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

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

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.