使用Wrangler部署Cloudflare Node.js应用时出现worker_threads解析错误

核心原因 #

Cloudflare Workers基于V8 Isolate运行，完全不支持Node.js的worker_threads模块——哪怕开启node_compat也没用，因为这个模块依赖Node.js的线程系统，和Workers的隔离环境架构冲突。你的构建配置或依赖中肯定有代码/包引入了这个模块，导致打包后部署报错。

分步解决方案 #

1. 定位引入worker_threads的依赖 #

运行命令找出依赖树里的源头：

npm ls worker_threads

找到对应包后，优先替换为Cloudflare Workers兼容的替代包（比如选专门适配Workers的日志、工具类包）。如果是可选依赖，直接通过构建配置排除它。

2. 修复esbuild构建脚本 #

你当前用--platform=node按Node.js环境打包，完全不符合Workers的运行环境，必须调整：
修改package.json里的build命令：

"build": "npx esbuild ./src/index.ts --bundle --platform=browser --outfile=build/worker.js --define:process.env.NODE_ENV=\"production\""

• 删除--external:node:*：这个配置会让所有Node.js模块都不打包，但Workers环境根本没有这些模块，反而需要对必要模块做polyfill（worker_threads除外）。
• 改用--platform=browser：适配Workers的类浏览器运行环境。

3. 强制屏蔽worker_threads（无法替换依赖时） #

如果找不到替代包，给worker_threads做个空垫片：

1. 在项目根目录新建worker-threads-shim.js：

// 空实现，避免解析错误
export const Worker = () => { throw new Error('worker_threads不支持在Cloudflare Workers中运行') };

2. 修改构建命令注入垫片：

"build": "npx esbuild ./src/index.ts --bundle --platform=browser --outfile=build/worker.js --define:process.env.NODE_ENV=\"production\" --inject:./worker-threads-shim.js"

打包时会把require("worker_threads")替换成这个空实现，解决解析错误。

4. 清理不必要的Node.js依赖 #

把@types/node、ts-node这类仅Node.js开发用的包移到devDependencies，避免被打包：

"devDependencies": {
  "@cloudflare/workers-types": "^4.20230518.0",
  "rollup-plugin-node-polyfills": "^0.2.1",
  "wrangler": "3.1.1",
  "@types/node": "^18.11.18",
  "ts-node": "^10.0.0"
},
"dependencies": {
  "@rollup/plugin-inject": "^5.0.3",
  "@tsndr/cloudflare-worker-jwt": "^2.2.1",
  "itty-router": "^4.0.14",
  "toucan-js": "^3.1.0"
}

5. 检查wrangler.toml配置 #

如果你的依赖不需要Node.js兼容，建议关闭node_compat = true，减少兼容层带来的潜在问题。

内容的提问来源于stack exchange，提问作者MTN