Nuxt.js 入门指南

如果你是一名 Vue 开发者,希望使用现代化工作流构建生产就绪的应用程序,Nuxt 4 为你提供了最快的前进路径。Nuxt 基于 Vue 3 构建,提供服务端渲染、混合渲染、基于文件的路由,以及适用于 Node、静态主机、无服务器和边缘环境的统一部署模型。

本新手友好教程将引导你使用当前的默认配置(如 Vue 3、Vite、TypeScript、组合式函数和 Nitro)创建你的第一个 Nuxt 4 应用程序。

什么是 Nuxt 4?为什么要使用它?

Nuxt 4 是 Nuxt 框架的当前主要版本,也是 2025 年末新 Vue 应用程序的推荐选择。它使用 Vue 3、Vite 和 Nitro 服务器引擎,提供快速的开发体验和灵活的生产架构。

与普通的 Vue 应用不同,Nuxt 4 开箱即用地提供 SSR,自动管理路由,在服务器和客户端上下文中处理数据获取,并附带可预测的、约定驱动的项目结构。

默认使用 Vue 3 + Vite

Nuxt 4 使用 Vite 作为其开发服务器和构建管道。这为你提供了近乎即时的热模块替换、快速的冷启动和高度优化的输出包。

Vue 3 组合式 API 和 TypeScript 优先设计提供了强大的类型推断、更好的代码组织和可预测的组件行为。

TypeScript,无需设置

TypeScript 支持是内置的。Nuxt 会根据你的项目目录、API 路由、中间件和组件自动生成类型。从你保存文件的那一刻起,你的 IDE 就能理解整个项目。

设置你的第一个 Nuxt 4 项目

使用 npm create nuxt@latest 安装

使用现代化的 Nuxt 4 CLI 创建新项目:

npm create nuxt@latest my-app
cd my-app
npm install
npm run dev

这将设置一个 Nuxt 4 项目,包含 TypeScript、Vite、Nitro 和自动导入的组合式函数,一切就绪。

目录结构概览

一个全新的 Nuxt 4 项目包括:

• pages/ — 基于文件的路由
• components/ — 自动导入的组件
• composables/ — 具有自动导入功能的可重用逻辑
• server/api/ — 由 Nitro 驱动的服务器端点
• public/ — 静态资源
• nuxt.config.ts — TypeScript 优先的配置

这种结构消除了设置开销,并保持一切可预测。

核心概念:页面、布局、组合式函数、自动导入

Nuxt 4 中的基于文件的路由

在 pages/ 目录中添加一个 Vue 文件,Nuxt 会自动创建路由:

<!-- pages/products/[id].vue -->
<script setup lang="ts">
const route = useRoute()
const id = route.params.id
</script>

<template>
  <h1>Product {{ id }}</h1>
</template>

动态路由参数使用方括号。

用于共享 UI 的布局

布局允许在页面周围使用共享包装器:

<!-- layouts/default.vue -->
<template>
  <AppHeader />
  <main><slot /></main>
  <AppFooter />
</template>

页面会自动使用默认布局。你可以使用 definePageMeta 切换布局。

组合式函数和自动导入

composables/ 目录中的组合式函数会在任何地方自动导入:

// composables/useCounter.ts
export const useCounter = () => {
  const count = useState('count', () => 0)
  const inc = () => count.value++
  return { count, inc }
}

无需导入语句,无需样板代码 — Nuxt 处理所有这些。

Nuxt 4 中的数据获取

使用 useFetch 进行 SSR 感知请求

useFetch 处理服务端数据加载和客户端水合:

<script setup lang="ts">
const { data: posts } = await useFetch('/api/posts')
</script>

这避免了服务器和客户端之间的重复获取,并与 Nitro 无缝配合。

通过 Nitro 创建 API 路由

在 server/api/ 中创建服务器端点:

// server/api/posts.get.ts
export default defineEventHandler(async () => {
  const posts = await $fetch('https://jsonplaceholder.typicode.com/posts')
  return posts.slice(0, 5)
})

Nitro 会自动为 Node、静态、无服务器或边缘部署优化这些端点。

使用 useAsyncData 实现自定义逻辑

如果你需要更多控制:

<script setup lang="ts">
const { data } = await useAsyncData('posts', () =>
  $fetch('/api/posts', { query: { limit: 5 } })
)
</script>

使用 Pinia 进行状态管理

对于应用级状态,Nuxt 4 使用 Pinia:

npm install @pinia/nuxt

启用它:

export default defineNuxtConfig({
  modules: ['@pinia/nuxt']
})

创建一个 store:

// stores/user.ts
export const useUserStore = defineStore('user', () => {
  const profile = ref(null)
  async function load() {
    profile.value = await $fetch('/api/user')
  }
  return { profile, load }
})

Pinia 直接与 Nuxt 的自动导入和 SSR 行为集成。

Nuxt 4 中的渲染模式

默认服务端渲染

Nuxt 4 在服务器上渲染页面以优化 SEO 和性能。你可以按路由调整渲染:

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/admin/**': { ssr: false },
    '/blog/**': { isr: 3600 }
  }
})

这使得混合应用能够混合使用 SSR、预渲染静态页面和动态的纯客户端部分。

静态生成和混合部署

如果需要,可以生成静态输出:

npm run generate

你可以预渲染营销页面,保持仪表板动态,并通过 Nitro 运行所有内容。

部署你的 Nuxt 4 应用程序

生产环境构建

npm run build

Nuxt 输出一个 .output/ 目录,包含服务器代码、客户端资源以及适用于每个主要托管平台的预设。

平台无关部署

部署到:

• Node 服务器
• 静态主机
• 无服务器平台(AWS、Vercel、Netlify)
• 边缘网络(Cloudflare Workers、Vercel Edge)

Nitro 会自动选择正确的预设。

结论

今天开始使用 Nuxt.js 意味着使用 Nuxt 4。
凭借默认的 SSR、混合渲染、自动导入、组合式函数以及支持部署的 Nitro,Nuxt 4 为你提供了构建快速、现代、可维护的 Vue 应用程序所需的一切。

从以下命令开始:

npm create nuxt@latest

—你就已经站在了正确的基础之上。

常见问题

Nuxt 4 中 useFetch 和 useAsyncData 有什么区别?

useFetch 是一个便捷的包装器,用于处理以 HTTP 为中心的请求和 SSR 水合。useAsyncData 是一个更底层的原语,用于自定义数据加载逻辑。两者都与 Nitro 无缝配合。

我可以在不使用 SSR 的情况下使用 Nuxt 4 吗?

可以。在 nuxt.config.ts 中设置 ssr: false 以获得 SPA 行为,或使用 routeRules 按路由配置 SSR。

Nuxt 4 如何处理 TypeScript?

Nuxt 4 为路由、API 处理程序、组件、组合式函数和服务器工具提供内置的类型生成,无需手动设置。