fs · Cloudflare Workers docs

你可以使用 node:fs ↗ 访问 Workers 中的虚拟文件系统。

node:fs 模块在支持 Node.js 兼容性的 Workers 运行时中可用，需启用 nodejs_compat 兼容性标志。任何启用了 nodejs_compat 且兼容性日期为 2025-09-01 或更晚的 Worker 默认拥有 node:fs 访问权限。也可通过 nodejs_compat 和 enable_nodejs_fs_module 标志组合，在兼容性日期较早的 Worker 上启用 node:fs。要禁用 node:fs，可设置 disable_nodejs_fs_module 标志。

import { readFileSync, writeFileSync } from "node:fs";

const config = readFileSync("/bundle/config.txt", "utf8");

writeFileSync("/tmp/abc.txt", "Hello, world!");

Workers 虚拟文件系统（VFS）是基于内存的文件系统，允许你将 Worker 包中包含的模块作为只读文件读取、访问用于写入临时文件的目录，或访问常见的字符设备 ↗，如 /dev/null、/dev/random、/dev/full 和 /dev/zero。

初始目录结构如下：


/bundle
└── (one file for each module in your Worker bundle)
/tmp
└── (empty, but you can write files, create directories, symlinks, etc)
/dev
├── null
├── random
├── full
└── zero

/bundle 目录包含 Worker 包中所有模块的文件，可使用 readFileSync 或 read(...) 等 API 读取。这些文件始终为只读。从 bundle 读取在需要读取配置文件或模板时很有用。

import { readFileSync } from "node:fs";

// The config.txt file would be included in your Worker bundle.
// Refer to the Wrangler documentation for details on how to
// include additional files.
const config = readFileSync("/bundle/config.txt", "utf8");

export default {
	async fetch(request) {
		return new Response(`Config contents: ${config}`);
	},
};

/tmp 目录可写，可用于创建临时文件或目录。也可在此目录中创建符号链接。然而，/tmp 的内容不持久，且对每个请求唯一。这意味着在一个请求的上下文中于 /tmp 创建的文件不会在其他并发或后续请求中可用。

import { writeFileSync, readFileSync } from "node:fs";

export default {
	fetch(request) {
		// The file `/tmp/hello.txt` will only exist for the duration
		// of this request.
		writeFileSync("/tmp/hello.txt", "Hello, world!");
		const contents = readFileSync("/tmp/hello.txt", "utf8");
		return new Response(`File contents: ${contents}`);
	},
};

/dev 目录包含常见的字符设备：

/dev/null：空设备，丢弃所有写入数据，读取时返回 EOF。
/dev/random：读取时提供随机字节、丢弃所有写入数据的设备。仅在请求上下文中允许从 /dev/random 读取。
/dev/full：读取时始终返回 EOF、丢弃所有写入数据的设备。
/dev/zero：读取时提供无限零字节流、丢弃所有写入数据的设备。

VFS 上的所有操作均为同步。你可以使用 node:fs 模块提供的同步、异步回调或基于 Promise 的 API，但所有操作都将同步执行。

VFS 中文件的时间戳目前始终设置为 Unix 纪元（1970-01-01T00:00:00Z）。这意味着依赖时间戳的操作（如 fs.stat）将始终为 VFS 中的所有文件返回相同的时间戳。这是临时限制，将在未来版本中解决。

由于所有临时文件都保存在内存中，创建的所有临时文件和目录的总大小计入 Worker 的内存限制。若超出此限制，Worker 实例将被终止并重启。

文件系统实现具有以下限制：

文件路径的最大总长度为 4096 个字符，包括路径分隔符。由于路径在内部作为文件 URL 处理，限制会考虑特殊字符的百分号编码，在检查限制前会对无需编码的字符进行解码。例如，路径 /tmp/abcde%66/ghi%zz 长度为 18 个字符，因为 %66 无需百分号编码，因此计为 1 个字符，而 %zz 是无效的百分号编码，计为 3 个字符。
路径段的最大数量为 48。例如，路径 /a/b/c 为 3 段。
单个文件的最大大小为 128 MB。

以下 node:fs API 在 Workers 中不受支持或仅部分支持：

用于监视文件变更的 fs.watch 和 fs.watchFile 操作。
fs.globSync() 及其他 glob API 尚未实现。
fs.rm API 中的 force 选项尚未实现。
文件时间戳始终设置为 Unix 纪元（1970-01-01T00:00:00Z）。
不支持文件权限和所有权。

完整的 node:fs API 文档见 Node.js node:fs 文档 ↗。