Nuxt 3 静态生成（generate）下服务端 API 调用失效的解决方案

Nuxt 3 使用 nuxt generate 构建静态站点时，server/ 目录中的 API 路由不会被部署，因其依赖 Node.js 服务端运行环境；若需调用服务端逻辑，必须改用服务端渲染模式（SSR）并执行 nuxt build + nuxt preview。

nuxt 3 使用 `nuxt generate` 构建静态站点时，`server/` 目录中的 api 路由不会被部署，因其依赖 node.js 服务端运行环境；若需调用服务端逻辑，必须改用服务端渲染模式（ssr）并执行 `nuxt build` + `nuxt preview`。

在 Nuxt 3 中，server/ 目录（如 server/api/home.ts）定义的是服务端专属 API 路由，它们仅在具备 Node.js 运行时的环境下（如 SSR 或服务端渲染模式）才可被访问。而 nuxt generate 命令会将应用预渲染为纯静态 HTML/CSS/JS 文件，完全剥离服务端能力——此时所有 /api/* 请求在浏览器中发起时，实际是向静态资源服务器（如 Nginx、Vercel Static Hosting 或 dist/ 目录）发起的，自然返回 404。

✅ 正确做法：启用 SSR 并使用构建+预览流程

确保 nuxt.config.ts 中未禁用 SSR（默认即启用）：

export default defineNuxtConfig({
// 不要设置 ssr: false
// 若需强制 SSR，可显式声明（非必需）：
ssr: true,
})

替换构建命令：

# ❌ 错误：生成静态文件（无 server API）
npm run generate

✅ 正确：构建服务端就绪的应用

npm run build

启动本地预览服务（模拟生产 Node 服务）

npm run preview

运行后，`http://localhost:3000/api/home` 将正常响应，前端 `useFetch('/api/home')` 也可成功获取数据。

⚠️ 注意事项：  
- 静态部署平台（如 GitHub Pages、Netlify Static、Vercel Static）**不支持 `server/` API**，若必须使用此类平台，请将 API 调用改为直连真实后端（绕过 Nuxt 服务端代理），或改用 Vercel Serverless Functions / Netlify Edge Functions 等支持服务端逻辑的方案；  
- 若仍需部分静态化 + 部分 SSR，可结合 `routeRules` 配置动态路由（如 `routeRules: { '/api/**': { ssr: true } }`），但前提是整体以 `ssr: true` 模式构建；  
- `useRuntimeConfig` 中的 `public` 属性可在客户端安全使用，但 `private` 配置（如敏感 token）**仅限服务端访问**，切勿在 `defineEventHandler` 外暴露。

总结：`server/` 是 Nuxt 3 的服务端能力边界，与部署模式强绑定。选择 `generate` 即放弃服务端路由；选择 `build` + `preview`（或托管至支持 Node 的平台如 Vercel、Node 服务器）才能完整发挥其优势。