OpenClaw Cloudflare 新手指南
OpenClaw Cloudflare 新手指南
这页服务的是这样一个时刻： 你已经把本地环境跑通了，现在想把第一版安全地发到 Cloudflare 上。
如果你连本地安装、第一次 build 或第一次 sanity check 都还没完成，这页还不是你的第一站。
快速信息
- 适合谁：已经完成本地验证，准备做第一次 Cloudflare 部署的人
- 当前这站的部署栈：通过 OpenNext 把 Next.js 发布到 Cloudflare Workers
- 这个仓库里最重要的命令：
pnpm cf:preview、pnpm cf:deploy、pnpm cf:typegen - 验证时间：2026-03-13，已对照当前 OpenNext 与 Cloudflare Workers 官方文档核对
什么情况下适合上 Cloudflare
- 你想把站点从“只在自己电脑上能看”变成一个稳定公开 URL
- 你需要 Cloudflare 的边缘运行时和可观测性
- 你的第一个真实工作流已经在本地稳定
- 你已经能管理好 secrets、域名和回滚记录
什么情况下先不要从这里开始
- 你本地的
pnpm build还没跑通 - 你还不知道第一个重要的 channel 或 workflow 是什么
- 你还没决定生产环境 URL
- 你的核心环境变量还在频繁变化
部署前先准备好这些
在碰 deploy 之前，先把这几件事准备好：
- 一个 Cloudflare 账号；如果你要正式域名，也先准备好自己的域名。
pnpm install- 一个能正常使用的 Wrangler 登录状态。
- 你准备正式发布的公开环境值。
先执行这个检查：
npx wrangler whoami如果失败，再先登录：
npx wrangler login这个仓库的 worker 配置在 wrangler.toml，仓库里的安全示例在 wrangler.toml.example。
对新手最稳妥的路径
第一步：先证明应用本身能 build
先跑：
pnpm build只有 build 干净通过，才继续碰 Cloudflare。
第二步：先在本地预览 worker
如果你改过 runtime 绑定，或者想更新类型文件，先跑：
pnpm cf:typegen然后再本地预览 worker：
pnpm cf:preview至少确认首页和一个更深层的页面都能打开，再进入真正 deploy。
第三步：只加你现在真的需要的 secrets
如果你现在只是先发布公开内容页，这个站点可以先不依赖数据库和认证 secrets。
但如果你准备启用认证或数据库功能，就先加上：
npx wrangler secret put AUTH_SECRET
npx wrangler secret put DATABASE_URL如果你的本地 preview 开着 auth，不要忘了把 .dev.vars 里的占位 AUTH_SECRET 换成真实本地值。
第四步：部署到 Cloudflare Workers
直接跑：
pnpm cf:deploy这个仓库已经接了 @opennextjs/cloudflare，所以 deploy 脚本本身就是面向 Cloudflare Workers 的。
第五步：绑定真实域名并做 smoke test
第一次部署成功后，再做下面这组检查：
- 如果域名没有自动绑定，就去 Cloudflare Workers 后台手动绑定
- 打开部署后的正式 URL
- 至少测试
/、/openclaw和一个更深层页面，例如/skills - 在对外宣布之前，先确认 Cloudflare 里能看到请求日志和错误
第一次生产验证清单
在你说“已经上线”之前，至少确认：
- 首页能在真实域名上打开
- 一条英文路由和一条中文路由都能正常访问
- 一个深层内容页不会出现 404
- 没有把依赖 secret 的功能意外打开
- 你真的能在 Cloudflare observability 里找到报错
新手最常踩的坑
1. 把 Cloudflare 当成第一层验证
Cloudflare 应该是第二层验证。第一层验证永远是本地 build 和本地 preview。
2. 还在用旧的 Pages 思维
这个仓库已经是 OpenNext + Cloudflare Workers 路线，不要自己再脑补一条不同的部署链路。
3. 忘了生产 URL 一致性
如果绑定域名和 NEXT_PUBLIC_APP_URL 对不上，链接、预览图和分享体验会很快变乱。
4. Secret 加得太早或太晚
不要因为还没用到的数据库 secret 卡住内容站第一版上线；但也不要在没配好 secret 的情况下就启用认证或数据库能力。
5. 上线后没有回滚记录
至少记下部署命令、日期、域名和最后一份可用配置，后面会非常省时间。