启用nodejs_compat后Cloudflare Worker仍提示“No such module 'node:fs' / 'fs'”错误的技术问询
启用nodejs_compat后Cloudflare Worker仍提示“No such module 'node:fs' / 'fs'”错误的技术问询
我来帮你拆解这个问题,你遇到的情况其实是因为Cloudflare Workers的Node.js兼容层有一些容易被忽略的细节,咱们一步步来解决:
一、为什么会出现“No such module”错误?
你已经开启了nodejs_compat兼容标志,但这只是启用了基础的Node.js API兼容层,并不是所有Node.js核心模块都会默认开启。node:fs属于需要显式指定启用的模块,你需要在wrangler.toml里额外添加nodejs_compat_modules配置项,把要用到的模块列进去:
修改后的wrangler.toml示例:
name = "my-worker" main = "src/index.ts" compatibility_date = "2025-09-21" compatibility_flags = ["nodejs_compat"] nodejs_compat_modules = ["node:fs"]
这样Wrangler才会把node:fs模块注入到你的Worker运行环境中,之前的错误就是因为没有显式声明要启用这个模块。
二、关于node:fs在Workers中的使用限制
即使启用了node:fs,它的行为和你在本地Node.js环境里用的也不一样,有几个关键限制要注意:
- 不能直接读取你本地仓库里的文件:Worker部署后是在Cloudflare的边缘节点运行,不会挂载你的本地代码仓库的文件系统,你本地的
./foo.txt在Worker运行时根本不存在。 - Worker里的文件系统是虚拟/临时的:
node:fs在Workers中的实现是基于边缘节点的临时存储,这个存储是无状态、短暂的,每次请求结束后数据就会被清理,而且不同边缘节点的存储是完全独立的,不能用来持久化或者读取本地项目文件。
三、如果要读取项目中的静态文件,该怎么做?
如果你的需求是读取项目里的静态文件(比如foo.txt),有两种更合适的方案:
- 把文件作为Worker的绑定资产:在
wrangler.toml里配置[[assets]]字段,把静态文件打包到Worker部署包中,然后通过绑定的资产对象来读取文件内容。
示例配置:
然后在代码里这样读取:[[assets]] binding = "ASSETS" bucket = "./public" # 假设foo.txt放在项目的public目录下 entry-point = "src"export default { async fetch(request, env) { const fileResponse = await env.ASSETS.fetch("foo.txt"); const txt = await fileResponse.text(); return new Response(txt); }, }; - 把文件内容嵌入到代码中:如果文件很小,可以直接把内容作为字符串写在代码里;或者用构建工具(比如ESBuild)把文件内容打包成模块导入,比如在TypeScript里用
import fooTxt from "./foo.txt?raw"(需要配置ESBuild支持raw加载器)。
四、补充:关于node:fs的实际适用场景
如果一定要用node:fs,它一般只适合处理Worker运行时生成的临时文件,或者配合Cloudflare的其他服务(比如R2)的虚拟文件系统绑定,但这种场景比较少见,大多数静态文件读取需求用上面两种方案更合适。
最后再提个小检查点:你可以试试把compatibility_date更新到当前最新的月份,有时候稍旧的日期可能会有模块支持的延迟,确保配置和运行时的支持完全匹配。




