技术笔记Tue Oct 13 2026 00:00:00 GMT+0000 (Coordinated Universal Time)15 分钟阅读

Cloudflare Worker 部署的 5 个隐蔽陷阱

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

Z
ZhangKing
作者
Cloudflare Worker 部署的 5 个隐蔽陷阱

《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 个陷阱,表面上各不相同:

  1. 父目录配置劫持
  2. wrangler 3.x 资源不递归
  3. assets 默认绕过 Worker
  4. 第三方库 bug 转移
  5. 静态资源 404

但它们有一个共同点——

都不是"代码错误",而是"架构假设的碰撞"。

每一个陷阱,都是因为某个工具(wrangler、Cloudflare Assets、R2-Explorer)做了一个合理但与我的预期不符的假设。

而这些假设,不会写在 README 的第一页。它们只在你踩坑后,去 GitHub Issues、Discord 频道、Stack Overflow 里搜半天才能发现。

这让我想起一句话:

文档告诉你"能做什么",故障排查告诉你"不能做什么"。 真正的门槛,往往藏在后者里。


5 条黄金原则

部署任何 Cloudflare Worker + SPA 项目前,必读:

  1. 用 --config 显式指定配置——别让父目录的 wrangler 文件劫持你
  2. 必须 wrangler 4.x + Node 22——3.x 的 assets 不递归是定时炸弹
  3. run_worker_first = true 是带认证 SPA 的必需——静态资源也要走认证
  4. 不要相信第三方库的"看起来正确"——关键函数读源码
  5. 端到端测试 > 单元测试——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 的态度从"前端福音"变成了"敬畏的工具"。

它确实是强大的。但强大 ≠ 易用。

强大意味着它能支撑复杂的架构,而复杂的架构必然有复杂的默认行为。这些默认行为在你需要的时候是惊喜,在你不需要的时候是陷阱。

唯一的应对方式:保持怀疑,保持测试,保持读源码。

这是工程师的基本功,也是和"自由灵魂引擎"相处的根本方式。


相关阅读:


写于 2026-10-13,部署 zkpan.uk 三天后。 每一个坑,都用 6-12 小时换来的。 希望你看完这篇,能省下 60 小时。

#Cloudflare#Worker#部署#调试#踩坑

分享这篇文章