速查手册

发布时最常翻的命令、配置和排障点

这一页对应原始资料里的速查手册。它不是完整文档，而是把高频配置、命令和故障判断压缩成更适合上线时快速翻看的结构。

常用路线速查

场景	推荐组合	说明
纯内容站 / 文档站	GitHub + Cloudflare Pages	优先静态导出，部署最轻。
静态页面 + 少量接口	Pages + Worker	页面和接口分别维护，节奏更灵活。
多个前端共用后端	Pages + 独立 API Worker	接口统一维护，前端继续独立发布。

高频命令

以下命令来自资料中的速查思路，保留首版最常用的一组。

npm install
npm run dev
npm run build
wrangler login
wrangler secret put <NAME>
git push origin main

Cloudflare Pages 关键配置

Build Command

和本地构建保持一致。Next.js 静态导出路线常见为 `npm run build`。

Output Directory

不要写错。静态导出项目通常是 `out`，如果路径不对，Pages 会出现部署成功但页面空白。

Environment Variables

区分预览与生产环境。公开值可前端读取，敏感值只能放到受保护的环境配置里。

资源能力速记

KV

配置、映射、轻量缓存。

D1

结构化数据、SQL 查询。

R2

图片、文件和对象存储。

Secrets

只放在 Worker 或 Pages 的环境变量，不进入前端构建产物。

常见故障速查

Pages 构建成功但页面 404：先检查 output 目录是否填对
正式域名打不开：优先检查 DNS 记录和 Zone 是否正确
前端能打开但接口报错：检查 CORS、环境变量和 Worker 路由
样式或图片缺失：检查静态资源是否被正确导出到产物目录
统计没数据：确认 Web Analytics 已开启，前端埋点是否真正触发

官方文档入口建议单独保留

原始资料最后都附了官方文档入口。正式站点里建议把 Pages、Workers、D1、KV、R2、Web Analytics 的官方链接单独整理成附录或资源页，便于持续更新。

飞书群入口说明

当前首页和正文中的飞书群按钮是统一占位入口，用于承接后续开放申请或登记通知。正式链接准备好后，统一在站点配置中替换即可。