故障排查
解决运行 Nuxt 模板时的常见问题。
先判断故障属于安装/构建、运行时配置、数据库、认证、提供商回调、内容还是客户端 渲染。服务端日志与浏览器控制台应同时查看；Nitro 错误往往只出现在终端。
安装与构建
| 现象 | 常见原因 | 安全处理 |
|---|---|---|
nuxt: command not found | 没有用 pnpm 安装依赖 | 使用 Node 22、启用 Corepack，再运行 pnpm install |
缺少 .nuxt 类型/自动导入 | nuxt prepare 未运行或生成目录过期 | 运行 pnpm postinstall；必要时只删除生成的 .nuxt 后重跑 |
| 开发正常、构建失败 | 服务端/客户端边界、运行时变量或内容错误 | 运行 pnpm eslint . 与 pnpm build，优先处理第一条错误 |
| 组件无法解析 | 自动导入名称或目录配置错误 | 检查 nuxt.config.ts 的 components/shadcn；归属不明确时显式导入 |
不要照搬 Next.js 修复：本模板没有 App Router、proxy.ts、next/font 或 Next
route handler。
PostgreSQL 与 Drizzle
| 现象 | 检查 | 处理 |
|---|---|---|
| 连接被拒绝/认证失败 | NUXT_DATABASE_URL、数据库进程、SSL/连接池 URL | 在 Nuxt 外测试同一连接串；serverless 使用提供商的 pooled URL |
| 表不存在 | server/database/migrations、迁移历史 | 对目标数据库运行 npx drizzle-kit generate 再 migrate |
| Drizzle 找不到配置 | server/database/drizzle/drizzle.config.ts | 若 CLI 需要，显式传配置路径，并从项目根目录执行 |
| schema 修改无效果 | server/database/index.ts 的导出 | 确保新 schema 可达，重新生成并检查 SQL，再迁移 |
不要对猜测出来的生产 URL 执行迁移。只打印数据库 host（不要打印凭据），先备份， 并检查生成 SQL。参见数据库。
Better Auth 与 OAuth
**重定向循环、session 401 或 cookie 异常：**确认 NUXT_PUBLIC_BASE_URL 与浏览器
origin 完全相同，包括协议和端口。server/utils/auth.ts 用它生成 baseURL 与
trustedOrigins。局域网/开发额外来源通过逗号分隔的
NUXT_AUTH_EXTRA_TRUSTED_ORIGINS 添加，生产环境不要保留宽泛来源。
**OAuth 回调失败：**设置完整的 client ID/secret，并注册：
<NUXT_PUBLIC_BASE_URL>/api/auth/callback/github
<NUXT_PUBLIC_BASE_URL>/api/auth/callback/google提供商控制台 URL、公开 base URL 与浏览器地址必须一致。未配置某提供商时，应 隐藏按钮，而不是保留必然失败的入口。参见认证。
Resend 邮件
| 现象 | 检查 |
|---|---|
| “API key not set” | 运行时存在服务端 NUXT_RESEND_API_KEY |
| Resend 拒绝发件人 | websiteConfig.mail.fromEmail 使用已验证域名 |
| 联系表单没有收件人 | websiteConfig.mail.supportEmail 已设置且有人值守 |
| 注册无法完成 | 强制验证邮件必须能够投递 |
| 中文认证邮件仍是英文 | 认证调用目前未传 locale，需要显式传入 |
同时检查应用日志与 Resend event dashboard。参见邮件。
支付与 webhook
先确认公开路由和方法完全一致：
- Creem：
POST /api/payment/notify/creem，原始 body，creem-signatureheader，NUXT_CREEM_WEBHOOK_SECRET。 - ZPay：
GET /api/payment/notify/zpay，带签名 query，NUXT_ZPAY_MERCH_KEY。
Creem 返回 401 表示签名缺失/无效，500 可能是 webhook secret 未配置。验 HMAC
前不要解析再序列化原始 body。ZPay 的校验或处理抛错时返回 fail。还要检查各
提供商 notify URL、公网 HTTPS 可达性、产品 ID 与 NUXT_CREEM_SERVER_IDX
（0 生产、1 测试）。参见支付。
AI Gateway 与 Replicate
| 现象 | 常见原因/处理 |
|---|---|
| “Missing AI Gateway API key” | 设置服务端 NUXT_AI_GATEWAY_API_KEY 并重启 |
| 模型/搜索控件无效果 | 当前只是 UI；服务端固定使用 openai/gpt-5.2 |
| AI 请求返回 401 | 登录；仅在明确演示时设置 NUXT_PUBLIC_AI_PUBLIC_DEMO=true |
| provider “not configured” | 设置 NUXT_REPLICATE_API_TOKEN；有 token 才注册 Replicate |
| 媒体轮询一直不结束 | 检查 Replicate prediction、模型输入映射、超时与提供商状态 |
| 任务成功但 URL 后来失效 | 将结果复制到持久化对象存储，不要依赖提供商 URL |
模型 schema 会变化；更换 Replicate 模型时重新核对输入字段。参见 AI 聊天与AI 媒体。
Nuxt Content 与国际化
**页面找不到：**检查 content.config.ts 的语言集合、文件路径、必填 title，
以及 useDocContent 计算的路径。中文文档/博客集合虽已配置，目前仍为空。
**页面存在但侧栏没有：**更新 app/config/docs-sidebar-config.ts；侧栏是手工维护。
语言错误或博客混合：prefix_except_default 表示英文无前缀、中文使用 /zh。
使用 NuxtLinkLocale/useLocalePath。当前博客列表查询所有语言集合；加入中文
博客时应限制为当前语言。
**草稿可见：**schema 虽接受 published，当前查询并未过滤，需显式添加条件。
参见内容与
国际化。
主题 hydration
若服务端 HTML 与 hydration 后的主题/图标不一致，不要在 SSR 中直接按浏览器
storage 分支。使用 useColorMode()，并将依赖客户端偏好的内容包在
<ColorScheme> 中。保持 classSuffix: ""、.dark CSS 变量与
storageKey: "theme" 一致。参见主题。
Docker 与 Nitro
| 现象 | 检查 |
|---|---|
| 容器启动但无法访问 | PORT=80、HOST=0.0.0.0 与端口映射 |
缺少 server/index.mjs | 运行 pnpm build，按 Dockerfile 复制 .output 内容 |
| 运行时 secret 为 undefined | 把 NUXT_* 注入运行中的容器，而不只是构建阶段 |
| 部署后上传消失 | public/uploads 是非持久本地目录，应迁移 S3/R2/Blob |
先在本地用 node .output/server/index.mjs 启动构建产物，再排查平台。参见
部署。
Nuxt 常见坑
~/@指向app/，~~/@@指向项目根，#shared指向shared/。- 服务端 secret 放在
runtimeConfig根并使用NUXT_*；浏览器可见值放在runtimeConfig.public并使用NUXT_PUBLIC_*。 - 缺少对应 Nuxt 前缀的环境变量不会覆盖 runtime config。
pathPrefix: false会改变自动导入组件名；文档组件是 global，多数功能组件不是。- 页面位于
(dashboard)并不会自动受保护。页面仍须声明auth（必要时加admin）中间件，每个 API 还要独立校验认证/角色。
仍未解决？
把问题缩小到一个路由，记录请求方法/路径、响应状态、第一段服务端堆栈、当前 运行方式（dev/Nitro/Docker），以及哪些必需变量存在——不要记录变量值。这样， “Nuxt 坏了”通常会迅速变回一个朴素得令人安心的普通 bug。