Nuxt 3 服务端渲染实战：从项目搭建到SEO优化

# Nuxt 3 服务端渲染实战：从项目搭建到SEO优化 ## 前言 Nuxt 3 是目前 Vue 生态中最主流的企业级全栈框架，它内置了服务端渲染(SSR)、静态站点生成(SSG)、文件路由、自动化导入等功能，极大降低了从零搭建项目的复杂度。本文从实际工作经验出发，梳理 Nuxt 3 项目从初始化到上线的完整流程，并分享一些容易忽略的坑点。 ## 一、项目初始化 Nuxt 3 官方推荐使用 npx nuxi init 创建项目： npx nuxi@latest init my-nuxt-app cd my-nuxt-app npm install 安装完成后运行 npm run dev，访问 localhost 的 3000 端口即可看到默认页面。 需要注意的是，Nuxt 3 默认使用 Vite 作为构建工具，如果你有 Webpack 依赖的需求，可以在 nuxt.config.ts 中切换构建工具： export default defineNuxtConfig({ builder: "webpack" }) 不过大多数情况下 Vite 已经足够好用，切换前先确认是否真的有这个必要。 ## 二、自动导入机制 Nuxt 3 的一个核心特性是自动导入。你放在 composables 目录下的函数、components 目录下的组件、utils 目录下的工具函数，都不需要手动 import 就可以直接在模板和 script 中使用。 这听起来很美好，但有几个注意事项： - 自动导入的范围仅限于约定目录，自定义目录需要在 nuxt.config.ts 中通过 components 和 imports 选项显式声明 - composables 中导出的函数如果名字前不带 use 前缀，可能会导致类型推断出问题 - 自动导入是在构建时处理的，TS 类型支持需要配合 nuxi prepare 生成类型文件 建议在项目根目录的 .gitignore 中加入 .nuxt 目录，类型文件会在每次构建时自动生成。 ## 三、路由系统 Nuxt 3 使用文件路由系统，pages 目录下的文件自动对应路由： - pages 目录下的 index.vue 对应根路径 - pages 目录下的 about.vue 对应关于页面路径 - pages 目录下的 blog 文件夹下的中括号包裹的 id.vue 文件对应 blog 下的动态路径 动态路由的参数通过 useRoute 获取： const route = useRoute() const articleId = route.params.id 嵌套路由通过创建与父路由同名的目录实现： - pages 目录下的 parent.vue 使用 NuxtPage 组件作为子路由的出口 - pages 目录下的 parent 文件夹下的 child.vue 对应父路由加子路由的路径 ## 四、数据获取 Nuxt 3 提供了四个数据获取函数，理解它们的区别是掌握 SSR 的关键： **useFetch**：基于 ofetch 的封装，最常用的数据获取方式，自动处理 SSR 场景下的数据序列化和客户端恢复 const { data, pending, error, refresh } = await useFetch("/api/posts") **useAsyncData**：底层 API，适合需要对数据做复杂处理的场景 const { data } = await useAsyncData("posts", () => { return fetchPosts() }) **useLazyFetch** 和 **useLazyAsyncData**：不阻塞页面渲染的数据获取，适合加载非关键内容 一个常见的坑：useFetch 的第二个 key 参数非常重要。两个不同页面如果使用了相同的 key，会导致数据互相覆盖。确保每个 useFetch 调用都有唯一的 key。 ## 五、SEO 优化 SSR 框架的核心优势之一就是 SEO 友好。Nuxt 3 提供了两种方式设置页面 Meta 信息： **方式一：在组件中使用 useHead** useHead({ title: "文章标题", meta: [ { name: "description", content: "文章简介描述" }, { property: "og_title", content: "OpenGraph 标题" } ] }) **方式二：使用 useSeoMeta（推荐）** useSeoMeta({ title: "文章标题", ogTitle: "OpenGraph 标题", description: "文章简介描述", ogDescription: "OpenGraph 描述" }) useSeoMeta 是 useHead 的 SEO 专用封装，代码更简洁，而且大部分 SEO 工具能正确识别。 对于图片 SEO，不要忘记给 NuxtImg 组件设置 alt 属性，搜索引擎依赖 alt 文本来理解图片内容。 ## 六、部署上线 Nuxt 3 支持多种部署模式： **SSR 服务端部署**：先运行 npm run build，然后执行 node .output 目录下的 server 文件夹中的 index.mjs 文件启动服务。需要 Node.js 18 以上版本。 **静态站点生成**：nuxt.config.ts 中设置 ssr 为 true 且 target 为 static，运行 npm run generate 生成纯静态文件，可直接部署到 Nginx 或 CDN。 **边缘计算平台**：Nuxt 3 原生支持 Cloudflare Pages、Vercel、Netlify 等平台的 Nitro 预设，一条命令即可构建适配产物。 生产环境安全注意事项： - 检查 .env 文件是否已加入 .gitignore，生产密钥绝不能提交到版本库 - runtimeConfig 中的 public 字段是公开的，只有非 public 字段才是服务端安全变量 - 通过 Nuxt 的 security 模块添加 CSP 头，防止 XSS 攻击 - 生产构建前运行 npm audit 检查依赖漏洞 ## 七、常见踩坑记录 **坑一：客户端和服务端的环境差异** 在 SSR 模式下，代码会先在服务端执行一次再在客户端执行一次。使用了 window、document 等浏览器特有 API 的代码需要在客户端专属生命周期（如 onMounted）或使用 process.client 判断后才能调用。 **坑二：第三方库不支持 SSR** 有些图表库和地图库依赖浏览器 API。Nuxt 提供 ClientOnly 组件包裹这些库： ClientOnly 组件内部的内容只在客户端渲染，服务端不执行 **坑三：Pinia 状态持久化** 如果 Pinia 使用了持久化插件，需要确认插件兼容 SSR。建议使用 pinia-plugin-persistedstate 的 nuxt 版本，它能正确处理服务端和客户端的状态同步。 **坑四：中间件误用导致无限重定向** 在全局中间件中做路由重定向时，注意不要将目标路径也纳入中间件的触发范围，否则会导致无限循环。用条件判断明确哪些路径需要导航守卫。 ## 八、总结 Nuxt 3 是目前 Vue 生态中功能最完整的全栈框架，但功能丰富也意味着学习曲线不低。核心要点有三个： 1. 理解 SSR 的执行模型，分清服务端和客户端代码的边界 2. 善用 useAsyncData 和 useFetch 的数据缓存和 key 管理 3. SEO 信息用 useSeoMeta 统一管理，尽早配置 遇到问题时，先检查官方文档和 GitHub Issues，大部分常见问题都有现成的解决方案。Nuxt 的社区活跃度很高，一般不会有长时间无解的问题。 如果你正在从 Nuxt 2 迁移，建议先通读迁移指南，因为 2 到 3 是全面重写，不能简单对比升级。