On this page

稳定性：1 - 实验性

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

访问方式：

import vfs from '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')); // 'Hello, VFS!'
JavaScript

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

  • provider {VirtualProvider} 要使用的提供者。默认值： new MemoryProvider()。
  • options <Object>
    Attributes
    emitExperimentalWarning:<boolean>
    在创建实例时是否发出实验性 警告。 默认值： true 。
  • 返回：{VirtualFileSystem}

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

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

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

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

VirtualFileSystem wraps a VirtualProvider and exposes a node:fs-like API. Each instance maintains its own file tree.

The provider backing this VFS instance.

true when the underlying provider is read-only.

  • 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)
  • utimesSync(path, atime, mtime)
  • lutimesSync(path, atime, mtime)
  • mkdtempSync(prefix)
  • opendirSync(path[, options])
  • openAsBlob(path[, options])
  • File descriptor operations: openSync, closeSync, readSync, writeSync, fstatSync
  • Streams: createReadStream, createWriteStream
  • Watchers: watch, watchFile, unwatchFile

readFile、writeFile、stat、lstat、readdir、realpath、readlink、 access、open、close、read、write、rm、fstat、truncate、 ftruncate、link、mkdtemp、opendir。Each method accepts a Node.js-style callback (err, ...result) => {}.

vfs.promises provides promise-based variants:

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();
JavaScript

This promise namespace corresponds to fs.promises, and includes 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, and watch.

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

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

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

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
JavaScript

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

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
JavaScript

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

  • dev is 4085 (the VFS device ID).
  • ino is monotonically increasing within the process.
  • blksize is 4096.
  • blocks is Math.ceil(size / 512).
  • Times are set by default to the moment the entry was created/last modified.