Pages Functions 常见陷阱

# 常见问题与调试 ## 错误诊断 | 症状 | 可能原因 | 解决方案 | |---------|--------------|----------| | **函数未调用** | `/functions` 位置错误、扩展名错误或 `_routes.json` 排除路径 | 检查 `pages_build_output_dir`，使用 `.js`/`.ts`，验证 `_routes.json` | | **`ctx.env.BINDING` 未定义** | 绑定未配置或名称不匹配 | 添加至 `wrangler.jsonc`，验证名称（区分大小写），重新部署 | | **`ctx.env` 出现 TypeScript 错误** | 缺少类型定义 | 运行 `wrangler types` 或定义 `interface Env {}` | | **中间件未运行** | 文件名/位置错误或缺少 `ctx.next()` | 命名为 `_middleware.js`，导出 `onRequest`，调用 `ctx.next()` | | **生产环境缺少密钥** | `.dev.vars` 未部署 | `.dev.vars` 仅限本地 - 通过仪表板或 `wrangler secret put` 设置生产密钥 | | **绑定类型不匹配** | 接口类型错误 | 参阅 [api.md](./api.md) 绑定表获取正确类型 | | **“KV key not found” 但存在** | 键位于错误的命名空间或环境 | 验证命名空间绑定，检查预览与生产环境 | | **函数超时** | 同步等待或缺少 `await` | 所有 I/O 必须为 async/await，后台任务使用 `ctx.waitUntil()` | ## 常见错误 ### TypeScript 类型错误 **问题：** `ctx.env.MY_BINDING` 显示类型错误 **原因：** `Env` 缺少类型定义 **解决方案：** 运行 `npx wrangler types` 或手动定义： typescript interface Env { MY_BINDING: KVNamespace; } export const onRequest: PagesFunction = async (ctx) => { /* ... */ }; ### 生产环境无法获取密钥 **问题：** `ctx.env.SECRET_KEY` 在生产环境中未定义 **原因：** `.dev.vars` 仅限本地，不会被部署 **解决方案：** 设置生产环境密钥： bash echo "value" | npx wrangler pages secret put SECRET_KEY --project-name=my-app ## 调试 typescript // 控制台日志 export async function onRequest(ctx) { console.log('Request:', ctx.request.method, ctx.request.url); const res = await ctx.next(); console.log('Status:', res.status); return res; } bash # 实时流式日志 npx wrangler pages deployment tail npx wrangler pages deployment tail --status error c // 源映射 (wrangler.jsonc) { "upload_source_maps": true } ## 限制 | 资源 | 免费版 | 付费版 | |----------|------|------| | CPU 时间 | 10ms | 50ms | | 内存 | 128 MB | 128 MB | | 脚本大小 | 10 MB (压缩后) | 10 MB (压缩后) |