使用Wrangler打包Node.js依赖部署Cloudflare Worker遇模块解析错误

问题详情 #

尝试构建依赖Node.js的Cloudflare Worker，执行wrangler deploy时失败，出现大量模块解析错误，核心是Node.js内置模块（如async_hooks、worker_threads等）无法被识别。已尝试在package.json中添加"platform": "node"配置，无效。

报错示例 #

X [ERROR] Could not resolve "async_hooks"
  node_modules/undici/lib/api/api-connect.js:4:34:
      4 │ const { AsyncResource } = require('async_hooks')
        ╵                                   ~~~~~~~~~~~~~

  The package "async_hooks" wasn't found on the file system but is built into node. Are you trying to bundle for node? You can use "platform: 'node'" to do that, which will remove this error.

最终构建失败提示：

X [ERROR] Build failed with 74 errors:

  node_modules/@discordjs/rest/dist/index.js:445:30: ERROR: Could not resolve "timers/promises"
  node_modules/@discordjs/ws/dist/index.js:117:42: ERROR: Could not resolve "worker_threads"
  node_modules/@discordjs/ws/dist/index.js:448:31: ERROR: Could not resolve "timers/promises"
  node_modules/discord.js/src/client/BaseClient.js:3:29: ERROR: Could not resolve "node:events"
  node_modules/discord.js/src/client/Client.js:3:24: ERROR: Could not resolve "node:process"
  ...

解决方案 #

1. 核心原因 #

Cloudflare Worker的运行环境是V8 Isolate，并非完整的Node.js runtime，不支持async_hooks、worker_threads这类Node.js专属内置模块。你使用的依赖（如discord.js、undici）是为Node.js环境设计的，直接在Worker中使用会触发解析错误。

另外，package.json中的platform配置不影响Wrangler的打包逻辑——Wrangler使用esbuild打包，相关配置需在wrangler.toml中设置，且即使强制指定platform: node，Worker环境也无法运行Node.js专属API。

2. 具体修复步骤 #

• 替换不兼容依赖
  改用适配Cloudflare Worker的轻量替代库：

  • HTTP请求：放弃undici，直接使用Worker原生的fetch API
  • Discord API：使用@cloudflare/discord-interactions这类专为Worker设计的库，或选择不依赖Node内置模块的Discord SDK分支

• 开启Node.js兼容模式（有限支持）
  如果必须使用部分Node.js模块，在wrangler.toml中添加兼容性配置：

  compatibility_flags = ["nodejs_compat"]
  

  此配置会启用Worker对部分Node.js API的兼容支持，但注意：worker_threads、async_hooks这类模块仍无法正常工作。

• 清理依赖树
  用npm ls或pnpm why排查哪些依赖引入了不兼容模块，移除不必要的依赖项，或降级到不依赖Node专属模块的版本。

• 手动Polyfill（谨慎使用）
  对于简单的缺失模块（如events），可以安装npm上的polyfill包（如events），但需注意Worker的代码体积限制（单脚本最大1MB）。

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