Pages 常见陷阱

# 常见陷阱 (Gotchas) ## Functions 未运行 **问题**: 函数端点返回 404 或未执行 **原因**: `_routes.json` 排除路径；文件扩展名错误 (`.jsx`/`.tsx`)；Functions 目录不在输出根目录 **解决方案**: 检查 `_routes.json`，重命名为 `.ts`/`.js`，验证构建输出结构 ## 静态资源 404 **问题**: 静态文件无法访问 **原因**: 构建输出目录配置错误；Functions 捕获了请求；高级模式缺少 `env.ASSETS.fetch()` **解决方案**: 验证输出目录，在 `_routes.json` 中添加排除项，在 `_worker.js` 中调用 `env.ASSETS.fetch()` ## 绑定无法工作 **问题**: `env.BINDING` 未定义或报错 **原因**: wrangler.jsonc 语法错误；绑定 ID 错误；缺少 `.dev.vars`；类型不同步 **解决方案**: 验证配置，核对 ID，创建 `.dev.vars`，运行 `npx wrangler types` ## 构建失败 **问题**: 部署期间构建失败 **原因**: 构建命令/输出目录错误；Node 版本不兼容；缺少环境变量；20分钟超时；内存溢出 (OOM) **解决方案**: 检查控制台 → 部署 → 构建日志；验证设置；添加 `.nvmrc`；优化构建 ## 中间件未运行 **问题**: 中间件未执行 **原因**: 文件名错误 (非 `_middleware.ts`)；缺少 `onRequest` 导出；未调用 `next()` **解决方案**: 重命名文件并添加下划线前缀；导出处理器；调用 `next()` 或返回 Response ## 头信息/重定向未生效 **问题**: `_headers` 或 `_redirects` 未应用 **原因**: 仅对静态资源有效；Functions 覆盖；语法错误；超出限制 **解决方案**: 在 Functions 的 Response 对象中设置头信息；验证语法；检查限制 (100 条头信息, 2,100 条重定向) ## TypeScript 错误 **问题**: Functions 代码中的类型错误 **原因**: 未生成类型；Env 接口与 wrangler.jsonc 不匹配 **解决方案**: 运行 `npx wrangler types --path='./functions/types.d.ts'`；更新 Env 接口 ## 本地开发问题 **问题**: 开发服务器错误或绑定无效 **原因**: 端口冲突；绑定未传递；本地与 HTTPS 环境差异 **解决方案**: 使用 `--port=3000`；通过 CLI 或 wrangler.jsonc 传递绑定；考虑 HTTP/HTTPS 差异 ## 性能问题 **问题**: 响应缓慢或 CPU 限制错误 **原因**: 静态资源触发了 Functions；冷启动；10ms CPU 限制；包体积过大 **解决方案**: 通过 `_routes.json` 排除静态资源；优化热点路径；保持包体积 < 1MB ## 框架特定问题 ###