虚拟文件系统

稳定性：1 - 实验性

node:vfs 模块提供了一个具有 node:fs 式 API 的虚拟文件系统。 它适用于测试、测试夹具、内嵌资源，以及其他需要自包含文件系统而无需接触实际文件系统的场景。

访问方式：

import vfs from 'node:vfs';

const vfs = require('node:vfs');

该模块仅在 node: 方案下可用，并且仅当 Node.js 以 --experimental-vfs 标志启动时可用。

VFS API 不是沙箱、权限系统或访问控制机制。 它不会将不受信任的代码与宿主文件系统或其他 Node.js 能力隔离开来。能够访问 VirtualFileSystem 实例、 挂载它、选择其提供程序或向其传递路径的代码，都是受信任的应用程序代码。

挂载 VFS 只会重定向解析后路径位于挂载点下的受支持 node:fs 调用。它不会阻止代码使用其他路径或 其他 Node.js API 访问进程可用的资源。 RealFSProvider 会将 VFS 路径映射到其配置的根目录下，并拒绝解析到该根目录之外的路径，但这种检查并不是安全边界。不要依赖 VFS 来运行不受信任的代码；当需要安全 边界时，请使用操作系统级隔离，例如独立用户、容器或平台沙箱。

const vfs = require('node:vfs');

const myVfs = vfs.create();
myVfs.mkdirSync('/dir', { recursive: true });
myVfs.writeFileSync('/dir/hello.txt', 'Hello, VFS!');

console.log(myVfs.readFileSync('/dir/hello.txt', 'utf8')); // '你好，VFS！'

vfs.create() 默认返回一个由 MemoryProvider 支持的 VirtualFileSystem 实例。该实例公开同步、基于回调以及基于 Promise 的文件系统方法， 其形状与 node:fs API 相对应。所有路径都采用 POSIX 风格并且必须是绝对路径 （以 / 开头）。

vfs.create(provider?, options?): void

便捷工厂函数，等价于 new VirtualFileSystem(provider, options)。

const vfs = require('node:vfs');

// 默认内存提供者
const memoryVfs = vfs.create();

// 显式提供者
const realVfs = vfs.create(new vfs.RealFSProvider('/tmp/vfs-root'));

VirtualFileSystem 封装了一个 VirtualProvider，并提供类似 node:fs 的 API。每个实例都维护自己的文件树。

new VirtualFileSystem(provider?, options?): void

支持此 VFS 实例的提供程序。

当底层提供程序为只读时为 true。

VirtualFileSystem 实现以下方法，其签名与相应的 node:fs 方法匹配：

• existsSync(path)
• statSync(path[, options])
• lstatSync(path[, options])
• readFileSync(path[, options])
• writeFileSync(path, data[, options])
• appendFileSync(path, data[, options])
• readdirSync(path[, options])
• mkdirSync(path[, options])
• rmdirSync(path)
• unlinkSync(path)
• renameSync(oldPath, newPath)
• copyFileSync(src, dest[, mode])
• realpathSync(path[, options])
• readlinkSync(path[, options])
• symlinkSync(target, path[, type])
• accessSync(path[, mode])
• rmSync(path[, options])
• truncateSync(path[, len])
• ftruncateSync(fd[, len])
• linkSync(existingPath, newPath)
• chmodSync(path, mode)
• chownSync(path, uid, gid)
• lchownSync(path, uid, gid)
• utimesSync(path, atime, mtime)
• lutimesSync(path, atime, mtime)
• mkdtempSync(prefix)
• opendirSync(path[, options])
• openAsBlob(path[, options])
• 文件描述符操作：openSync、closeSync、readSync、writeSync、 fstatSync
• 流：createReadStream、createWriteStream
• 监视器：watch、watchFile、unwatchFile

readFile、writeFile、stat、lstat、readdir、realpath、readlink、 access、open、close、read、write、rm、fstat、truncate、 ftruncate、link、mkdtemp、opendir。每个方法都接受 Node.js 风格的 回调 (err, ...result) => {}。

vfs.promises 提供基于 Promise 的变体：

const vfs = require('node:vfs');

async function example() {
  const myVfs = vfs.create();
  await myVfs.promises.writeFile('/file.txt', 'hello');
  const data = await myVfs.promises.readFile('/file.txt', 'utf8');
  return data;
}
example();

此 Promise 命名空间对应于 fs.promises，包含 readFile、 writeFile、appendFile、stat、lstat、readdir、mkdir、rmdir、 unlink、rename、copyFile、realpath、readlink、symlink、 access、rm、truncate、link、mkdtemp、chmod、chown、lchown、 utimes、lutimes、open、lchmod 和 watch。

所有 VFS 提供者的基类。子类实现基本原语（例如 open、stat、readdir、mkdir、rmdir、unlink、rename 等），并继承派生方法（例如 readFile、writeFile、exists、copyFile、access 等）的默认实现。

const { VirtualProvider } = require('node:vfs');

class StaticProvider extends VirtualProvider {
  get readonly() { return true; }

  statSync(path) { /* ... */ }
  openSync(path, flags) { /* ... */ }
  readdirSync(path, options) { /* ... */ }
  // ...
}

对于任何尚未被重写的原语，基类都会抛出 ERR_METHOD_NOT_IMPLEMENTED， 并会对 readonly 提供者拒绝写入并抛出 EROFS。

默认的内存提供者。使用 Map 支持的树结构存储文件、目录和符号链接， 支持符号链接（supportsSymlinks === true），并支持监视（supportsWatch === true）。

memoryProvider.setReadOnly(): void

将提供者锁定为只读模式。之后通过使用此提供者的任何 VirtualFileSystem 进行写入都会抛出 EROFS。没有办法将该提供者恢复为可写。

const vfs = require('node:vfs');

const provider = new vfs.MemoryProvider();
const myVfs = vfs.create(provider);
myVfs.writeFileSync('/seed.txt', 'initial');

provider.setReadOnly();

myVfs.writeFileSync('/x.txt', 'fail'); // 抛出 EROFS

一个包装目录（即实际文件系统上的目录）并通过 VFS API 暴露其内容的提供者。所有 VFS 路径都会相对于根目录进行解析，并验证其始终位于根目录内；解析到根目录外的符号链接会被拒绝。此路径映射不是沙箱或访问控制机制。

new RealFSProvider(rootPath): void

const vfs = require('node:vfs');

const realVfs = vfs.create(new vfs.RealFSProvider('/tmp/vfs-root'));
realVfs.writeFileSync('/file.txt', 'hello'); // 写入 /tmp/vfs-root/file.txt

用作根目录的已解析绝对路径。

VFS Stats 对象是一个真正的 fs.Stats 实例（如果请求 { bigint: true }，则为 fs.BigIntStats 实例）。其字段使用合成但稳定的值：

• dev 为 4085（VFS 设备 ID）。
• ino 在进程内单调递增。
• blksize 为 4096。
• blocks 为 Math.ceil(size / 512)。
• 默认情况下，时间设置为条目创建或最后修改的时刻。