Cloudflare Worker 部署的 5 个隐蔽陷阱
当我以为部署一个 Worker 是三分钟的事,它用了三天才教会我:文档不会告诉你的,才是真正的门槛。

《Cloudflare Worker 部署的 5 个隐蔽陷阱》
文档说:"wrangler deploy 就能上线"。 现实说:你需要先踩过 5 个隐蔽的坑。 这 5 个坑,每一个都不会在第一篇教程里出现,但每一个都能让你卡住半天到三天不等。
起 因:三分钟的部署,三天的血泪
我一直以为 Cloudflare Worker 是"前端开发者的福音"——不用管服务器,不用配 Nginx,不用担心 DDoS,写完代码一个 wrangler deploy 就完事。
直到我亲手把 zkpan.uk(一个基于 R2-Explorer 的云盘)部署上线。
结果是:从第一次部署到真正能正常登录、看到文件、流畅操作,用了三天。
这三天里,我踩了 5 个隐蔽的陷阱。每一个:
- 看起来都"应该是正常工作的"
- 都有现成的文档说明
- 都会在某个特定条件下"巧合地正常"
- 一旦条件变化,就立刻爆炸
更可怕的是——这些坑不会同时出现。它们会一个一个接踵而至,让你以为"这个修好了应该就完了",结果下一个又冒出来。
今天,我把这 5 个坑1:1 还原出来。
不是为了抱怨,是为了让你少走 3 天弯路。
陷阱一:父目录的 wrangler 配置会"劫持"你的 Worker
症 状
我在项目根目录有一个 wrangler.jsonc(配置 A 项目)。某天新建子目录 zkpan/,里面有自己的 wrangler.toml(配置 B 项目)。我在子目录里执行:
cd zkpan/
wrangler deploy
结果:部署的根本不是 zkpan 项目,而是 A 项目。Worker 名字是 A 项目的,控制台里看不到 zkpan 的记录,配置全是 A 的。
真正原因
wrangler 会自动向上递归查找父目录的配置文件:
项目根目录/wrangler.jsonc ← 找到了!就用这个
└── zkpan/
└── wrangler.toml ← 根本没被读
这是 wrangler 的"贴心设计"——为了支持 monorepo 多项目共享配置。但当你的根目录有遗留配置时,它就变成了**"父目录劫持"**。
解决方 案
用 --config 显式指定:
wrangler deploy --config ./wrangler.toml
或者,用环境变量切断向上查找:
# 在子目录里部署
cd zkpan/
wrangler deploy --config ./wrangler.toml
教 训
永远不要相信"默认行为"在多项目环境下还能工作。 wrangler 4 引入的
--config是救命稻草,但官方文档只在"故障排查"章节里轻描淡写地提了一句。
陷阱二:wrangler 3.x 不递归上传 assets 子目录
症 状
zkpan.uk 部署成功,登录成功,API 正常返回 JSON。
但页面永远卡在 "Loading R2-Explorer..."。
我用 curl 测试,发现了诡异的现象:
# 测试根路径 — 正常
curl -sI https://zkpan.uk/ | grep content-type
# content-type: text/html ✅
# 测试 API — 正常
curl -sI https://zkpan.uk/api/buckets | grep content-type
# content-type: application/json ✅
# 测试 JS 文件 — 异常!
curl -sI https://zkpan.uk/assets/index.97b9144c.js | grep content-type
# content-type: text/html ❌ 应该是 text/javascript!
JS 文件返回 HTML? 打开浏览器 DevTools 的 Network 面板一看,JS 文件的响应体是:
<!DOCTYPE html>
<html>
<body>Loading R2-Explorer...</body>
</html>
浏览器试图解析这段 HTML 成 JavaScript,直接报错:
Uncaught SyntaxError: Unexpected token '<'
页面永远卡在 Loading — 因为服务器根本没传 JS 文件,而是返回了 SPA 的 fallback HTML。
真正原因
wrangler 3.x 的 assets 上传是"非递归"的。
我的项目结构:
spa-custom/
├── favicon.ico
├── index.html
├── assets/ ← ⚠️ 子目录不传!
│ ├── index.97b9144c.js ← 部署后访问返回 404/SPA fallback
│ └── index.74f0784c.css
└── icons/ ← ⚠️ 子目录不传!
└── favicon-128x128.png
对比测试:
| URL | 修复前 | 修复后 |
|-----|--------|--------|
| /favicon.ico(根目录)| image ✅ | image ✅ |
| /assets/index.xxx.js(子目录)| text/html ❌ | text/javascript ✅ |
| /icons/favicon-128x128.png(子目录)| text/html ❌ | image/png ✅ |
解决方 案
升级到 wrangler 4.x + Node 22:
# 1. 安装 Node 22(wrangler 4 最低要求)
nvm install 22
# 2. 全局升级 wrangler 4
npm install -g wrangler@^4.0.0
# 3. 验证版本
wrangler --version # 应该是 4.x
# 4. 重新部署
cd ~/path/to/zkpan
wrangler deploy --config ./wrangler.toml
wrangler 4 的部署输出会有关键证据:
✨ Read 30 files from the assets directory /path/to/spa-custom
🌀 Found 1 new or modified static asset to upload.
+ /assets/index.97b9144c.js
✨ Success! Uploaded 1 file (27 already uploaded)
教 训
wrangler 升级不是"可选项",是"必须项"。 wrangler 3 → 4 的升级解决了三个我之前没意识到的 bug:assets 递归上传、Node 18 弃用警告、TypeScript 5 支持。
检测方法
# 检查静态资源是否返回正确的 Content-Type
curl -sI https://your-domain.workers.dev/assets/yourfile.js
# 期望:content-type: text/javascript
# 异常:content-type: text/html(SPA fallback)
陷阱三:Cloudflare Assets 默认绕过 Worker(最隐蔽!)
症 状
我加了 run_worker_first = true 想让所有请求都走 Worker 认证。然后:
- ✅
GET /api/buckets→ Worker 处理(认证拦截正常) - ❌
GET /→ 绕过 Worker,直接返回 R2-Explorer 的 HTML
用户没登录也能看到 dashboard 页面——认证形同虚设。
真正原因
Cloudflare Workers 的 assets 绑定默认行为是绕过 Worker fetch handler:
[assets]
directory = "node_modules/r2-explorer/dashboard"
binding = "ASSETS"
# ← 没有 run_worker_first = true
# ← Cloudflare 直接返回静态资源,不调用 Worker
调用流程对比:
| 路径 | 没有 run_worker_first | 有 run_worker_first |
|------|---------------------|-------------------|
| /api/buckets | ✅ Worker 处理 | ✅ Worker 处理 |
| / | ❌ 直接返回 HTML | ✅ Worker 处理 |
| /style.css | ❌ 直接返回 CSS | ✅ Worker 处理 |
| /icon.png | ❌ 直接返回 PNG | ✅ Worker 处理 |
解决方 案
必加 run_worker_first = true:
[assets]
directory = "node_modules/r2-explorer/dashboard"
binding = "ASSETS"
html_handling = "auto-trailing-slash"
not_found_handling = "single-page-application"
run_worker_first = true # ⭐ 必加
教 训
静态资源认证不只是 API 认证 —— HTML/CSS/JS 也要走认证。 wrangler 4.86.0 的默认行为是绕过 Worker,任何带认证的 SPA 都必须显式开启
run_worker_first。
陷阱四:第三方库的 bug 不会消失,只会"转移"
症 状
加上 run_worker_first = true 后,GET / 返回 500 错误:
"ASSETS binding is not pointing to a valid dashboard,
learn more here: https://r2explorer.com/guides/migrating-to-1.1/"
我反复检查目录结构、重装 R2-Explorer、清缓存——都没用。
真正原因
我打开 R2-Explorer 的源码,找到处理 / 路径的函数 dashboardIndex():
// node_modules/r2-explorer/src/dashboard.js
function dashboardIndex(c) {
if (c.env.ASSETS === void 0) {
return c.text("ASSETS binding is not defined...", 500);
}
// ⬇️ WTF?直接返回错误?
return c.text("ASSETS binding is not pointing to a valid dashboard...", 500);
// ⬇️ 这行永远不会执行!
// return c.env.ASSETS.fetch(new Request(...));
}
我看了三遍才敢相信:
- 函数只检查
ASSETS === void 0(是否未定义) - 如果定义了,直接返回 500 错误
- 永远不调用
c.env.ASSETS.fetch()返回真正的 HTML
这不是配置问题 — 这是第三方库的 bug。
为什么之前没发现
bug 巧合抵消:
- 之前
assets默认行为:/直接走 Assets 返回 HTML,不调用 Worker - 之前没加
run_worker_first = true:绕过了这个 bug - 两个 bug 互相抵消 —— 巧合让一切正常工作
当我加上 run_worker_first = true 后,Worker 终于被调用了,第三方库的 bug 也暴露了。
解决方 案
绕过第三方库的 bug,自己手动处理 / 路径:
if (url.pathname === "/" || url.pathname === "/index.html") {
if (env.ASSETS) {
const response = await env.ASSETS.fetch(
new Request(new URL("/", request.url), {
method: "GET",
headers: request.headers,
})
);
const newHeaders = new Headers(response.headers);
newHeaders.set("Cache-Control", "no-store, no-cache, must-revalidate");
return new Response(response.body, {
status: response.status,
headers: newHeaders,
});
}
}
教 训
bug 可以相互抵消 —— 修一个可能暴露另一个。 用第三方库前要读关键函数源码 —— linter/编译器抓不到的 bug,只有源码能抓。
陷阱五:修了 /,JS/CSS 又 404 了
症 状
修了陷阱四的 / 路径后,HTML 终于正常返回。
但浏览器还是 Loading。
打开 Network 面板:
index.html→ 200 OK ✅assets/index.97b9144c.js→ 404 Not Found ❌assets/index.74f0784c.css→ 404 Not Found ❌
页面拿到 HTML 但拿不到 JS → 永远卡在 Loading。
真正原因
之前的修复只处理了 / 路径,没有处理其他静态资源:
// ❌ 错误:只处理 / 路径
if (url.pathname === "/" || url.pathname === "/index.html") {
return env.ASSETS.fetch(...);
}
// 其他路径都给 R2Explorer
return r2explorer.fetch(request, env, ctx);
但 R2Explorer 不认识静态资源路径——它只认识 /api/* 和 /share/:shareId。
其他路径(如 /assets/index.xxx.js)会走到 app.all("*", () => 404),返回 404。
解决方 案
所有非 API 路径都从 env.ASSETS 取:
if (isAuthenticated(request)) {
if (env.ASSETS && !url.pathname.startsWith("/api/")) {
// 所有非 API 路径:HTML、SPA 路由、JS、CSS、图片、favicon
const response = await env.ASSETS.fetch(request);
const newHeaders = new Headers(response.headers);
newHeaders.set("Cache-Control", "no-store, no-cache, must-revalidate");
return new Response(response.body, {
status: response.status,
statusText: response.statusText,
headers: newHeaders,
});
}
// 只把 API 路径交给 R2Explorer
return r2explorer.fetch(request, env, ctx);
}
完整路由分发逻辑
请求进入 Worker
↓
认证检查
├─ 未认证 → 302 → /login
└─ 已认证 ↓
路径判断
├─ /api/* → R2Explorer(处理 API)
└─ 其他 → env.ASSETS(处理 HTML/JS/CSS/图片)
教 训
静态资源不只是
/—— 包括 JS、CSS、图片、favicon。 修一个 bug 可能暴露另一个 bug —— 教训三 → 教训四 → 教训五,是连锁反应。 JS 文件通常 1-2 MB,加载失败肉眼看不到,必须看 Network 面板。
验证清单
部署后必须验证:
- [ ] HTML 加载(
GET /) - [ ] JS 文件加载(
GET /assets/*.js) ⭐ 容易遗漏 - [ ] CSS 文件加载(
GET /assets/*.css) - [ ] Favicon 加载(
GET /favicon.ico) - [ ] 图片加载(
GET /icons/*.png) - [ ] API 调用成功(
GET /api/server/config) - [ ] 浏览器控制台无 404 错误
终 章:陷阱的本质
这 5 个陷阱,表面上各不相同:
- 父目录配置劫持
- wrangler 3.x 资源不递归
- assets 默认绕过 Worker
- 第三方库 bug 转移
- 静态资源 404
但它们有一个共同点——
都不是"代码错误",而是"架构假设的碰撞"。
每一个陷阱,都是因为某个工具(wrangler、Cloudflare Assets、R2-Explorer)做了一个合理但与我的预期不符的假设。
而这些假设,不会写在 README 的第一页。它们只在你踩坑后,去 GitHub Issues、Discord 频道、Stack Overflow 里搜半天才能发现。
这让我想起一句话:
文档告诉你"能做什么",故障排查告诉你"不能做什么"。 真正的门槛,往往藏在后者里。
5 条黄金原则
部署任何 Cloudflare Worker + SPA 项目前,必读:
- 用
--config显式指定配置——别让父目录的 wrangler 文件劫持你 - 必须 wrangler 4.x + Node 22——3.x 的 assets 不递归是定时炸弹
run_worker_first = true是带认证 SPA 的必需——静态资源也要走认证- 不要相信第三方库的"看起来正确"——关键函数读源码
- 端到端测试 > 单元测试——HTML 加载、JS 加载、CSS 加载,全要验证
写在最后:三天的情绪曲线
第 1 天 18:00
"wrangler deploy 成功了!zkpan.uk 上线了!🎉"
第 1 天 18:05
"为什么页面永远 Loading...?"
第 2 天 03:00
"原来是 wrangler 3.x 的 bug,升级到 4.x 就好了!这次肯定没问题了!"
第 2 天 03:10
"为什么还是能匿名访问 dashboard?这不是没登录吗..."
第 3 天 01:00
"加了 run_worker_first = true,这次真的完了... 完成了!"
第 3 天 01:05
"500 错误?ASSETS binding not valid?我明明配置了啊!"
第 3 天 02:30
"打开源码一看 — 第三方库有 bug。代码就这样写的,if defined then return error。我去..."
第 3 天 04:00
"绕过第三方库的 bug,自己手动处理 / 路径 — 终于 OK 了!"
第 3 天 04:15
"HTML 能加载了,但 JS 404 了... 又来?"
第 3 天 06:00
"所有非 API 路径都从 env.ASSETS 取 — 终于彻底修好了。"
这三天的血泪,让我对 Cloudflare Worker 的态度从"前端福音"变成了"敬畏的工具"。
它确实是强大的。但强大 ≠ 易用。
强大意味着它能支撑复杂的架构,而复杂的架构必然有复杂的默认行为。这些默认行为在你需要的时候是惊喜,在你不需要的时候是陷阱。
唯一的应对方式:保持怀疑,保持测试,保持读源码。
这是工程师的基本功,也是和"自由灵魂引擎"相处的根本方式。
相关阅读:
- 《死在了网络上,不是死在技术上》 — Vercel 4.5MB 限制的踩坑之旅
- 《命令行的传承:Vercel CLI 部署的血泪》 — CLI 部署的工程哲学
- zkpan.uk 部署日记 2026-06-23 — 本次部署的完整调试日志
写于 2026-10-13,部署 zkpan.uk 三天后。 每一个坑,都用 6-12 小时换来的。 希望你看完这篇,能省下 60 小时。