Nuxt 3：全栈 Vue 框架

7.1 Nuxt 3 是什么？

Nuxt 3 是基于 Vue 3 的全栈框架，在 Vue 的基础上提供了：

• 服务端渲染（SSR）：更快的首屏加载，更好的 SEO
• 文件系统路由：自动根据文件结构生成路由，无需手动配置
• 自动导入：组件、Composables、工具函数自动按需引入
• 全栈能力：server/ 目录可以编写 API 路由，无需独立后端
• 混合渲染：每个路由可以独立配置 SSR/SSG/CSR 等渲染模式

# 使用官方脚手架
npx nuxi@latest init my-nuxt-app
cd my-nuxt-app
npm install
npm run dev   # http://localhost:3000

7.2 项目目录结构

my-nuxt-app/
├── .nuxt/              # 自动生成，勿手动修改
├── assets/             # 需要构建工具处理的静态资源（图片、字体、CSS）
├── components/         # Vue 组件（自动导入）
│   ├── AppHeader.vue
│   └── ui/             # 子目录组件名：UiButton
│       └── Button.vue
├── composables/        # Composables（自动导入）
│   └── useCounter.ts
├── layouts/            # 布局组件
│   ├── default.vue     # 默认布局
│   └── auth.vue
├── middleware/         # 路由中间件
│   └── auth.ts
├── pages/              # 页面（自动生成路由）
│   ├── index.vue       # /
│   ├── about.vue       # /about
│   └── users/
│       ├── index.vue   # /users
│       └── [id].vue    # /users/:id（动态路由）
├── plugins/            # Nuxt 插件（在 Vue 实例创建前运行）
├── public/             # 直接提供的静态资源（无需构建）
├── server/             # 服务端代码（仅在服务器运行）
│   ├── api/
│   │   └── users.get.ts  # GET /api/users
│   ├── middleware/
│   └── utils/
├── utils/              # 工具函数（自动导入）
├── app.vue             # 应用根组件
├── nuxt.config.ts      # Nuxt 配置
└── package.json

7.3 文件系统路由

Nuxt 3 自动将 pages/ 目录下的 Vue 文件转换为路由，无需手动配置 Vue Router：

文件路径	生成的路由	说明
pages/index.vue	/	首页
pages/about.vue	/about	普通页面
pages/users/index.vue	/users	目录索引页
pages/users/[id].vue	/users/:id	动态路由
pages/users/[id]/posts.vue	/users/:id/posts	嵌套动态路由
pages/[...slug].vue	/:slug(.*)*	Catch-all（404 等）
pages/blog/[[page]].vue	/blog 或 /blog/2	可选参数

<script setup lang="ts">
// Nuxt 自动导入 useRoute，无需 import
const route = useRoute()
const id = route.params.id

// useFetch 也是自动导入的（Nuxt 内置）
const { data: user } = await useFetch(`/api/users/${id}`)

// 定义页面元信息（SEO）
useHead({
  title: () => user.value?.name ?? '用户详情',
  meta: [{ name: 'description', content: '用户个人主页' }]
})
</script>

7.4 自动导入（Auto-imports）

Nuxt 3 的一大特色是自动导入：无需手动 import，就可以直接使用以下内容：

7.5 Layouts 布局系统

<template>
  <div>
    <AppHeader />  <!-- 自动导入 -->
    <main>
      <slot />  <!-- 页面内容渲染到这里 -->
    </main>
    <AppFooter />
  </div>
</template>

<script setup>
// 指定使用 auth 布局（layouts/auth.vue）
definePageMeta({
  layout: 'auth'
})
</script>

7.6 Server API 路由

server/api/ 目录下的文件会自动成为 API 端点，基于 H3（轻量 HTTP 框架）：

// GET /api/users
export default defineEventHandler(async (event) => {
  // 只在服务器运行，可以安全地访问数据库
  const db = useDatabase()
  const users = await db.query('SELECT * FROM users')
  return users  // 自动序列化为 JSON
})

// DELETE /api/users/:id
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  const body = await readBody<{ reason: string }>(event)

  // 验证身份（使用请求头）
  const token = getHeader(event, 'authorization')
  if (!token) throw createError({ statusCode: 401, message: '未授权' })

  await deleteUser(id)
  return { success: true }
})

文件名	HTTP 方法	URL
server/api/users.get.ts	GET	/api/users
server/api/users.post.ts	POST	/api/users
server/api/users/[id].get.ts	GET	/api/users/:id
server/api/users/[id].delete.ts	DELETE	/api/users/:id
server/api/users/index.ts	所有方法	/api/users

7.7 nuxt.config.ts 配置

export default defineNuxtConfig({
  // 开发工具（开发环境自动启用 Vue DevTools）
  devtools: { enabled: true },

  // 模块（扩展 Nuxt 功能）
  modules: [
    '@nuxtjs/tailwindcss',
    '@pinia/nuxt',
    '@nuxt/image',
    'nuxt-auth-utils'
  ],

  // CSS 全局文件
  css: ['~/assets/css/main.css'],

  // 运行时配置（区分公开和私有）
  runtimeConfig: {
    // 私有：仅服务端可用
    dbUrl: process.env.DATABASE_URL,
    jwtSecret: process.env.JWT_SECRET,
    // 公开：客户端和服务端都可用
    public: {
      apiBase: '/api',
      appName: '我的应用'
    }
  },

  // TypeScript 配置
  typescript: {
    strict: true
  }
})

7.5 Nuxt 4 迁移预览

Nuxt 4（计划与 Nuxt 3.x 并行提供兼容模式）带来了几个重要改变，可以提前在 Nuxt 3 中启用测试：

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4  // 提前测试 Nuxt 4 行为
  },
  // Nuxt 4 下 app/ 目录作为应用根目录
  // pages/ → app/pages/
  // composables/ → app/composables/
  // components/ → app/components/
})

7.6 Nuxt DevTools

Nuxt DevTools 是官方提供的可视化调试工具，在开发模式下通过浮动按钮打开。它提供了组件树分析、路由列表、模块状态、性能分析等功能，极大提升了 Nuxt 项目的调试体验。

export default defineNuxtConfig({
  devtools: {
    enabled: true,     // 启用 DevTools（开发模式默认已启用）
    timeline: {
      enabled: true    // 启用时间线功能，追踪异步操作
    }
  }
})