问题排查
定位常见的安装、集成、内容与部署故障。
架构说明： 本页的 Web 配置适用于独立产品。作为 Unified Platform Host 时，还需应用服务端配置中的原生 Origin、OAuth audience、App API、Webhook、存储和通知边界。
先确认失败边界属于 Vite 构建、Worker runtime、D1、provider API 还是浏览器，再
一次只修改一个配置平面。本地从 .env 可用，不代表生产 Worker 已配置。
首轮检查
pnpm check
pnpm test
pnpm build然后确认当前 origin、Worker 日志（pnpm wrangler tail），以及问题发生在本地还是
远端。不要把远端 migration 或 secret 轮换当作猜测式第一步。
安装、Vite 与路由
| 现象 | 可能原因 | 安全修复 |
|---|---|---|
| 找不到命令/script | 包管理器错误或使用了不存在的 script | pnpm install；只用 package.json 中的 dev、build、preview、deploy |
fumadocs-mdx:collections/* import 失败 | .source 生成内容过期 | 停止 dev，必要时只删除生成的 .source，重新 pnpm dev/pnpm build |
| 路由文件存在但应用找不到 | 路由树过期或文件命名不符合约定 | 重启 Vite，并修正 src/routes 下文件 |
| 路由树修改消失 | 手改了 src/routeTree.gen.ts | 撤销手改，修改 route file；不要编辑生成树 |
Creem 的 node:crypto/Buffer 报错 | 缺少 nodejs_compat | 恢复 wrangler.jsonc 的 compatibility flag 并重建 |
Worker 配置与 binding
DB 与 UPLOADS 来自 wrangler.jsonc binding。若 undefined，核对 binding 名称/
资源，并在请求期间通过 cloudflare:workers 的 env 读取。不要从 process.env
读取它们，也不要在模块初始化时捕获。
| 现象 | 可能原因 | 安全修复 |
|---|---|---|
| 本地可用，部署后 secret 缺失 | .env/.dev.vars 不会上传 | pnpm wrangler secret put NAME 后重新部署 |
BETTER_AUTH_URL 仍是 localhost/旧域名 | 生产非 secret var 过期 | 把 wrangler.jsonc vars 改为准确部署 origin |
| 产品/模型/demo 改动不生效 | 构建后才修改 VITE_* | 在构建环境设置并重建/部署 |
| D1/R2 资源错误 | 各环境 binding ID/名称不一致 | 对照 wrangler.jsonc、Cloudflare 资源与部署配置 |
D1 与 Drizzle
| 现象 | 原因 | 修复 |
|---|---|---|
| 本地注册提示表不存在 | Miniflare D1 未执行 migration | pnpm db:migrate:local |
| 生产 schema 过期 | 只执行了本地 migration | 备份并审查后运行 pnpm db:migrate |
| SQL 与 schema 不符 | 改 schema 后未重新生成 | pnpm db:generate，审查 drizzle/，先本地后远端 |
| Drizzle 要求 PostgreSQL/连接 URL | 使用了其他模板说明 | 使用 D1/SQLite 与 DB binding；没有 DATABASE_URL |
建议的 drizzle-kit push 失败/绕过历史 | 工作流错误 | 使用生成并提交的 SQL migration，不要使用 drizzle-kit push |
| Transaction API 失败 | D1 不支持交互式 transaction | 使用 db.batch()/幂等语句并处理部分失败 |
Better Auth 与 OAuth
- **登录循环或 cookie 失败：**确保
BETTER_AUTH_URL与公开 scheme/host/port 完全 一致，生产使用 HTTPS，代理不会意外改变 origin。 - **OAuth callback mismatch：**provider callback 为
<origin>/api/auth/callback/github或/google；域名变化时同步更新。 - **受保护 API 仍可访问：**页面
beforeLoad不够，每个敏感 handler 都要重查 session/role。 - **本地注册无法完成：**执行本地 D1 migration 并配置 Resend；或只为明确的本地 开发有意识调整验证行为。
Resend 与联系表单
无邮件时检查 RESEND_API_KEY、发件域名验证与
websiteConfig.mail.fromEmail，查看 Resend 返回错误和控制台。当前
sendEmail() 返回结构化失败，但 auth/contact caller 并非都传播它，所以成功页面
不代表已投递。增加不含收件人或正文的安全日志与监控。
Creem 支付
| 现象 | 检查项 |
|---|---|
| Checkout 产品错误/缺失 | VITE_CREEM_PRODUCT_PRO_MONTHLY/_PRO_YEARLY/_LIFETIME；改后重建 |
| API 命中错误环境 | CREEM_SERVER_IDX 必须与 API key 配套 |
| Webhook 签名失败 | 原始 payload、CREEM_WEBHOOK_SECRET 与 provider signature header |
| 支付成功但 D1 未更新 | Webhook 必须是 /api/payment/notify/creem，远端 migration 已执行，并检查 Worker 日志 |
| Dashboard 显示无关订阅 | 订阅页仍是 mock；连接 /api/user/subscription |
R2 上传
- **
UPLOADSundefined：**创建并绑定 bucket，保持请求期env.UPLOADS访问。 - **上传 401：**接口要求 Better Auth session。
- **上传 400：**发送名为
files的FormData；当前最多五个、单个 5 MB，MIME 为image/*。 - **读取 404：**确认返回 key 位于同一个本地/远端 bucket。
- **接受不安全内容：**MIME metadata 不等于签名校验；增加解码/magic-byte 与尺寸策略。
OpenAI 与 Replicate
| 现象 | 可能原因/修复 |
|---|---|
| Chat 立即返回 400 | 检查 OPENAI_API_KEY、body 结构与模型可用性，安全查看 Worker 错误 |
| 搜索开关没有 source | 它选择 search-preview model，不是自定义 tool；只有模型返回时才有 source |
| 媒体提示 provider 未配置 | 本地/生产设置 REPLICATE_API_TOKEN，重启/部署 |
| 轮询不结束 | 检查 Replicate task；把 canceled 当终态，并核对输出解析/模型映射 |
| 输出之后消失 | Provider URL 未持久化；把成功结果复制到 R2 |
| AI 账单异常 | 公开接口尚无限额/限流；开放前加固 |
内容与 i18n
- **文档不在侧栏：**加入正确
meta.json，并确认 MDX 存在。 - **中文文档缺失/fallback：**添加
slug.zh.mdx；当前模板多数文档仍只有英文。 - **
/en/*重定向：**这是预期行为，默认英文 canonical 不带前缀；中文用/zh/*。 - **切换语言回首页：**当前
LanguageToggle会去所选语言根路径；如需保留页面， 改为 localize 当前路径。 - **博客/法律正文未翻译：**这些 loader 当前在多语言路由间共用一套 MDX。
仍无法解决
记录最小复现、准确命令/请求、本地或部署环境、脱敏错误、Worker 日志时间与相关
配置平面。不要公开 .env、Wrangler secret、OAuth 凭据、webhook payload 或用户
数据。