上周我想做一个"多人同时在线、能看到彼此走动"的小场景:前端一个 WebGL 画面,后端用 WebSocket 把每个人的位置和动作广播出去。技术上最省事的方案是 Cloudflare Workers + Durable Objects——不用买服务器,一个房间就是一个 Durable Object 实例,天然适合这种"小房间、强实时"的场景。
听起来是半小时的活。实际从第一行命令到线上可访问,我花了将近三个小时,其中大部分时间不是在写代码,而是在跟权限和配置较劲。这篇把踩过的 5 个坑和对应的诊断方法完整记下来,你用 AI 助手做同类部署时可以少走一遍。
整个过程里,真正属于"代码写错"的只有一个(第 3 个坑)。剩下四个全部是配置语义陷阱:你以为勾了、其实没保存;你以为改的是这个 token、其实改的是另一个;你以为接口该这么传参、实际字段名不一样。
这类问题最坑的地方在于:报错信息看起来像代码问题,实际上是权限问题。所以下面每个坑我都配了"怎么证明是它"的验证动作,而不是靠猜。
Cloudflare 有两套 API Token,长得像、名字也像,但完全不是一回事:
类型 | 前缀 | 在哪创建 | 用途 |
|---|---|---|---|
User API Token | cfut_ | My Profile → API Tokens | 用户级,受"认证方式限制" |
Account API Token | cfat_ | 账户 → API Tokens | 账户级,脚本部署常用 |
我一开始用一个 cfat_ 开头的账户级 token 部署 Pages,一切正常。后来要给 Workers 加写权限,在后台点进去改了一个 cfut_ 的 token——勾也勾了、保存也保存了,但部署依然 403。
原因很朴素:我改的那个 token,跟命令行里在用的那个,不是同一个。
诊断方法(比反复试探针准得多):
只要"前缀 + 后缀"跟后台那一行对不上,就说明你改的不是它——这时候再怎么点保存都没用,别耗。

这是我卡最久的地方。Cloudflare 的 token 编辑页有两个"隐形必填项",缺一个都建不出可用 token:
第一道坎:Account policy 的资源范围默认是空的。
权限组里 Workers Scripts 勾成 Edit 看着没问题,但 Account policy → Include 右边的资源框显示的是 Select...(空)。这时候点 Continue,建出来的 token 照样 403。必须点开选 All accounts(或至少勾中目标账户)。Workers 是账户级资源,资源范围没覆盖账户,权限勾了也白搭。
第二道坎:编辑页有"草稿态",必须走完两步提交。
在权限页勾选完,页面底部按钮还是 Continue to summary——这意味着改动还在草稿里。必须:
Continue to summaryUpdate token / Create Token我第一次就是在第 1 步截了图,以为改完了,然后对着一个没生效的 token 反复重试了三次。
顺带一个坑:用 "Edit Cloudflare Workers" 模板建 token 时,模板会自带一条 Edit Zone policy,默认选了 "Specific zone" 却没填具体 zone,页面直接报红字 Choose a zone resource,把底部的 Create 按钮卡死。Worker 部署不需要 zone 权限(除了普通 route),把这条 policy 整条删掉即可。

这是全场唯一一个真·代码错误,但报错信息给了明确线索:
免费计划的 Durable Object 必须声明为 SQLite 后端:
改一行,重新 deploy 就能过。这类问题不用查文档,报错里已经写了答案。

部署成功后 wrangler 会返回一个 https://xxx.workers.dev 的地址。我打开是空白,同事打开也是空白,第一反应是"部署坏了"。
实际是 *.workers.dev 这个域名在国内经常不可达。部署是成功的——判断依据不要用"我这边能不能打开",而要用控制台和 API:
两个接口都正常返回,就说明线上是好的,问题在访问链路。
解法是绑自己的域名,而且不能用普通 route,要用 custom domain:
custom_domain = true 时,wrangler deploy 会自动建 DNS 记录和证书,不要手动加 CNAME,会冲突。
另外两个细节:
zone_id 的普通 [[routes]] 需要 Zone 写权限,账户级 token 没有就会 403;/accounts/{id}/workers/domains 创建自定义域,容易被 User token 以 Method not allowed for this authentication scheme 拒掉。走 wrangler 配置最省事。
绑好域名后,我在本地 curl 一直是 HTTP 000,curl -v 显示代理对目标域名 CONNECT 返回 502。差点又去改配置。
判别方法很简单,三条一起看:
curl --noproxy '*' 直连还不通;三条对上,就是本机到目标的链路问题,不是线上问题。这种"假故障"最费时间,因为它看起来跟"服务挂了"一模一样。
现象 | 先查什么 | 常见真因 |
|---|---|---|
部署 403 No access to the specified resource | token 前缀/后缀是否与后台一致 | 改错了 token 类型 |
建完 token 仍然 403 | Account policy 资源范围是否为空 | 没选 All accounts |
权限勾了但没变化 | 是否走了 Continue to summary → Update | 停在草稿态 |
Create 按钮点不动 | 页面里是否有红字 policy | Zone policy 选了 Specific zone 没填值 |
code 10097 | wrangler.toml 的 migrations | 免费计划要用 new_sqlite_classes |
.workers.dev 打不开 | 控制台/API 是否正常 | 域名不可达,绑自定义域 |
本地 curl 000 / CONNECT 502 | 换外部通道验一次 | 本机代理干扰,假故障 |
这轮下来我最大的体会不是"AI 会不会写代码",而是:部署类任务里,AI 最大的价值是"设计验证动作",不是"猜原因"。
同样是 403,让人(或者让 AI)凭经验猜,会依次怀疑:代码写错 → 权限没给 → 配置没保存 → 平台限制,每猜一次就是一轮试错。而如果先做一个"最小写探针"(上传一个 5 行的 Hello World 脚本),一次请求就能把"是权限问题还是代码问题"切开——后面所有排查都在这条岔路的正确一侧进行。
我现在给这类任务的提示词固定这么写:
最后交付的东西是一个可以点开就用的地址,但真正省下时间的,是中间那些"先证明、再动手"的小验证。

(本文为个人实操记录,命令与配置均来自实际排查过程,不同账号与计划版本可能存在差异,以官方文档为准。)
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。