C3 常见陷阱

# C3 故障排除 ## 部署问题 ### 占位符 ID **错误：** "Invalid namespace ID" **修复：** 将 wrangler.jsonc 中的占位符替换为真实 ID： bash npx wrangler kv namespace create MY_KV # 获取真实 ID ### 身份验证 **错误：** "Not authenticated" **修复：** `npx wrangler login` 或设置 `CLOUDFLARE_API_TOKEN` ### 名称冲突 **错误：** "Worker already exists" **修复：** 修改 wrangler.jsonc 中的 `name` ## 平台选择 | 需求 | 平台 | |------|----------| | Git 集成，分支预览 | `--platform=pages` | | Durable Objects, D1, Queues | Workers (默认) | 平台选错？使用正确的 `--platform` 标志重新创建。 ## TypeScript 问题 **"Cannot find name 'KVNamespace'"** bash npm run cf-typegen # 重新生成类型 # 在编辑器中重启 TS 服务器 **配置更改后缺少类型：** 重新运行 `npm run cf-typegen` ## 包管理器 **多个锁文件导致问题：** bash rm pnpm-lock.yaml # 如果使用 npm rm package-lock.json # 如果使用 pnpm ## CI/CD **CI 在提示处挂起：** bash npm create cloudflare@latest my-app -- --type=hello-world --lang=ts --no-git --no-deploy **CI 中的身份验证：** yaml env: CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} ## 框架特定问题 | 框架 | 问题 | 修复 | |-----------|-------|-----| | Next.js | create-next-app 失败 | `npm cache clean --force`, 重试 | | Astro | 缺少适配器 | 安装 `@astrojs/cloudflare` | | Remix | 模块错误 | 更新 `@remix-run/cloudflare*` | ## 兼容性日期 **"Feature X requires compatibility_date >= ..."** **修复：** 将 wrangler.jsonc 中的 `compatibility_date` 更新为今天的日期 ## Node.js 版本 **"Node.js version not supported"** **修复：** 安装 Node.js 18+ (`nvm install 20`) ## 快速参考 | 错误 | 原因 | 修复 | |-------|-------|-----| | Invalid namespace ID | 占位符绑定 | 创建资源，更新配置 | | Not authenticated | 未登录 | `npx wrangler login` | | Cannot find KVNamespace | 缺少类型 | `npm run cf-typegen` | | Worker already exists | 名称冲突 | 修改 `name` | | CI 挂起 | 缺少标志 | 添加 --type, --lang, --no-deploy | | Template not found | 名称错误 | 检查 cloudflare/templates |