Skip to main content
VFS 沙盒使用内存中的虚拟文件系统完全在本地运行。无需云服务、Docker 或外部依赖项——非常适合开发和测试。 它使用 node-vfs-polyfill，该库实现了即将推出的 Node.js VFS 功能 (nodejs/node#61478)。

​
设置

npm install @langchain/node-vfs
无需认证。

​
与 deepagents 结合使用

import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { VfsSandbox } from "@langchain/node-vfs";

const sandbox = await VfsSandbox.create({
  initialFiles: {
    "/src/index.js": "console.log("Hello from VFS!")",
  },
});

try {
  const agent = createDeepAgent({
    model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
    systemPrompt: "You are a coding assistant with VFS access.",
    backend: sandbox,
  });

  const result = await agent.invoke({
    messages: [{ role: "user", content: "Run the index.js file" }],
  });
} finally {
  await sandbox.stop();
}

​
独立使用

import { VfsSandbox } from "@langchain/node-vfs";

const sandbox = await VfsSandbox.create({
  initialFiles: {
    "/src/index.js": "console.log("Hello from VFS!")",
  },
});

const result = await sandbox.execute("node /src/index.js");
console.log(result.output); // "Hello from VFS!"

await sandbox.stop();

​
配置

选项类型默认值描述
mountPathstring"/vfs"虚拟文件系统的挂载路径
timeoutnumber30000命令执行超时时间（毫秒）
initialFilesRecord<string, string | Uint8Array>-填充 VFS 的初始文件

​
工作原理

VFS 采用混合方法以实现最大兼容性：
  1. 文件存储：文件使用虚拟文件系统存储在内存中
  2. 命令执行：执行命令时，文件同步到临时目录，运行命令，然后更改同步回 VFS
  3. 回退模式：如果 node-vfs-polyfill 不可用，则回退到使用临时目录进行存储和执行
这提供了内存存储的好处（隔离、速度），同时保持了完整的 Shell 命令执行支持。

​
文件操作

// Upload files
const encoder = new TextEncoder();
await sandbox.uploadFiles([
  ["src/app.js", encoder.encode("console.log("Hi")")],
  ["package.json", encoder.encode("{"name": "test"}")],
]);

// Download files
const results = await sandbox.downloadFiles(["src/app.js"]);
for (const result of results) {
  if (result.content) {
    console.log(new TextDecoder().decode(result.content));
  }
}

​
工厂函数

import { createVfsSandboxFactory, createVfsSandboxFactoryFromSandbox } from "@langchain/node-vfs";

// Create new sandbox per invocation
const factory = createVfsSandboxFactory({
  initialFiles: { "/README.md": "# Hello" },
});

// Or reuse an existing sandbox across invocations
const sandbox = await VfsSandbox.create();
const reuseFactory = createVfsSandboxFactoryFromSandbox(sandbox);

​
错误处理

import { VfsSandboxError } from "@langchain/node-vfs";

try {
  await sandbox.execute("some-command");
} catch (error) {
  if (error instanceof VfsSandboxError) {
    switch (error.code) {
      case "NOT_INITIALIZED":
        // Handle uninitialized sandbox
        break;
      case "COMMAND_TIMEOUT":
        // Handle timeout
        break;
    }
  }
}

​
错误代码

代码描述
NOT_INITIALIZED沙盒未初始化
ALREADY_INITIALIZED沙盒已初始化
INITIALIZATION_FAILED初始化 VFS 失败
COMMAND_TIMEOUT命令执行超时
COMMAND_FAILED命令执行失败
FILE_OPERATION_FAILED文件操作失败
NOT_SUPPORTED环境不支持 VFS

​
何时使用 VFS

最适合：
  • 本地开发和测试
  • 无需 Docker 的 CI/CD 管道
  • 无需云设置的快速原型设计
  • 外部服务不可用的环境
不适合：
  • 需要真正容器隔离的生产工作负载
  • 跨会话的持久存储
  • 繁重的计算任务（无资源限制）

​
未来：原生 Node.js VFS

此包使用 node-vfs-polyfill，它实现了 nodejs/node#61478 中正在开发的即将推出的 Node.js VFS 功能。当官方 node:vfs 模块在 Node.js 中发布时，此包将更新以使用原生实现。
在 GitHub 上编辑此页面 或 提交 issue.
将这些文档连接 到 Claude、VSCode 等，通过 MCP 获取实时答案。