frontend

Nuxt.js 完全指南：Vue 全栈框架的 SSR、SSG、API 路由与部署实践

Nuxt.js 3 深度实践：文件系统路由、SSR/SSG/ISR 渲染模式、API 路由（Server Routes）、useFetch/useAsyncData 数据获取、中间件与插件、SEO 与 Meta 管理、Nitro 服务端引擎、自动导入、部署到 Vercel/Netlify/Node.js。

Leeting Yan 2026-08-01 3 分钟阅读 1026 字

Nuxt.js 是基于 Vue 的全栈框架，提供文件系统路由、服务端渲染（SSR）、静态生成（SSG）、API 路由、自动导入等开箱即用的能力。Nuxt 3 基于 Nitro 服务端引擎，支持 multi-provider 部署（Node/Vercel/Netlify/Deno/Workers），是 Vue 生态构建生产级全栈应用的首选方案。

一、Nuxt 3 核心特性速览

特性	说明
文件系统路由	`pages/index.vue` → `/`，`pages/users/[id].vue` → `/users/:id`
渲染模式	SSR（默认）、SSG（prerender）、CSR（spa）、ISR（混合）
API 路由	`server/api/.ts` → `/api/`，直接写后端接口
自动导入	组件/Composables/工具函数无需 import
Nitro 引擎	统一服务端运行时，支持 15+ 部署目标
TypeScript	原生支持，类型自动生成
Module 生态	300+ 官方和社区模块

二、文件系统路由

2.1 基础路由

pages/
├── index.vue           # /
├── about.vue           # /about
└── users/
    ├── index.vue       # /users
    └── [id].vue        # /users/:id

2.2 动态路由

<!-- pages/users/[id].vue -->
<script setup>
const route = useRoute()
const { data: user } = await useFetch(`/api/users/${route.params.id}`)
</script>

<template>
  <div>
    <h1>{{ user?.name }}</h1>
  </div>
</template>

2.3 嵌套路由

pages/
├── parent.vue          # 父布局（必须有 <NuxtPage />）
└── parent/
    ├── child.vue       # /parent/child
    └── index.vue       # /parent

三、数据获取

3.1 useFetch：SSR 友好的数据获取

<script setup>
// 服务端 + 客户端都能正确 hydration
const { data: posts, pending, error, refresh } = await useFetch('/api/posts', {
  lazy: false,           // 阻塞渲染（默认）
  server: true,          // 服务端获取
  default: () => [],     // 默认值
})

// 手动刷新
const handleRefresh = () => refresh()
</script>

3.2 useAsyncData：更精细控制

<script setup>
const { data, pending } = await useAsyncData('posts', () =>
  $fetch('/api/posts')
)
</script>

3.3 API 路由

// server/api/posts.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)  // 读取查询参数
  const posts = await fetchPosts(query.limit)
  return posts
})

// server/api/posts.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const post = await createPost(body)
  return post
})

四、渲染模式

模式	配置	特点
SSR（默认）	无需配置	首屏快，服务端渲染
SSG	`nuxt generate`	预渲染为静态 HTML，CDN 友好
CSR	`ssr: false`	纯客户端，SPA 体验
ISR	`routeRules`	增量静态再生，按需更新
Hybrid	`routeRules`	不同路由不同渲染模式

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },           // 首页静态生成
    '/blog/**': { isr: 60 },            // ISR，60 秒重新验证
    '/admin/**': { ssr: false },        // 管理后台纯 CSR
    '/api/**': { cors: true },          // API 路由允许跨域
  },
})

五、中间件与插件

5.1 路由中间件

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const auth = useAuthStore()
  if (!auth.isLoggedIn) {
    return navigateTo('/login')
  }
})

// pages/dashboard.vue
<script setup>
definePageMeta({
  middleware: ['auth'],
})
</script>

5.2 服务端插件

// server/plugins/auth.ts
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    // 每个请求都执行
    const token = getHeader(event, 'authorization')
    event.context.auth = parseToken(token)
  })
})

六、部署

6.1 Vercel

npx nuxi build  # 自动识别 Nitro preset

6.2 Node.js 服务器

npx nuxi build
node .output/server/index.mjs

常见问题（FAQ）

Nuxt 3 和 Nuxt 2 有什么区别？

Vue 3 + TypeScript 原生支持
Vite 替代 Webpack（开发速度提升 10 倍）
Nitro 替代 Nuxt 2 的服务端引擎
Composition API 默认
自动导入所有内容

Nuxt 和 Next.js 怎么选？

Vue 生态 → Nuxt
React 生态 → Next.js
两者功能对等，生态决定选择

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页