Nuxt 3 服务端渲染优化与常见坑备忘

# Nuxt 3 服务端渲染优化与常见坑备忘 > 这是一份 Nuxt 3 服务端渲染（SSR）的实战备忘，记录高频优化手段和踩过的坑，随用随查。 ## ⚡ 渲染模式怎么选 - **SSR**：服务端渲染，SEO 友好，适合内容型站点 - **SSG**：构建时生成静态页，适合内容不常变的站点 - **SPA**：纯客户端，适合后台管理系统 ```js // nuxt.config.ts 全局设置 export default defineNuxtConfig({ ssr: true, routeRules: { "/about": { static: true }, // 该页 SSG "/admin/**": { ssr: false }, // 该路径 SPA "/api/**": { cors: true } } }) ``` > 按路由精细控制，比全局一刀切更灵活。 ## 📦 数据获取的三种方式 ```js // useFetch：服务端自动去重，推荐 const { data, pending, error } = await useFetch("/api/posts") // useAsyncData：更底层的控制 const { data } = await useAsyncData("key", () => $fetch("/api/data")) // $fetch：手动控制 const data = await $fetch("/api/data") ``` > useFetch 在 SSR 下会自动把数据序列化到客户端，避免重复请求。 ## 🚀 性能优化清单 ### 1. 组件懒加载 ```js // 动态组件，按需加载 const HeavyComp = defineAsyncComponent(() => import("~/components/HeavyChart.vue") ) ``` ### 2. 图片懒加载 ```html <NuxtImg src="/banner.jpg" loading="lazy" /> ``` ### 3. 减少 hydration 开销 ```html <!-- 纯静态内容跳过 hydration --> <div v-html="content" /> ``` ### 4. 缓存 API 响应 ```js routeRules: { "/api/posts": { swr: 300 } // 缓存 5 分钟 } ``` ## 🐛 常见坑备忘 > ⚠️ **坑1：window/document 在服务端未定义** 浏览器 API 只能在客户端用，包一层判断： ```js if (import.meta.client) { // 浏览器专属代码 localStorage.getItem("token") } ``` > ⚠️ **坑2：SSR 与客户端状态不一致导致 hydration 报错** 服务端渲染和客户端渲染结果要一致，随机数、时间戳要用固定种子。 > ⚠️ **坑3：环境变量泄露到客户端** ```js // 只有 NUXT_PUBLIC_ 前缀才会暴露到客户端 const secret = process.env.DB_PASSWORD // 仅服务端 const publicKey = useRuntimeConfig().public.apiBase // 客户端可见 ``` > ⚠️ **坑4：内存泄漏（服务端）** SSR 下模块级变量会在请求间共享，不要存请求级数据到模块作用域。 ## 📌 SEO 关键配置 ```js useSeoMeta({ title: "文章标题", description: "文章描述", ogImage: "/cover.jpg", }) // 动态路由的 SEO useHead({ title: () => `文章 - ${route.params.id}` }) ``` ## 🎯 部署注意 - SSR 需要 Node 运行时（不能纯静态托管） - 用 PM2 或 Docker 守护进程 - 设置合理的超时和内存限制 ```bash npm run build && node .output/server/index.mjs ``` 这份备忘持续补充，遇到新坑就记下来。