Nuxt 3 进阶实战教程

本教程深入讲解 Nuxt 3 的高级特性，包括状态管理、服务端 API 开发、中间件路由守卫、SEO 优化及部署。

1. 状态管理 (Pinia 集成)

Nuxt 3 推荐使用 Pinia 作为状态管理库。

安装:

npm install @pinia/nuxt pinia

配置 (nuxt.config.ts):

export default defineNuxtConfig({
  modules: ["@pinia/nuxt"],
});

创建 Store (stores/counter.ts):

import { defineStore } from "pinia";

export const useCounterStore = defineStore("counter", () => {
  const count = ref(0);
  const doubleCount = computed(() => count.value * 2);

  function increment() {
    count.value++;
  }

  return { count, doubleCount, increment };
});

在页面中使用 (pages/index.vue):

<template>
  <div>
    <p>Count: {{ counter.count }}</p>
    <p>Double: {{ counter.doubleCount }}</p>
    <button @click="counter.increment">Increment</button>
  </div>
</template>

<script setup>
import { useCounterStore } from "~/stores/counter";
const counter = useCounterStore();
</script>

2. 服务端路由 (Server Routes)

Nuxt 3 内置了 Nitro 引擎，可以在 server/ 目录下直接创建后端 API，无需额外的后端服务。

2.1 创建 API 接口

创建 server/api/hello.ts:

export default defineEventHandler((event) => {
  return {
    hello: "world",
  };
});

前端调用: await useFetch('/api/hello')

2.2 处理 POST 请求与参数

创建 server/api/submit.post.ts: (后缀 .post 限制仅接受 POST 请求)

export default defineEventHandler(async (event) => {
  // 获取请求体
  const body = await readBody(event);

  // 获取查询参数 ?name=nuxt
  const query = getQuery(event);

  return {
    receivedBody: body,
    queryParam: query,
  };
});

前端调用:

const { data } = await useFetch("/api/submit", {
  method: "POST",
  body: { foo: "bar" },
});

3. 路由中间件 (Middleware)

中间件用于在导航到特定路由之前运行代码（如权限验证）。

3.1 匿名中间件 (页面内)

<script setup>
definePageMeta({
  middleware: (to, from) => {
    console.log("正在导航到", to.path);
  },
});
</script>

3.2 命名中间件

创建 middleware/auth.ts:

export default defineNuxtRouteMiddleware((to, from) => {
  const isAuthenticated = false; // 模拟鉴权逻辑

  // 如果未登录，重定向到登录页
  if (!isAuthenticated && to.path !== "/login") {
    return navigateTo("/login");
  }
});

在页面中使用:

<!-- pages/dashboard.vue -->
<script setup>
definePageMeta({
  middleware: "auth",
});
</script>

3.3 全局中间件

创建 middleware/logger.global.ts (带 .global 后缀)，它将在每次路由切换时自动运行。

4. SEO 与 Meta 标签配置

Nuxt 3 对 SEO 非常友好，支持动态配置 Meta 标签。

4.1 使用 useSeoMeta (推荐)

<script setup>
useSeoMeta({
  title: "我的 Nuxt 应用",
  ogTitle: "我的 Nuxt 应用",
  description: "这是使用 Nuxt 3 构建的神奇网站。",
  ogDescription: "这是使用 Nuxt 3 构建的神奇网站。",
  ogImage: "https://example.com/image.png",
  twitterCard: "summary_large_image",
});
</script>

4.2 使用 useHead

<script setup>
useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} - 网站名称` : "网站名称";
  },
  meta: [{ name: "keywords", content: "Nuxt, Vue, SSR" }],
  script: [{ src: "https://third-party-script.com/analytics.js", body: true }],
});
</script>

5. 插件系统 (Plugins)

用于注入 Vue 实例或添加全局功能。

创建 plugins/error-handler.ts:

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, instance, info) => {
    console.error("全局错误捕获:", error);
    // 这里可以将错误上报到 Sentry 等服务
  };

  // 提供全局辅助函数
  return {
    provide: {
      formatDate: (date: Date) => date.toLocaleDateString(),
    },
  };
});

在组件中使用:

<script setup>
const { $formatDate } = useNuxtApp();
console.log($formatDate(new Date()));
</script>

6. 部署 (Deployment)

Nuxt 3 支持多种部署目标。

6.1 Node.js 服务器部署 (通用)

构建项目：

npm run build

这将在 .output/ 目录下生成构建产物。

运行服务：

node .output/server/index.mjs

可以使用 PM2 管理进程：

pm2 start .output/server/index.mjs --name "nuxt-app"

6.2 静态站点生成 (SSG)

如果你的站点是纯静态的（如博客、文档），可以生成静态文件。

配置 nuxt.config.ts:

export default defineNuxtConfig({
  ssr: true, // 默认就是 true
});

运行生成命令：

npm run generate

这将生成 .output/public 目录，你可以将其部署到任何静态托管服务 (GitHub Pages, Vercel, Netlify, Nginx)。