# https://github.com/e2b-dev/E2B 项目说明书

生成时间：2026-05-17 14:04:55 UTC

## 目录

- [项目介绍](#page-1)
- [系统架构](#page-2)
- [JavaScript/TypeScript SDK](#page-3)
- [Python SDK](#page-4)
- [CLI 命令行工具](#page-5)
- [沙箱生命周期管理](#page-6)
- [文件系统操作](#page-7)
- [Git 操作与网络配置](#page-8)
- [模板系统与构建](#page-9)
- [模板生成器与 Handlebars 模板](#page-10)

<a id='page-1'></a>

## 项目介绍

### 相关页面

相关主题：[系统架构](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)
- [packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)
- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)
- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)
- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)
- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)
- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)
- [packages/js-sdk/src/template/readycmd.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/readycmd.ts)
- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)
- [packages/js-sdk/src/sandbox/commands/commandHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/commandHandle.ts)
- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)
- [packages/python-sdk/e2b/api/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/client.py)
- [packages/python-sdk/e2b/volume/client/client.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/volume/client/client.py)
- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)
- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)
- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)
</details>

# 项目介绍

## 概述

E2B 是一个开源基础设施项目，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。该项目提供了 JavaScript SDK（Node.js）和 Python SDK 两套开发工具包，使开发者能够轻松启动和控制云端沙箱环境。资料来源：[packages/python-sdk/README.md:1]()

E2B 的核心价值在于为 AI 应用提供了一个安全、可控的代码执行环境。当 AI 模型生成代码后，开发者可以通过 E2B 在隔离的沙箱中运行这些代码，而无需担心安全问题或资源污染。资料来源：[packages/js-sdk/README.md:1]()

## 核心功能

### 安全沙箱环境

E2B 沙箱是基于 Docker 容器技术构建的安全隔离环境。每个沙箱都是完全独立的，拥有自己的文件系统、网络和进程空间。这种隔离确保了运行在沙箱中的代码不会影响主机系统或其他沙箱。资料来源：[packages/js-sdk/src/sandbox/index.ts:1]()

沙箱支持以下关键安全特性：

| 特性 | 说明 | 默认值 |
|------|------|--------|
| 互联网访问 | 控制沙箱是否可访问外部网络 | 启用 |
| 安全模式 | 启用额外的安全限制 | 启用 |
| 网络隔离 | 自定义网络配置 | 支持 |

资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()

### 多语言 SDK 支持

E2B 提供了两个官方的 SDK 实现：

#### JavaScript SDK

JavaScript SDK 面向 Node.js 环境，支持 TypeScript 和 JavaScript。安装方式如下：

```bash
npm i e2b
```

该 SDK 提供了完整的沙箱控制能力，包括文件系统操作、命令执行、进程管理等。资料来源：[packages/js-sdk/README.md:1]()

#### Python SDK

Python SDK 面向 Python 环境，支持 Python 3.x。安装方式如下：

```bash
pip install e2b
```

该 SDK 提供了与 JavaScript SDK 类似的功能，并针对 Python 生态进行了优化。资料来源：[packages/python-sdk/README.md:1]()

### 模板系统

E2B 的模板系统允许开发者定义预配置的沙箱环境。模板本质上是一个 Dockerfile，包含了基础镜像、环境变量、依赖安装等配置。资料来源：[packages/js-sdk/src/template/index.ts:1]()

模板支持多种基础镜像来源：

| 方法 | 描述 | 示例 |
|------|------|------|
| from_base_image | E2B 默认基础镜像 | e2bdev/base:latest |
| from_python_image | Python 环境 | python:3 |
| from_node_image | Node.js 环境 | node:lts |
| from_bun_image | Bun 环境 | oven/bun:latest |
| from_debian_image | Debian 环境 | debian:bookworm |
| from_ubuntu_image | Ubuntu 环境 | ubuntu:24.04 |
| from_image | 自定义镜像 | 自定义镜像名称 |

资料来源：[packages/js-sdk/src/template/types.ts:1]()

模板构建过程会将所有指令转换为 Dockerfile 格式，包括 RUN、COPY、ENV 等指令。资料来源：[packages/js-sdk/src/template/index.ts:1]()

### 命令执行系统

沙箱支持通过命令执行系统运行任意命令。每个命令执行后会返回标准输出、标准错误和退出码。资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()

命令执行的核心特性包括：

```typescript
interface CommandResult {
  stdout: string    // 标准输出
  stderr: string    // 标准错误
  exitCode: number  // 退出码，0 表示成功
  error?: string    // 错误信息
}
```

开发者可以通过 `wait()` 方法异步等待命令执行完成，如果命令以非零退出码结束，将抛出 `CommandExitError` 异常。资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()

### 文件系统操作

E2B 提供了强大的文件系统操作能力，支持多种文件格式读取和写入。资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts:1]()

#### 文件读取格式

| 格式 | 说明 | 适用场景 |
|------|------|----------|
| text | 文本格式（默认） | 读取文本文件 |
| bytes | 字节数组 | 读取二进制文件 |
| blob | Blob 对象 | Web 环境文件处理 |
| stream | 可读流 | 大文件流式处理 |

资料来源：[packages/js-sdk/src/volume/index.ts:1]()

#### 文件写入

文件写入支持 gzip 压缩传输，并可通过 `use_octet_stream` 参数选择使用 multipart/form-data 或 application/octet-stream 格式上传。资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py:1]()

### 就绪检查命令

模板系统支持设置启动命令和就绪检查命令。就绪检查确保沙箱中的服务完全启动后才标记为可用状态。资料来源：[packages/python-sdk/e2b/template/main.py:1]()

E2B 提供了几个内置的就绪检查工具：

| 函数 | 描述 | 实现方式 |
|------|------|----------|
| waitForURL | 等待 HTTP URL 返回指定状态码 | curl + grep |
| waitForProcess | 等待指定名称的进程运行 | pgrep |
| waitForFile | 等待文件存在 | shell test |

资料来源：[packages/js-sdk/src/template/readycmd.ts:1]()

### 存储卷管理

E2B 支持持久化存储卷功能，允许沙箱挂载外部存储。这些存储卷可以在沙箱之间共享数据，或用于持久化存储重要数据。资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()

存储卷挂载配置示例：

```typescript
const sandbox = await Sandbox.create('template-name', {
  volumeMounts: {
    '/data': 'my-volume-name'
  }
})
```

资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1]()

### MCP 服务器集成

E2B 模板系统支持集成 MCP（Model Context Protocol）服务器，允许在沙箱中运行各种 MCP 服务。资料来源：[packages/python-sdk/e2b/template/main.py:1]()

添加 MCP 服务器的示例：

```python
template.add_mcp_server('exa')
template.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
```

注意：使用 MCP 服务器需要基础镜像预装了 mcp-gateway。资料来源：[packages/python-sdk/e2b/template/main.py:1]()

## 系统架构

### 整体架构

```mermaid
graph TD
    A[开发者应用] --> B[E2B SDK]
    B --> C[API Gateway]
    C --> D[Sandbox Manager]
    D --> E[Docker Container]
    E --> F[envd Agent]
    F --> G[文件系统]
    F --> H[网络栈]
    F --> I[进程管理]
```

### SDK 分层架构

```mermaid
graph TD
    A[用户代码] --> B[高级 API]
    B --> C[连接配置]
    C --> D[API Client]
    D --> E[HTTP/REST]
```

## API 客户端配置

E2B SDK 内部使用 HTTP 客户端与后端 API 通信，支持丰富的配置选项。资料来源：[packages/python-sdk/e2b/api/client/client.py:1]()

| 配置项 | 说明 |
|--------|------|
| base_url | API 基础 URL |
| timeout | 请求超时时间 |
| verify_ssl | 是否验证 SSL 证书 |
| follow_redirects | 是否跟随重定向 |
| cookies | 请求 Cookie |
| headers | 自定义请求头 |
| httpx_args | 额外传递给 httpx 的参数 |

资料来源：[packages/python-sdk/e2b/api/client/client.py:1]()

## 命令行工具

E2B 提供了命令行工具用于管理模板。主要命令包括：

### 模板构建

```bash
e2b template build
```

该命令会根据指定目录下的 Dockerfile 或模板配置构建沙箱模板。资料来源：[packages/cli/src/commands/template/build.ts:1]()

### 模板创建

```bash
e2b template create
```

该命令用于创建新的沙箱模板，支持交互式配置。资料来源：[packages/cli/src/commands/template/create.ts:1]()

## 快速开始

### 1. 安装 SDK

根据使用的编程语言选择对应的 SDK 安装命令：

```bash
# JavaScript/TypeScript
npm i e2b

# Python
pip install e2b
```

### 2. 获取 API 密钥

1. 访问 [e2b.dev](https://e2b.dev) 注册账号
2. 在仪表板获取 API 密钥
3. 设置环境变量

```bash
export E2B_API_KEY=e2b_***
```

### 3. 创建沙箱

**JavaScript 示例：**

```javascript
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('python-default')
const result = await sandbox.commands.run('echo "Hello World"')
console.log(result.stdout)
await sandbox.close()
```

**Python 示例：**

```python
import e2b

sandbox = e2b.Sandbox()
result = sandbox.commands.run('echo "Hello World"')
print(result.stdout)
sandbox.close()
```

## 环境变量配置

| 变量名 | 说明 | 必需 |
|--------|------|------|
| E2B_API_KEY | API 认证密钥 | 是 |
| E2B_SANDBOX_TIMEOUT | 默认沙箱超时时间（毫秒） | 否 |
| E2B_DEBUG | 启用调试模式 | 否 |

## 错误处理

E2B SDK 定义了多种错误类型用于处理不同的异常情况：

| 错误类型 | 说明 |
|----------|------|
| SandboxError | 沙箱基础错误 |
| CommandExitError | 命令执行失败（退出码非0） |
| NotFoundError | 资源未找到 |
| TemplateError | 模板相关错误 |
| TimeoutError | 操作超时 |

资料来源：[packages/js-sdk/src/sandbox/commands/commandHandle.ts:1]()

## 相关资源

- 官方网站：[https://www.e2b.dev/](https://www.e2b.dev/)
- JavaScript SDK NPM：[https://www.npmjs.com/package/e2b](https://www.npmjs.com/package/e2b)
- Python SDK PyPI：[https://pypi.org/project/e2b/](https://pypi.org/project/e2b/)

---

<a id='page-2'></a>

## 系统架构

### 相关页面

相关主题：[项目介绍](#page-1), [JavaScript/TypeScript SDK](#page-3), [Python SDK](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/js-sdk/src/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/index.ts)
- [packages/js-sdk/src/sandbox/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/index.ts)
- [packages/python-sdk/e2b/sandbox/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/main.py)
- [packages/js-sdk/src/envd/api.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/api.ts)
- [packages/python-sdk/e2b/envd/api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/api.py)
- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)
- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)
- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)
- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)
</details>

# 系统架构

## 概述

E2B 是一个开源基础设施平台，允许用户在云端安全隔离的沙箱环境中运行 AI 生成的代码。系统架构围绕三个核心概念构建：**沙箱（Sandbox）**、**模板（Template）** 和 **API 客户端**。这种设计使得开发者可以通过 SDK 定义可复现的运行时环境，并动态创建和管理隔离的执行实例。

资料来源：[README.md:1-10]()

## 核心组件架构

E2B 系统由以下主要组件构成：

| 组件 | 语言实现 | 职责 |
|------|---------|------|
| JavaScript SDK | TypeScript | 提供浏览器和 Node.js 环境下的沙箱管理能力 |
| Python SDK | Python | 提供 Python 环境下的沙箱管理能力 |
| CLI 工具 | TypeScript | 提供命令行界面用于模板管理和部署 |
| API 网关 | 后端服务 | 处理沙箱生命周期请求和状态管理 |
| envd 服务 | 后端服务 | 在沙箱内部执行命令和文件操作 |

资料来源：[packages/js-sdk/README.md:1-20]()

## SDK 架构

### SDK 导出结构

JavaScript SDK 和 Python SDK 都遵循统一的模块化设计，核心导出包括：

```mermaid
graph TD
    A[E2B SDK] --> B[Sandbox 类]
    A --> C[Template 类]
    A --> D[辅助函数]
    B --> B1[启动/停止沙箱]
    B --> B2[文件系统操作]
    B --> B3[进程管理]
    B --> B4[网络访问]
    C --> C1[基础镜像选择]
    C --> C2[依赖安装]
    C --> C3[环境变量配置]
    C --> C4[启动命令设置]
```

资料来源：[packages/js-sdk/src/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()

### API 客户端架构

SDK 通过统一的 API 客户端与后端服务通信：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `apiKey` | E2B API 密钥 | 环境变量 `E2B_API_KEY` |
| `baseURL` | API 基础地址 | `https://api.e2b.dev` |
| `timeout` | 请求超时时间 | 60000ms |
| `headers` | 自定义请求头 | 包含 SDK 版本、运行时信息 |

资料来源：[packages/js-sdk/src/api/metadata.ts:1-20]()

## 沙箱（Sandbox）架构

### 沙箱生命周期

```mermaid
stateDiagram-v2
    [*] --> 创建中: 调用 sandbox.start()
    创建中 --> 运行中: envd 服务就绪
    运行中 --> 暂停中: 调用 sandbox.pause()
    暂停中 --> 运行中: 调用 sandbox.resume()
    运行中 --> 停止中: 调用 sandbox.kill() 或超时
    停止中 --> [*]
```

资料来源：[packages/js-sdk/src/sandbox/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()

### 沙箱创建请求

沙箱创建时，SDK 向后端发送包含完整配置的对象：

```typescript
interface NewSandbox {
  templateID: string;           // 模板标识符
  metadata?: Record<string, unknown>;
  mcp?: Record<string, unknown>; // MCP 服务器配置
  envVars?: Record<string, string>;
  timeout?: number;              // 超时时间（秒）
  secure?: boolean;              // 安全模式
  allow_internet_access?: boolean;
  network?: NetworkConfig;
  autoPause?: boolean;
  autoResume?: { enabled: boolean };
  volumeMounts?: VolumeMount[];
}
```

资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:1-30]()

### 沙箱文件系统

沙箱提供虚拟文件系统，支持以下操作：

| 操作 | JavaScript SDK | Python SDK |
|------|---------------|------------|
| 读取文件 | `sandbox.fs.read(path)` | `sandbox.fs.read(path)` |
| 写入文件 | `sandbox.fs.write(path, content)` | `sandbox.fs.write(path, content)` |
| 列出目录 | `sandbox.fs.list(path)` | `sandbox.fs.list(path)` |
| 创建目录 | `sandbox.fs.makeDir(path)` | `sandbox.fs.make_dir(path)` |

资料来源：[packages/js-sdk/src/sandbox/index.ts]()、[packages/python-sdk/e2b/sandbox/main.py]()

## 模板（Template）架构

### 模板构建器模式

Template 使用流式构建器（Builder）模式，允许链式调用定义环境：

```mermaid
graph LR
    A[Template] --> B[基础镜像]
    B --> C[依赖安装]
    C --> D[环境变量]
    D --> E[启动命令]
    E --> F[TemplateFinal]
```

资料来源：[packages/js-sdk/src/template/types.ts:1-50]()

### 模板配置选项

| 配置方法 | 功能 | 示例 |
|---------|------|------|
| `from_image(image)` | 从指定 Docker 镜像创建 | `from_image("python:3.11")` |
| `from_python_image(version)` | 从 Python 官方镜像创建 | `from_python_image("3")` |
| `from_node_image(variant)` | 从 Node.js 官方镜像创建 | `from_node_image("lts")` |
| `from_bun_image(variant)` | 从 Bun 官方镜像创建 | `from_bun_image("latest")` |
| `from_base_image()` | 从 E2B 基础镜像创建 | - |
| `run_cmd(cmd)` | 执行 shell 命令 | `run_cmd("pip install flask")` |
| `copy(src, dest)` | 复制文件到沙箱 | `copy("./app", "/app")` |
| `set_envs(envs)` | 设置环境变量 | `set_envs({"PORT": "3000"})` |
| `npm_install()` / `pip_install()` | 安装语言依赖 | - |
| `apt_install(packages)` | 安装系统包 | `apt_install(["vim"])` |
| `bun_install()` | 使用 Bun 安装依赖 | - |
| `set_start_cmd(cmd, ready_cmd)` | 设置启动命令 | `set_start_cmd("npm start", waitForURL("..."))` |

资料来源：[packages/js-sdk/src/template/types.ts:50-150]()、[packages/python-sdk/e2b/template/main.py:1-100]()

### 模板构建流程

```mermaid
graph TD
    A[定义 Template] --> B[调用 build 方法]
    B --> C[生成 Dockerfile]
    C --> D[上传到 E2B 构建服务]
    D --> E{构建状态}
    E -->|building| F[轮询构建状态]
    F --> E
    E -->|success| G[返回 BuildInfo]
    E -->|error| H[抛出 BuildError]
```

资料来源：[packages/js-sdk/src/template/index.ts:1-80]()

### 启动就绪检查

系统支持多种就绪检查策略：

| 函数 | 用途 | 实现方式 |
|------|------|---------|
| `waitForURL(url, statusCode)` | 等待 HTTP URL 可访问 | curl + grep |
| `waitForProcess(name)` | 等待进程运行 | pgrep |
| `waitForFile(path)` | 等待文件存在 | shell test |

资料来源：[packages/js-sdk/src/template/readycmd.ts:1-50]()

## 环境变量和配置

### SDK 配置

| 环境变量 | 说明 | JavaScript SDK | Python SDK |
|----------|------|---------------|------------|
| `E2B_API_KEY` | API 认证密钥 | ✅ | ✅ |
| `E2B_BASE_URL` | 自定义 API 地址 | 可选 | 可选 |
| `E2B_TIMEOUT` | 默认超时时间 | 可选 | 可选 |

资料来源：[packages/js-sdk/src/api/metadata.ts:1-20]()

### 沙箱环境变量

沙箱创建时可传入环境变量，格式为键值对映射：

```python
# Python SDK 示例
sandbox = Sandbox(
    template="my-template",
    envs={
        "NODE_ENV": "production",
        "DATABASE_URL": "postgres://..."
    }
)
```

```typescript
// JavaScript SDK 示例
const sandbox = await Sandbox.create({
    template: "my-template",
    envs: {
        "NODE_ENV": "production",
        "DATABASE_URL": "postgres://..."
    }
})
```

资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:10-20]()

## MCP 服务器集成

E2B 支持 MCP（Model Context Protocol）服务器集成，允许沙箱访问外部工具和服务：

```mermaid
graph LR
    A[MCP 服务器] -->|mcp-gateway| B[沙箱环境]
    B --> C[SDK 调用]
    C --> D[工具执行]
```

| 方法 | 说明 |
|------|------|
| `add_mcp_server(servers)` | 添加 MCP 服务器 |
| `Template.betaDevContainerPrebuild()` | 预构建 devcontainer |
| `Template.betaSetDevContainerStart()` | 设置 devcontainer 启动 |

资料来源：[packages/js-sdk/src/template/types.ts:100-130]()

## 部署架构

### 模板构建部署

```mermaid
graph LR
    A[本地开发] --> B[定义 Template]
    B --> C[Template.build]
    C --> D[E2B API]
    D --> E[Docker 构建]
    E --> F[镜像仓库]
    F --> G[生产环境]
```

资料来源：[packages/cli/src/commands/template/build.ts:1-50]()

### 构建产物

| 产物 | 说明 |
|------|------|
| Docker 镜像 | 存储在 E2B 镜像仓库中 |
| 模板元数据 | 包含镜像 ID、别名、标签等信息 |
| 构建日志 | 用于调试构建问题 |

## 安全模型

| 安全特性 | 说明 |
|---------|------|
| 隔离执行 | 每个沙箱在独立容器中运行 |
| 网络控制 | 可配置 `allow_internet_access` |
| 超时机制 | 可设置沙箱最大运行时间 |
| 安全模式 | 可启用 `secure: true` 增强隔离 |

资料来源：[packages/js-sdk/src/sandbox/sandboxApi.ts:15-25]()

## 依赖安装方法对比

| 包管理器 | JS SDK | Python SDK | 系统级 |
|---------|--------|-----------|--------|
| npm/yarn | `npm_install()` | - | - |
| pip | - | `pip_install()` | - |
| pip3 | - | `pip_install()` | - |
| apt-get | `apt_install()` | `apt_install()` | ✅ |
| bun | `bun_install()` | `bun_install()` | - |
| 全局安装 | `npm_install(g=True)` | - | - |

资料来源：[packages/js-sdk/src/template/types.ts:80-120]()、[packages/python-sdk/e2b/template/main.py:50-150]()

## 总结

E2B 系统架构采用分层设计，通过统一的 SDK 抽象隐藏底层复杂性：

- **表现层**：JavaScript SDK 和 Python SDK 提供统一的 API
- **通信层**：API 客户端处理认证、请求序列化和错误处理
- **服务层**：后端 API 和 envd 服务管理沙箱生命周期
- **执行层**：Docker 容器提供资源隔离

这种架构使得开发者可以专注于业务逻辑，而无需关心底层基础设施的复杂性。

---

<a id='page-3'></a>

## JavaScript/TypeScript SDK

### 相关页面

相关主题：[系统架构](#page-2), [Python SDK](#page-4), [沙箱生命周期管理](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)
- [packages/js-sdk/src/api/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)
- [packages/js-sdk/src/api/metadata.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)
- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)
- [packages/js-sdk/src/sandbox/mcp.d.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/mcp.d.ts)
- [packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)
- [packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)
- [packages/js-sdk/src/envd/schema.gen.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)
</details>

# JavaScript/TypeScript SDK

## 概述

E2B JavaScript/TypeScript SDK 是一个开源基础设施，允许用户在云端安全隔离的沙箱中运行 AI 生成的代码。该 SDK 提供了启动和控制沙箱的完整能力，支持 Node.js、Browser 和 Deno 运行时环境。

资料来源：[packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)

### 核心能力

| 功能模块 | 描述 |
|---------|------|
| 沙箱管理 | 创建、启动、停止和管理云端沙箱 |
| 文件系统操作 | 在沙箱中读写文件、执行命令 |
| 模板系统 | 构建可复用的沙箱模板 |
| MCP 集成 | 支持 Model Context Protocol 服务器 |
| API 通信 | 通过 gRPC 和 REST 与后端服务通信 |

资料来源：[packages/js-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)

## 架构设计

### 技术栈

```mermaid
graph TD
    A[JavaScript SDK] --> B[@connectrpc/connect-web]
    A --> C[@bufbuild/protobuf]
    A --> D[openapi-fetch]
    
    E[沙箱环境] --> F[envd 服务]
    F --> G[文件系统 API]
    F --> H[命令执行 API]
    F --> I[环境变量 API]
    
    B --> E
    C --> E
    D --> J[REST API]
```

### 依赖关系

SDK 核心依赖包括：

| 依赖包 | 版本 | 用途 |
|-------|------|------|
| @bufbuild/protobuf | ^2.6.2 | Protocol Buffers 序列化 |
| @connectrpc/connect | 2.0.0-rc.3 | gRPC-Web 通信协议 |
| @connectrpc/connect-web | 2.0.0-rc.3 | Web 端 gRPC 支持 |
| openapi-fetch | ^0.14.1 | REST API 调用 |
| chalk | ^5.3.0 | 控制台输出格式化 |
| glob | ^11.1.0 | 文件模式匹配 |

资料来源：[packages/js-sdk/package.json:18-36](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)

### 运行时支持

SDK 支持多种 JavaScript 运行时环境：

- **Node.js**: 主要支持版本 >=18
- **Browser**: 支持现代浏览器环境
- **Deno**: 原生支持 Deno 运行时

资料来源：[packages/js-sdk/src/api/metadata.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)

## 安装与配置

### 安装方式

```bash
npm i e2b
```

### 环境变量配置

```bash
E2B_API_KEY=e2b_your_api_key_here
```

SDK 通过以下方式获取环境变量：

资料来源：[packages/js-sdk/src/api/metadata.ts:17-29](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)

```typescript
export function getEnvVar(name: string) {
  if (runtime === 'deno') {
    return Deno.env.get(name)
  }

  if (typeof process === 'undefined') {
    return ''
  }

  return process.env[name]
}
```

### 默认请求头

SDK 自动附加以下元数据头：

| 头信息 | 来源 | 说明 |
|-------|------|------|
| browser | platform.name | 浏览器标识 |
| lang | js | 语言标识 |
| lang_version | runtimeVersion | 运行时版本 |
| package_version | package.json | SDK 版本 |
| publisher | e2b | 发布者标识 |
| sdk_runtime | runtime | 运行时类型 |
| system | platform.os?.family | 操作系统类型 |

资料来源：[packages/js-sdk/src/api/metadata.ts:7-15](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/metadata.ts)

## API 端点

### 沙箱管理接口

#### 创建沙箱

```
POST /sandboxes
```

请求体 schema 定义：

资料来源：[packages/js-sdk/src/api/schema.gen.ts:18-35](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)

```typescript
interface paths {
    "/sandboxes": {
        post: {
            parameters: {
                query?: never;
                header?: never;
                path?: never;
                cookie?: never;
            };
            requestBody: {
                content: {
                    "application/json": components["schemas"]["NewSandbox"];
                };
            };
            responses: {
                201: {
                    headers: { [name: string]: unknown };
                    content: { "application/json": components["schemas"]["Sandbox"] };
                };
            };
        };
    };
}
```

#### 获取沙箱列表

```
GET /sandboxes
```

| 参数 | 类型 | 说明 |
|-----|------|------|
| metadata | string | 元数据过滤条件（URL 编码） |

响应示例：

```json
{
  "application/json": components["schemas"]["ListedSandbox"][]
}
```

资料来源：[packages/js-sdk/src/api/schema.gen.ts:1-25](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/api/schema.gen.ts)

### 环境变量接口

#### 获取环境变量

```
GET /envs
```

响应结构：

```typescript
interface paths {
    "/envs": {
        get: {
            parameters: {
                query?: never;
                header?: never;
                path?: never;
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                200: {
                    headers: { [name: string]: unknown };
                    content: {
                        "application/json": components["schemas"]["EnvVars"];
                    };
                };
            };
        };
    };
}
```

资料来源：[packages/js-sdk/src/envd/schema.gen.ts:1-35](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)

### 文件操作接口

#### 下载文件

```
GET /files
```

| 参数 | 类型 | 说明 |
|-----|------|------|
| path | string | 文件路径（URL 编码） |
| signature | string | 文件访问签名 |
| signature_expiration | string | 签名过期时间 |
| username | string | 用户标识 |

资料来源：[packages/js-sdk/src/envd/schema.gen.ts:50-65](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/envd/schema.gen.ts)

## MCP 服务器支持

SDK 提供完整的 Model Context Protocol (MCP) 服务器类型定义。

### 支持的 MCP 服务器类型

资料来源：[packages/js-sdk/src/sandbox/mcp.d.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/mcp.d.ts)

| 类别 | 服务器 |
|------|--------|
| 云服务 | awsCore, awsCdk, awsDiagram, awsDocumentation, awsTerraform, azure, aks |
| 搜索 | brave, exa, braveSearch |
| 数据库 | astraDb, chroma, clickhouse, cdataConnectcloud |
| 开发工具 | circleci, buildkite, camunda, apify |
| 文档 | astroDocs, atlasDocs, atlan |
| 安全 | beagleSecurity |
| 通信 | atlassian, close, audienseInsights |

### MCP 服务器接口定义

```typescript
export interface McpServer {
  airtable?: AirtableMCPServer;
  aks?: AzureKubernetesServiceAKS;
  apiGateway?: ApiGateway;
  apify?: ApifyMCPServer;
  arxiv?: ArXivMCPServer;
  astGrep?: AstGrep;
  // ... 更多服务器类型
}
```

## 模板系统

### 模板类型定义

资料来源：[packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)

SDK 提供链式 API 构建模板：

```typescript
interface TemplateBuilder {
  // 包管理器安装
  npmInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;
  bunInstall(packages?: string | string[], options?: { g?: boolean; dev?: boolean }): TemplateBuilder;
  yarnInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;
  pnpmInstall(packages?: string | string[], options?: { dev?: boolean }): TemplateBuilder;
  
  // 系统包安装
  aptInstall(packages: string | string[], options?: { noInstallRecommends?: boolean; fixMissing?: boolean }): TemplateBuilder;
  
  // MCP 服务器
  addMcpServer(servers: string | string[]): TemplateBuilder;
}
```

### 模板使用示例

```typescript
// 使用基础镜像创建模板
const template = Template()
  .fromBaseImage()
  .runCmd('echo Hello World E2B!')

// 安装 npm 包
template.npmInstall('express')
template.npmInstall(['lodash', 'axios'])
template.npmInstall('typescript', { dev: true })

// 安装系统包
template.aptInstall('vim')
template.aptInstall(['git', 'curl'], { noInstallRecommends: true })

// 添加 MCP 服务器
template.addMcpServer('exa')
template.addMcpServer(['brave', 'github'])
```

## 快速开始

### 基本使用流程

```mermaid
graph LR
    A[初始化 SDK] --> B[创建沙箱]
    B --> C[执行命令/操作文件]
    C --> D[获取结果]
    D --> E[停止沙箱]
```

### 完整示例

资料来源：[packages/js-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)

```typescript
import { Sandbox } from 'e2b'

// 创建沙箱实例
const sandbox = await Sandbox.create()

// 执行命令
const result = await sandbox.commands.run('echo "Hello from E2B!"')

// 读写文件
await sandbox.filesystem.write('/data/example.txt', 'Hello World')
const content = await sandbox.filesystem.read('/data/example.txt')

// 停止沙箱
await sandbox.close()
```

### 环境变量设置

```typescript
// 设置 API 密钥
const E2B_API_KEY = process.env.E2B_API_KEY
```

## 构建配置

### tsup 配置

资料来源：[packages/js-sdk/tsup.config.js](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/tsup.config.js)

```javascript
export default defineConfig({
  minify: false,
  target: ['es2017'],
  sourcemap: true,
  dts: true,
  format: ['esm', 'cjs'],  // 同时支持 ESM 和 CommonJS
  clean: true,
  entry: {
    index: './src/index.ts',
  },
  esbuildOptions: (options) => {
    options.legalComments = 'none'
    return options
  },
})
```

### 输出格式

| 格式 | 说明 |
|-----|------|
| ESM | ECMAScript Module，适合现代构建工具 |
| CJS | CommonJS，适合 Node.js 直接运行 |
| TypeScript 声明 | 自动生成 .d.ts 类型文件 |

## SDK 关键词

资料来源：[packages/js-sdk/package.json:26-39](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/package.json)

```
e2b, ai-agents, agents, ai, code-interpreter, sandbox, code, runtime, vm, nodejs, javascript, typescript
```

## 相关资源

| 资源 | 链接 |
|------|------|
| NPM 包 | https://www.npmjs.com/package/e2b |
| Python SDK | https://pypi.org/project/e2b |
| 官方文档 | https://e2b.dev/docs |
| 支持渠道 | https://e2b.dev/docs/support |

---

<a id='page-4'></a>

## Python SDK

### 相关页面

相关主题：[系统架构](#page-2), [JavaScript/TypeScript SDK](#page-3), [沙箱生命周期管理](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/python-sdk/package.json](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/package.json)
- [packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)
- [packages/python-sdk/e2b/sandbox_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)
- [packages/python-sdk/e2b/envd/process/process_pb2.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/process/process_pb2.py)
- [packages/python-sdk/example.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/example.py)
</details>

# Python SDK

## 概述

E2B Python SDK 是一个开源的基础设施库，用于在云端安全隔离的沙箱环境中运行 AI 生成的代码。该 SDK 提供了创建和控制沙箱的能力，支持同步和异步两种操作模式。开发者可以通过简单的 API 调用，在隔离环境中执行命令、运行代码，并与管理服务进行通信。

## 核心架构

### 模块结构

Python SDK 主要由以下几个核心模块组成：

| 模块 | 文件路径 | 功能说明 |
|------|----------|----------|
| sandbox_async | `e2b/sandbox_async/main.py` | 异步沙箱实现，支持 `Sandbox` 类的异步方法 |
| sandbox_sync | `e2b/sandbox_sync/main.py` | 同步沙箱实现，提供阻塞式的沙箱操作 |
| template | `e2b/template/main.py` | 模板构建器，用于定义沙箱环境配置 |
| template_async | `e2b/template_async/main.py` | 异步模板管理 |
| template_sync | `e2b/template_sync/main.py` | 同步模板管理 |

### 运行时架构图

```mermaid
graph TD
    A[开发者应用] --> B[Python SDK]
    B --> C{同步/异步模式}
    C -->|同步| D[sandbox_sync]
    C -->|异步| E[sandbox_async]
    D --> F[API 客户端]
    E --> F
    F --> G[E2B API 服务]
    G --> H[沙箱实例]
    H --> I[envd 进程]
    I --> J[隔离文件系统]
    I --> K[网络环境]
```

## 沙箱管理

### 创建沙箱

Python SDK 提供了两种沙箱创建方式：同步和异步。

#### 异步创建方式

```python
from e2b import Sandbox
import asyncio

async def main():
    sandbox = await Sandbox.create()
    # 执行操作
    await sandbox.close()

asyncio.run(main())
```

资料来源：[packages/python-sdk/e2b/sandbox_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/main.py)

#### 同步创建方式

```python
from e2b import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.commands.run('echo "Hello from E2B!"')
    print(result.stdout)
```

资料来源：[README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)

### 沙箱响应模型

沙箱创建成功后会返回 `SandboxCreateResponse` 对象，包含以下字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| sandbox_id | str | 沙箱唯一标识符 |
| sandbox_domain | str | 沙箱域名 |
| envd_version | str | envd 版本号 |
| envd_access_token | str | envd 访问令牌 |
| traffic_access_token | str | 流量访问令牌 |

资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)

### 沙箱生命周期管理

```mermaid
stateDiagram-v2
    [*] --> 创建中: Sandbox.create()
    创建中 --> 运行中: 沙箱启动成功
    运行中 --> 停止中: sandbox.close()
    停止中 --> 已停止: 资源清理完成
    创建中 --> 失败: API 错误
    运行中 --> 失败: 连接断开
    失败 --> [*]
    已停止 --> [*]
```

## 模板系统

### 模板构建器

模板系统允许开发者定义沙箱的初始环境配置，包括基础镜像、系统包安装、环境变量设置等。

#### 基础镜像选择

```python
from e2b import Template

template = (
    Template()
    .from_python_image('3')      # Python 3
    # 或
    .from_node_image('lts')      # Node.js LTS
    # 或
    .from_bun_image('latest')    # Bun 最新版
    # 或
    .from_base_image()           # E2B 默认基础镜像
)
```

资料来源：[packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)

#### 系统包安装

```python
template = (
    Template()
    .from_ubuntu_image('24.04')
    .apt_install('vim')
    .apt_install(['git', 'curl', 'wget'])
)
```

#### 环境变量配置

```python
template.set_envs({
    'NODE_ENV': 'production',
    'PORT': '8080'
})
```

### 启动命令配置

```python
from e2b import Template, wait_for_url, wait_for_port, wait_for_file

template = (
    Template()
    .from_node_image()
    .copy('app.js', '/home/user/')
    .set_start_cmd('node app.js', wait_for_port(3000))
)
```

资料来源：[packages/python-sdk/e2b/template/readycmd.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/readycmd.py)

### 模板构建

```python
from e2b import Template

template = (
    Template()
    .from_python_image('3')
    .copy('requirements.txt', '/home/user/')
    .run_cmd('pip install -r /home/user/requirements.txt')
)

# 构建带标签的模板
Template.build(template, 'my-python-env:v1.0')

# 构建带多标签的模板
Template.build(template, 'my-python-env', tags=['v1.1.0', 'stable'])
```

资料来源：[packages/python-sdk/e2b/template_sync/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_sync/main.py)

## 进程与命令执行

### 命令运行

在沙箱中执行命令有两种方式：

#### 使用 commands.run()

```python
result = sandbox.commands.run('echo "Hello from E2B!"')
print(result.stdout)  # Hello from E2B!
```

#### 使用 process 模块

```python
process = sandbox.process.start(
    cmd='python app.py',
    cwd='/home/user'
)
```

资料来源：[packages/python-sdk/example.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/example.py)

### 进程通信协议

进程通信使用 protobuf 定义的协议，核心模型包括：

| 消息类型 | 说明 |
|----------|------|
| Stdin | 标准输入消息 |
| Stdout | 标准输出消息 |
| Stderr | 标准错误输出 |
| Exit | 进程退出信号 |

资料来源：[packages/python-sdk/e2b/envd/process/process_pb2.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/envd/process/process_pb2.py)

## 错误处理

### 异常类型

| 异常类型 | 说明 |
|----------|------|
| SandboxException | 沙箱操作相关错误 |
| TemplateException | 模板构建相关错误 |
| handle_api_exception | API 调用错误处理 |

### 版本兼容性检查

SDK 会在创建沙箱时检查 envd 版本：

```python
if Version(res.parsed.envd_version) < Version("0.1.0"):
    await SandboxApi._cls_kill(res.parsed.sandbox_id)
    raise TemplateException(
        "You need to update the template to use the new SDK. "
        "You can do this by running `e2b template build` in the directory with the template."
    )
```

资料来源：[packages/python-sdk/e2b/sandbox_async/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/sandbox_api.py)

## 安装与配置

### 环境要求

Python SDK 需要 Python 3.8 或更高版本。

### 安装命令

```bash
pip install e2b
```

### 环境变量配置

```bash
E2B_API_KEY=e2b_***
```

资料来源：[packages/python-sdk/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)

## API 客户端配置

### 连接配置

```python
from e2b import ConnectionConfig

config = ConnectionConfig(
    api_key="your-api-key",
    # 其他可选参数
)
```

### API 客户端初始化

SDK 内部通过 `get_api_client()` 函数获取 API 客户端：

```python
api_client = get_api_client(
    config,
    require_api_key=True,
    require_access_token=False,
)
```

资料来源：[packages/python-sdk/e2b/template_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/main.py)

## 快速开始示例

```python
from e2b import Sandbox

# 同步使用
with Sandbox.create() as sandbox:
    result = sandbox.commands.run('echo "Hello from E2B!"')
    print(result.stdout)  # Hello from E2B!

# 异步使用
import asyncio
from e2b import Sandbox

async def main():
    sandbox = await Sandbox.create()
    result = await sandbox.commands.run('echo "Hello from E2B!"')
    print(result.stdout)
    await sandbox.close()

asyncio.run(main())
```

资料来源：[README.md](https://github.com/e2b-dev/E2B/blob/main/README.md)

## 进阶功能

### MCP 服务器集成

模板支持添加 MCP (Model Context Protocol) 服务器：

```python
template = (
    Template()
    .from_base_image()
    .add_mcp_server('exa')
    .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
)
```

资料来源：[packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)

### 缓存控制

跳过缓存，强制重新构建：

```python
template.skip_cache().run_cmd('apt-get update')
```

### Bun 包管理器

```python
template = (
    Template()
    .from_bun_image()
    .bun_install('express')
    .bun_install(['lodash', 'axios'])
    .bun_install('tsx', g=True)  # 全局安装
)
```

## 数据模型

### SandboxDetail

| 属性 | 类型 | 说明 |
|------|------|------|
| sandbox_id | str | 沙箱 ID |
| started_at | datetime | 启动时间 |
| state | str | 当前状态 |
| template_id | str | 模板 ID |
| alias | str | 模板别名 |
| allow_internet_access | bool | 是否允许互联网访问 |
| domain | str | 沙箱域名 |
| metadata | dict | 元数据 |

资料来源：[packages/python-sdk/e2b/api/client/models/sandbox_detail.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/models/sandbox_detail.py)

### 模板标签

```python
@dataclass
class TemplateTag:
    tag: str           # 标签名称
    build_id: str      # 构建 ID
    created_at: datetime  # 创建时间
```

资料来源：[packages/python-sdk/e2b/template_async/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/main.py)

---

<a id='page-5'></a>

## CLI 命令行工具

### 相关页面

相关主题：[沙箱生命周期管理](#page-6), [模板系统与构建](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli/README.md](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)
- [packages/cli/src/commands/template/create.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/create.ts)
- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)
- [packages/cli/src/utils/commands2md.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/utils/commands2md.ts)
</details>

# CLI 命令行工具

## 概述

E2B CLI 是一个命令行工具，用于构建和管理 E2B 云端沙箱以及沙箱模板。它提供了与 E2B 后端服务交互的便捷方式，使开发者能够通过终端快速创建、配置和部署沙箱环境。

CLI 工具是 E2B SDK 生态系统的重要组成部分，支持通过命令行直接操作沙箱和模板资源，而无需编写额外的代码。

资料来源：[packages/cli/README.md:1-3]()

## 安装方式

E2B CLI 支持多种安装方式，开发者可以根据自己的环境选择最适合的方法。

### 通过 Homebrew 安装（macOS）

```bash
brew install e2b
```

### 通过 NPM 安装

```bash
npm install -g @e2b/cli
```

资料来源：[packages/cli/README.md:10-19]()

## 认证配置

使用 CLI 之前需要进行身份认证。E2B 提供了交互式和非交互式两种认证方式。

### 交互式登录

```bash
e2b auth login
```

该命令会打开浏览器窗口引导用户完成认证流程。

### 非交互式认证

在没有浏览器访问权限的环境中，可以设置 `E2B_ACCESS_TOKEN` 环境变量进行认证。访问令牌可在 [e2b.dev/dashboard](https://e2b.dev/dashboard) 的账户设置中的团队选择器下获取。

```bash
E2B_ACCESS_TOKEN=sk_e2b_... e2b template build
```

> [!IMPORTANT]
> 注意 `E2B_ACCESS_TOKEN` 与 `E2B_API_KEY` 的区别。CLI 使用访问令牌，而 SDK 使用 API 密钥。

资料来源：[packages/cli/README.md:21-35]()

## 命令结构

CLI 采用分层命令结构，支持子命令扩展。命令文档生成工具可以将命令定义转换为 Markdown 格式的文档。

### 文档生成机制

CLI 提供了将命令自动转换为文档的功能，支持以下特性：

- 解析命令选项及其默认值
- 生成子命令文档
- 清理终端颜色代码
- 转义 HTML 特殊字符

```typescript
// 处理子命令
command.commands.forEach((subcommand: any) => {
  const [, subMdContent] = commandToMd(subcommand, fullName)
  mdContent += subMdContent + '\n\n'
})
```

资料来源：[packages/cli/src/utils/commands2md.ts:40-47]()

## 模板命令

模板是 E2B 沙箱的基础配置，定义了沙箱环境的初始状态。CLI 提供了完整的模板管理能力。

### 创建模板

创建新模板时，CLI 会生成相应的使用示例并支持多语言 SDK 代码片段输出。

```bash
e2b template create
```

模板创建完成后会输出成功信息，包含模板 ID 和使用示例：

```
✅ Building sandbox template {templateID} finished.
```

示例输出格式支持 Python SDK 和 JS SDK 两种格式，方便不同技术栈的开发者使用。

资料来源：[packages/cli/src/commands/template/create.ts:1-15]()

### 构建模板

构建命令将本地模板配置打包并上传到 E2B 后端进行构建。

```bash
e2b template build
```

#### 构建流程状态

构建过程会返回不同的状态，CLI 根据状态码进行相应处理：

| 状态 | 处理方式 |
|------|----------|
| `building` | 继续轮询直到构建完成 |
| `success` | 输出成功信息和示例代码 |
| `error` | 抛出错误并提示支持渠道 |

```typescript
switch (template.status) {
  case 'building':
    // 继续轮询
    break
  case 'success':
    // 输出成功信息和示例
    console.log(`✅ Building sandbox template... finished.`)
    break
  case 'error':
    throw new Error(`❌ Building sandbox template... failed.`)
}
```

资料来源：[packages/cli/src/commands/template/build.ts:50-80]()

#### Dockerfile 处理

CLI 支持自定义 Dockerfile 构建模板：

```typescript
export function getDockerfile(root: string, file?: string) {
  // 检查用户指定的 Dockerfile 是否存在
  if (file) {
    const dockerfilePath = path.join(root, file)
    const dockerfileContent = loadFile(dockerfilePath)
    
    if (dockerfileContent === undefined) {
      throw new Error(`No ${dockerfileRelativePath} found in the root directory.`)
    }
    
    return { dockerfilePath, dockerfileContent, dockerfileRelativePath }
  }
}
```

资料来源：[packages/cli/src/commands/template/build.ts:95-110]()

### 构建产物格式

成功构建后，CLI 会输出格式化的模板信息：

```typescript
console.log(
  `\n✅ Building sandbox template ${asFormattedSandboxTemplate({
    templateID: templateName,
  })} finished.\n${exampleHeader}\n${exampleUsage}\n`
)
```

输出包含：
- 模板 ID/别名
- 使用示例代码
- Python SDK 示例
- JS SDK 示例

资料来源：[packages/cli/src/commands/template/create.ts:8-13]()

## 环境变量

CLI 使用以下环境变量进行配置：

| 变量名 | 用途 | 来源 |
|--------|------|------|
| `E2B_ACCESS_TOKEN` | CLI 认证令牌 | 用户设置 |
| `E2B_API_KEY` | SDK API 密钥 | SDK 使用 |

资料来源：[packages/cli/README.md:31-34]()

## 错误处理

CLI 实现了统一的错误处理机制：

### 构建错误

```typescript
case 'error':
  throw new Error(
    `\n❌ Building sandbox template ${asFormattedSandboxTemplate({
      aliases,
      ...template,
    })} failed.\nCheck the logs above for more details or contact us ${asPrimary(
      '(https://e2b.dev/docs/support)'
    )} to get help.\n`
  )
```

### 文件缺失错误

```typescript
if (dockerfileContent === undefined) {
  throw new Error(
    `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`
  )
}
```

资料来源：[packages/cli/src/commands/template/build.ts:68-76]()

## 相关资源

- 官方文档：[https://e2b.dev/docs](https://e2b.dev/docs)
- CLI 文档：[https://e2b.dev/docs/cli](https://e2b.dev/docs)
- 支持渠道：[https://e2b.dev/docs/support](https://e2b.dev/docs/support)

资料来源：[packages/cli/README.md:36-37]()

---

<a id='page-6'></a>

## 沙箱生命周期管理

### 相关页面

相关主题：[文件系统操作](#page-7), [Git 操作与网络配置](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/js-sdk/src/sandbox/sandboxApi.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/sandboxApi.ts)
- [packages/python-sdk/e2b/sandbox/sandbox_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/sandbox_api.py)
- [packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py)
- [packages/js-sdk/src/sandbox/commands/commandHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/commands/commandHandle.ts)
- [packages/python-sdk/e2b/sandbox/commands/command_handle.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/commands/command_handle.py)
</details>

# 沙箱生命周期管理

## 概述

沙箱生命周期管理是 E2B 平台提供的核心功能，用于控制沙箱实例在超时、异常或资源管理场景下的行为方式。通过生命周期配置，用户可以定义沙箱在空闲超时后是被终止（kill）还是暂停（pause），以及是否支持自动恢复（auto_resume）功能。 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:15-17]()

## 核心概念

### 生命周期状态

E2B 沙箱支持以下生命周期状态：

| 状态 | 描述 | 可用选项 |
|------|------|----------|
| **Running** | 沙箱正在正常运行 | - |
| **Paused** | 沙箱被暂停，资源冻结 | `on_timeout: "pause"` |
| **Terminated** | 沙箱已被终止销毁 | `on_timeout: "kill"` |

### 生命周期配置参数

```typescript
interface LifecycleConfig {
  on_timeout: "kill" | "pause"    // 超时行为（默认: "kill"）
  auto_resume: boolean            // 是否支持自动恢复（默认: false，仅在 pause 模式下有效）
}
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `on_timeout` | `"kill"` \| `"pause"` | `"kill"` | 空闲超时后的行为 |
| `auto_resume` | `boolean` | `false` | 是否在访问时自动恢复暂停的沙箱 |

## 创建沙箱时的生命周期配置

### TypeScript SDK

```typescript
import Sandbox from 'e2b'

const sandbox = await Sandbox.create('my-template', {
  lifecycle: {
    on_timeout: "pause",
    auto_resume: true
  }
})
```

### Python SDK (异步)

```python
from e2b import Sandbox

sandbox = await Sandbox.create(
    template='my-template',
    lifecycle={"on_timeout": "pause", "auto_resume": True}
)
```

### Python SDK (同步)

```python
from e2b import Sandbox

sandbox = Sandbox.create(
    template='my-template',
    lifecycle={"on_timeout": "pause", "auto_resume": True}
)
```

## 生命周期状态流转

```mermaid
stateDiagram-v2
    [*] --> Creating: 创建沙箱
    Creating --> Running: 创建成功
    Creating --> [*]: 创建失败
    
    Running --> Idle: 空闲超时
    Idle --> Running: 恢复操作
    Idle --> Paused: 到达超时阈值
    
    Paused --> Running: auto_resume=true<br/>访问时自动恢复
    Paused --> Terminated: 手动终止
    
    Running --> Terminated: 手动终止<br/>on_timeout="kill"
    Terminated --> [*]
    
    note right of Paused: 仅当 lifecycle.on_timeout="pause" 时触发
    note right of Idle: 平台内部状态
```

## 自动暂停与恢复机制

### 工作原理

1. **自动暂停**：当沙箱在配置的超时时间内没有活跃操作时，平台自动将沙箱状态从 `Running` 转换为 `Paused`，释放底层计算资源 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:25]()

2. **自动恢复**：当 `auto_resume` 设置为 `true` 时，对暂停状态沙箱的任何访问操作（如运行命令、读取文件）会自动触发沙箱恢复 资料来源：[packages/python-sdk/e2b/sandbox_async/main.py:25]()

```mermaid
sequenceDiagram
    participant Client
    participant SandboxAPI
    participant SandboxInstance
    
    Client->>SandboxAPI: 创建沙箱 (lifecycle: auto_resume=true)
    SandboxAPI->>SandboxInstance: 启动沙箱
    
    Note over SandboxInstance: 空闲超时检测
    SandboxInstance-->>SandboxInstance: 自动暂停
    
    Client->>SandboxAPI: 访问暂停的沙箱
    SandboxAPI->>SandboxInstance: 自动恢复
    SandboxInstance-->>Client: 沙箱就绪
    
    Note over SandboxInstance: 恢复后继续使用
```

### 配置约束

| 场景 | `on_timeout` 要求 | 说明 |
|------|-------------------|------|
| 启用自动恢复 | 必须为 `"pause"` | auto_resume 仅在 pause 模式下生效 |
| 立即终止 | 设置为 `"kill"` | 超时后立即销毁沙箱（默认行为） |

## CLI 沙箱信息查看

通过 E2B CLI 可以查看沙箱的生命周期状态：

```bash
e2b sandbox info <sandboxID>
```

返回的沙箱信息包含以下生命周期相关字段：

| 字段 | 说明 |
|------|------|
| `state` | 当前状态（Running、Paused 等） |
| `lifecycle` | 生命周期配置 |
| `sandboxId` | 沙箱唯一标识 |

## 最佳实践

### 1. 开发调试场景

使用默认的 `kill` 模式，简化资源管理：

```typescript
const sandbox = await Sandbox.create('debug-template', {
  lifecycle: {
    on_timeout: "kill"  // 默认值
  }
})
```

### 2. 长时任务场景

使用暂停模式配合自动恢复，避免重复创建开销：

```typescript
const sandbox = await Sandbox.create('worker-template', {
  lifecycle: {
    on_timeout: "pause",
    auto_resume: true
  },
  timeoutMs: 30 * 60 * 1000  // 30分钟活跃超时
})
```

### 3. 成本敏感场景

使用 `kill` 模式确保资源及时释放：

```python
sandbox = await Sandbox.create(
    template='batch-template',
    lifecycle={"on_timeout": "kill"}
)
```

## 相关源码

- **JavaScript SDK**: `packages/js-sdk/src/sandbox/sandboxApi.ts` - 沙箱 API 调用实现
- **Python SDK**: `packages/python-sdk/e2b/sandbox/sandbox_api.py` - 沙箱 API 封装
- **Python API Client**: `packages/python-sdk/e2b/api/client/api/sandboxes/post_sandboxes.py` - 创建沙箱 API 请求
- **命令处理**: `packages/js-sdk/src/sandbox/commands/commandHandle.ts` - 命令执行与生命周期交互
- **Python 命令处理**: `packages/python-sdk/e2b/sandbox/commands/command_handle.py` - Python 命令执行

---

<a id='page-7'></a>

## 文件系统操作

### 相关页面

相关主题：[沙箱生命周期管理](#page-6), [Git 操作与网络配置](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/js-sdk/src/sandbox/filesystem/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/index.ts)
- [packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)
- [packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)
- [packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)
- [packages/js-sdk/src/volume/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/volume/index.ts)
</details>

# 文件系统操作

E2B 的文件系统操作模块提供了在沙箱（Sandbox）环境中读写文件和目录的完整能力。通过这个模块，用户可以在沙箱内执行文件浏览、读取、写入、监控等操作，是 E2B 沙箱与外部系统交互的核心途径之一。

---

## 模块概述

E2B 的文件系统操作横跨两个主要 SDK：

- **JavaScript/TypeScript SDK (`@e2b`)**：基于异步 API 设计，支持流式读取和多种返回格式
- **Python SDK (`e2b`)**：提供同步和异步两套接口，与 Python 生态深度集成

文件系统操作主要通过 `Sandbox` 实例的 `.filesystem` 属性访问，也可通过 Volume API 操作持久化存储卷中的文件。

---

## 核心功能

### 读取文件

文件系统模块支持以多种格式读取文件内容，适用于不同的使用场景。

#### JavaScript SDK

`Sandbox.filesystem.read()` 方法支持以下返回格式：

| 格式 | 返回类型 | 说明 |
|------|----------|------|
| `text` | `string` | 文件内容作为文本（默认） |
| `bytes` | `Uint8Array` | 文件内容作为字节数组 |
| `blob` | `Blob` | Web API Blob 对象 |
| `stream` | `ReadableStream<Uint8Array>` | 流式读取，适合大文件 |

```typescript
const sandbox = await Sandbox.create('base')

// 读取为文本
const content = await sandbox.filesystem.read('/path/to/file.txt', {
  format: 'text'
})

// 读取为字节数组
const bytes = await sandbox.filesystem.read('/path/to/file.bin', {
  format: 'bytes'
})

// 流式读取大文件
const stream = await sandbox.filesystem.read('/path/to/large.zip', {
  format: 'stream'
})
```

**可选参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `user` | `string` | 以指定用户身份读取（需 envd 0.5.0+） |
| `gzip` | `boolean` | 启用 gzip 解压缩传输 |

资料来源：[packages/js-sdk/src/sandbox/filesystem/index.ts](packages/js-sdk/src/sandbox/filesystem/index.ts)

#### Python SDK

```python
sandbox = await sb.Sandbox.create()

# 读取为文本
content = await sandbox.filesystem.read('/path/to/file.txt')

# 读取为字节
content = await sandbox.filesystem.read('/path/to/file.txt', format='bytes')
```

---

### 写入文件

写入操作支持批量写入多个文件，并自动创建必要的父目录。

#### JavaScript SDK

```typescript
await sandbox.filesystem.write([
  { path: '/app/config.json', data: JSON.stringify(config) },
  { path: '/app/index.js', data: 'console.log("hello")' }
])
```

#### Python SDK

```python
await sandbox.filesystem.write([
  { 'path': '/app/config.json', 'data': json.dumps(config) },
  { path: '/app/index.js', 'data': 'console.log("hello")' }
])
```

**写入选项参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `user` | `string` | 以指定用户身份写入 |
| `request_timeout` | `int` | 请求超时时间（毫秒） |
| `gzip` | `boolean` | 使用 gzip 压缩传输 |
| `use_octet_stream` | `boolean` | 使用 `application/octet-stream` 代替 `multipart/form-data`（需 envd 0.5.7+） |

```python
# 使用 octet-stream 方式上传，适合大文件
await sandbox.filesystem.write(
  [{ 'path': '/data/model.bin', 'data': model_bytes }],
  use_octet_stream=True,
  gzip=True
)
```

资料来源：[packages/python-sdk/e2b/sandbox/filesystem/filesystem.py](packages/python-sdk/e2b/sandbox/filesystem/filesystem.py)

---

### 目录监控

JavaScript SDK 提供了 `WatchHandle` 类用于监控目录变化。

```typescript
const watchHandle = await sandbox.filesystem.watchDir('/app', (event) => {
  console.log(`${event.type}: ${event.name}`)
})

// 停止监控
await watchHandle.stop()
```

**事件类型：**

| 事件类型 | 说明 |
|----------|------|
| `create` | 文件或目录被创建 |
| `write` | 文件被写入 |
| `remove` | 文件或目录被删除 |
| `rename` | 文件或目录被重命名 |

```typescript
// 完整的监控示例
const watchHandle = await sandbox.filesystem.watchDir(
  '/workspace',
  (event) => {
    console.log(`文件 ${event.name} 发生 ${event.type} 事件`)
  },
  (error) => {
    console.error('监控出错:', error)
  }
)
```

`WatchHandle` 类的结构：

```typescript
class WatchHandle {
  // 停止监控
  async stop(): void
  
  // 内部事件迭代器
  private async *iterateEvents(): AsyncIterator<FilesystemEvent>
  
  // 内部事件处理器
  private async handleEvents(): Promise<void>
}
```

资料来源：[packages/js-sdk/src/sandbox/filesystem/watchHandle.ts](packages/js-sdk/src/sandbox/filesystem/watchHandle.ts)

---

### Volume 文件操作

Volume API 提供了对持久化存储卷的文件操作能力，接口设计与普通文件系统类似。

```typescript
const volume = await Volume.get(volumeId)

// 读取 Volume 中的文件
const content = await volume.readFile('/data/file.txt')

// 读取为不同格式
const bytes = await volume.readFile('/data/archive.zip', {
  format: 'bytes'
})
```

**Volume API 读取格式：**

| 格式 | 返回类型 | 说明 |
|------|----------|------|
| `text` | `string` | 文件内容作为文本（默认） |
| `bytes` | `Uint8Array` | 文件内容作为字节数组 |
| `blob` | `Blob` | Web API Blob 对象 |
| `stream` | `ReadableStream<Uint8Array>` | 流式读取 |

```typescript
// 流式读取大文件
const stream = await volume.readFile('/data/dataset.csv', {
  format: 'stream',
  requestTimeoutMs: 120000
})

// 处理流式数据
for await (const chunk of stream) {
  processChunk(chunk)
}
```

**Volume 读取选项：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `requestTimeoutMs` | `number` | 请求超时时间（毫秒） |
| `signal` | `AbortSignal` | 可中止的请求信号 |

资料来源：[packages/js-sdk/src/volume/index.ts](packages/js-sdk/src/volume/index.ts)

---

## 架构设计

### 整体架构

```mermaid
graph TD
    A[用户代码] --> B[Sandbox.filesystem]
    A --> C[Volume.readFile]
    
    B --> D[FilesystemConnection]
    C --> E[VolumeConnection]
    
    D --> F[envd API]
    E --> G[Volume API]
    
    F --> H[沙箱 envd 服务]
    G --> I[E2B Volume 服务]
    
    H --> J[沙箱文件系统]
    I --> K[持久化存储]
```

### 文件读取流程

```mermaid
sequenceDiagram
    participant User as 用户代码
    participant FS as Filesystem
    participant API as envd API
    participant Envd as envd 服务

    User->>FS: read(path, opts)
    FS->>API: GET /files?path=...
    API->>Envd: 请求文件内容
    Envd-->>API: 文件内容
    API-->>FS: 返回响应
    FS-->>User: 根据格式返回结果
```

---

## 版本兼容性

### 用户身份参数

envd 版本对 `user` 参数的支持：

```typescript
// envd < 0.5.0：使用默认用户
// envd >= 0.5.0：可指定 user 参数

let user = opts?.user
if (
  user == undefined &&
  compareVersions(this.envdApi.version, ENVD_DEFAULT_USER) < 0
) {
  user = defaultUsername  // 回退到默认用户
}
```

### Octet Stream 上传

`use_octet_stream` 选项需要特定 envd 版本支持：

```python
supports_octet_stream = self._envd_version >= ENVD_OCTET_STREAM_UPLOAD
use_octet_stream = use_octet_stream and supports_octet_stream
```

如果不支持，会自动回退到 `multipart/form-data` 方式上传。

资料来源：[packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py](packages/python-sdk/e2b/sandbox_sync/filesystem/filesystem.py)

---

## 错误处理

### 常见错误类型

| 错误类型 | 说明 | 处理方式 |
|----------|------|----------|
| `NotFoundError` | 文件或目录不存在 | 检查路径是否正确 |
| `TimeoutError` | 请求超时 | 增加 `requestTimeoutMs` |
| `PermissionError` | 权限不足 | 使用 `user` 参数指定有权限的用户 |
| `NetworkError` | 网络连接问题 | 检查网络和沙箱状态 |

### 404 错误处理

```typescript
const res = await volume.api.GET('/volumecontent/{volumeID}/file', {...})

if (res.response.status === 404) {
  throw new NotFoundError(`Path ${path} not found`)
}
```

---

## 最佳实践

### 1. 选择合适的读取格式

```typescript
// 小文件：使用 text 或 bytes
const config = await sandbox.filesystem.read('/app/config.json', {
  format: 'text'
})

// 大文件：使用 stream 避免内存溢出
const stream = await sandbox.filesystem.read('/data/large-file.bin', {
  format: 'stream'
})

// Web 环境：使用 blob
const blob = await sandbox.filesystem.read('/assets/bundle.js', {
  format: 'blob'
})
```

### 2. 批量写入优化

```python
# 好的做法：批量写入减少请求次数
await sandbox.filesystem.write([
  { 'path': f'/app/file{i}.txt', 'data': content }
  for i in range(100)
])

# 避免：逐个写入（性能差）
for i in range(100):
  await sandbox.filesystem.write([
    { 'path': f'/app/file{i}.txt', 'data': content }
  ])
```

### 3. 启用 gzip 压缩

```typescript
// 对于文本内容，启用 gzip 可显著减少传输时间
const content = await sandbox.filesystem.read('/app/large.json', {
  gzip: true
})
```

### 4. 目录监控资源管理

```typescript
// 务必在不需要时停止监控
const watchHandle = await sandbox.filesystem.watchDir('/workspace', onEvent)

// 使用完毕后清理
try {
  await doWork()
} finally {
  await watchHandle.stop()
}
```

---

## 总结

E2B 的文件系统操作模块提供了完整、一致且易用的文件操作接口。核心特点包括：

- **多格式支持**：text、bytes、blob、stream 满足不同场景需求
- **流式处理**：对大文件提供流式读取，避免内存压力
- **压缩传输**：可选 gzip 压缩优化网络传输
- **目录监控**：支持实时监控文件系统变化事件
- **Volume 集成**：可操作持久化存储卷中的文件
- **跨 SDK 一致**：JavaScript 和 Python SDK 提供相似的接口设计

---

<a id='page-8'></a>

## Git 操作与网络配置

### 相关页面

相关主题：[沙箱生命周期管理](#page-6), [文件系统操作](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/js-sdk/src/sandbox/git/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/git/index.ts)
- [packages/python-sdk/e2b/sandbox_sync/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/git.py)
- [packages/python-sdk/e2b/sandbox_async/git.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_async/git.py)
- [packages/python-sdk/e2b/sandbox/_git/__init__.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/__init__.py)
- [packages/python-sdk/e2b/sandbox/_git/args.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/_git/args.py)
- [packages/js-sdk/src/sandbox/network.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/sandbox/network.ts)
- [packages/python-sdk/e2b/sandbox/network.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox/network.py)
</details>

# Git 操作与网络配置

## 概述

E2B 平台提供了在沙箱环境中执行 Git 操作和配置网络设置的完整功能。Git 操作主要通过模板构建器（Template Builder）在沙箱镜像构建阶段执行，支持克隆仓库、指定分支、浅克隆等常用功能。网络配置则允许用户在创建沙箱时控制网络访问权限和 MCP 网关的网络设置。

## Git 操作

### 模板中的 Git 克隆

在 E2B 中，Git 操作主要通过 `Template` 类的 `git_clone` 方法实现。该方法在镜像构建阶段执行，而非沙箱运行时执行，这意味着所有 Git 相关的准备工作需要在构建模板时完成。

```mermaid
graph TD
    A[创建 Template 实例] --> B[选择基础镜像]
    B --> C[调用 git_clone 方法]
    C --> D[执行 git clone 命令]
    D --> E[构建并部署模板]
    E --> F[沙箱启动时已包含克隆的仓库]
```

### Python SDK 中的 Git 操作

#### git_clone 方法签名

```python
def git_clone(
    self,
    url: str,
    path: Optional[Union[str, Path]] = None,
    branch: Optional[str] = None,
    depth: Optional[int] = None,
    user: Optional[str] = None,
) -> "TemplateBuilder":
```

#### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| url | str | 是 | Git 仓库的完整 URL 地址 |
| path | str 或 Path | 否 | 克隆目标路径 |
| branch | str | 否 | 指定分支名称 |
| depth | int | 否 | 浅克隆的提交历史深度 |
| user | str | 否 | 执行命令的用户身份 |

#### 使用示例

```python
from e2b import Template

# 基本克隆
template = (
    Template()
    .from_python_image("3.11")
    .git_clone("https://github.com/user/repo.git", "/app/repo")
)

# 指定分支的浅克隆
template = (
    Template()
    .from_node_image("24")
    .git_clone(
        "https://github.com/user/repo.git",
        path="/workspace/project",
        branch="main",
        depth=1
    )
)

# 以 root 用户身份克隆
template = (
    Template()
    .from_base_image()
    .git_clone(
        "https://github.com/user/repo.git",
        "/root/repo",
        user="root"
    )
)
```

资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)

### JavaScript SDK 中的 Git 操作

#### gitClone 方法签名

```typescript
gitClone(
  url: string,
  path?: string,
  options?: {
    branch?: string;
    depth?: number;
  },
  user?: string
): TemplateBuilder
```

#### 使用示例

```typescript
import { Template } from 'e2b'

// 基本克隆
const template = Template()
  .fromPythonImage('3')
  .gitClone('https://github.com/user/repo.git', '/app/repo')

// 指定分支和深度的克隆
const template = Template()
  .fromNodeImage('24')
  .gitClone(
    'https://github.com/user/repo.git',
    '/workspace/project',
    { branch: 'main', depth: 1 }
  )
```

### git clone 命令生成

底层实现通过构建 `git clone` 命令行参数来实现功能：

```python
args = ["git", "clone", url]
if branch:
    args.append(f"--branch {branch}")
    args.append("--single-branch")
if depth:
    args.append(f"--depth {depth}")
if path:
    args.append(str(path))
```

资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)

## 网络配置

### 沙箱网络访问控制

E2B 沙箱支持网络访问权限控制，用户可以在创建沙箱时通过 `allow_internet_access` 参数决定是否允许沙箱访问外部网络。

```mermaid
graph LR
    A[沙箱创建请求] --> B{allow_internet_access}
    B -->|True| C[允许访问外部网络]
    B -->|False| D[禁止访问外部网络]
    C --> E[可访问互联网资源]
    D --> F[仅限内部网络通信]
```

### Python SDK 网络配置

#### 同步沙箱创建

```python
with Sandbox.create(
    allow_internet_access=True,  # 允许网络访问
    network=True  # 启用网络功能
) as sandbox:
    result = sandbox.commands.run("curl https://api.example.com")
```

#### 异步沙箱创建

```python
sandbox = await Sandbox.create(
    allow_internet_access=True,
    network=True,
    lifecycle=Lifecycle.KEEP_ALIVE
)
```

#### 网络参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| allow_internet_access | bool | None | 控制沙箱是否可访问外部网络 |
| network | bool | True | 启用沙箱网络功能 |

资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)

### JavaScript SDK 网络配置

```typescript
const sandbox = await Sandbox.create({
  allowInternetAccess: true,
  network: true,
})
```

## MCP 网关网络配置

### MCP 服务器添加

在 Python SDK 中，可以使用 `add_mcp_server` 方法为模板添加 MCP（Model Context Protocol）服务器。该功能要求基础镜像已预装 mcp-gateway。

```python
def add_mcp_server(self, servers: Union[str, List[str]]) -> "TemplateBuilder":
```

#### 使用示例

```python
template = (
    Template()
    .from_base_image()  # 需使用包含 mcp-gateway 的镜像
    .add_mcp_server('exa')
    .add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
)
```

#### 前置条件检查

```python
if self._template._base_template != "mcp-gateway":
    raise BuildException(
        "Devcontainers can only used in the devcontainer base template"
    )
```

资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)

### MCP 网关启动配置

在沙箱运行时，MCP 网关通过特定命令启动，并使用环境变量进行认证配置：

```python
token = str(uuid.uuid4())
sandbox._mcp_token = token

res = sandbox.commands.run(
    f"mcp-gateway --config {shlex.quote(json.dumps(mcp))}",
    user="root",
    envs={"GATEWAY_ACCESS_TOKEN": token},
)
```

| 配置项 | 说明 |
|--------|------|
| mcp-gateway | MCP 网关可执行文件 |
| --config | MCP 服务器配置 JSON |
| GATEWAY_ACCESS_TOKEN | 网关访问认证令牌 |

资料来源：[packages/python-sdk/e2b/sandbox_sync/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/sandbox_sync/main.py)

## 环境变量配置

### Git 操作环境配置

在执行 Git 操作时，可以通过 `set_envs` 方法设置环境变量：

```python
template.set_envs({
    'GIT_TERMINAL_PROMPT': '0',  # 禁用 Git 交互提示
    'GIT_SSL_NO_VERIFY': 'true'   # 禁用 SSL 验证（测试环境）
})
```

#### set_envs 方法实现

```python
instruction: Instruction = {
    "type": InstructionType.ENV,
    "args": [item for key, value in envs.items() for item in [key, value]],
    "force": self._template._force_next_layer,
    "forceUpload": None,
}
self._template._instructions.append(instruction)
```

资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)

## 缓存控制

### 跳过缓存构建

对于需要强制重新构建的指令，可以使用 `skip_cache` 方法：

```python
template.skip_cache().run_cmd('apt-get update')
```

此方法会设置 `_force_next_layer = True`，确保后续指令及其所有层都重新构建，忽略任何缓存层。

资料来源：[packages/python-sdk/e2b/template/main.py:1-100](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)

## 完整使用示例

### Python SDK 综合示例

```python
from e2b import Template, Sandbox

# 创建包含 Git 仓库和 MCP 服务器的模板
template = (
    Template()
    .from_python_image("3.11")
    .git_clone(
        "https://github.com/user/private-repo.git",
        "/app/repo",
        branch="main",
        depth=1
    )
    .set_envs({
        "GIT_TERMINAL_PROMPT": "0",
        "APP_ENV": "production"
    })
    .run_cmd("pip install -r requirements.txt")
)

# 构建模板
build_info = template.build("my-app-template:v1.0")

# 使用模板创建沙箱并启用网络
with Sandbox.create(
    template=build_info.template_id,
    allow_internet_access=True,
    metadata={"user": "developer"}
) as sandbox:
    # 执行应用程序
    result = sandbox.commands.run("python /app/repo/main.py")
    print(result.stdout)
```

### JavaScript SDK 综合示例

```typescript
import { Template, Sandbox } from 'e2b'

// 创建模板
const template = Template()
  .fromNodeImage('24')
  .gitClone(
    'https://github.com/user/repo.git',
    '/workspace/project',
    { branch: 'main', depth: 1 }
  )
  .setEnvs({ NODE_ENV: 'production' })
  .runCmd('npm install')

// 构建并部署
const buildInfo = await Template.build(template, 'my-node-app:v1.0')

// 创建沙箱
const sandbox = await Sandbox.create({
  template: buildInfo.template.id,
  allowInternetAccess: true,
})

const result = await sandbox.commands.run('node /workspace/project/index.js')
console.log(result.stdout)
```

## 架构流程图

```mermaid
graph TD
    subgraph 模板构建阶段
        A[定义 Template] --> B[选择基础镜像]
        B --> C[执行 Git 克隆]
        C --> D[设置环境变量]
        D --> E[安装依赖]
        E --> F[构建 Docker 镜像]
        F --> G[部署到 E2B]
    end
    
    subgraph 沙箱运行阶段
        G --> H[创建沙箱实例]
        H --> I{allow_internet_access}
        I -->|True| J[启用网络访问]
        I -->|False| K[禁用网络访问]
        J --> L[运行用户代码]
        K --> L
        L --> M[执行命令]
        M --> N[访问网络资源]
    end
    
    subgraph MCP 网关配置
        O[配置 MCP 服务器]
        O --> P[启动 mcp-gateway]
        P --> Q[设置访问令牌]
        Q --> R[MCP 服务器就绪]
    end
    
    L -.-> R
```

## 注意事项

1. **Git 凭证管理**：对于私有仓库，需要在模板构建前配置适当的认证方式
2. **网络隔离**：生产环境中应根据需求谨慎设置 `allow_internet_access`
3. **基础镜像要求**：使用 MCP 功能需要选择包含 mcp-gateway 的基础镜像
4. **缓存策略**：开发调试时可使用 `skip_cache()` 强制重新构建

---

<a id='page-9'></a>

## 模板系统与构建

### 相关页面

相关主题：[模板生成器与 Handlebars 模板](#page-10), [CLI 命令行工具](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)
- [packages/js-sdk/src/template/types.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)
- [packages/python-sdk/e2b/template/main.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/main.py)
- [packages/python-sdk/e2b/template/types.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template/types.py)
- [packages/python-sdk/e2b/template_async/build_api.py](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/e2b/template_async/build_api.py)
- [packages/cli/src/commands/template/build.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/build.ts)
</details>

# 模板系统与构建

## 概述

E2B 的模板系统是一套用于构建沙箱运行环境的配置框架，允许开发者通过声明式 API 定义沙箱的基础镜像、系统依赖、应用依赖、环境变量以及启动命令。该系统支持 JavaScript SDK 和 Python SDK，提供了统一且直观的接口来创建可复用的沙箱模板。

模板系统的核心是 `TemplateBuilder` 类，它采用链式调用模式（Builder Pattern），允许开发者通过 fluent API 逐步配置模板的各个组成部分。构建完成的模板可以通过 SDK 的 `build` 方法部署到 E2B 基础设施上，生成可供沙箱使用的镜像。

## 核心概念

### 模板状态机

模板在构建过程中经历以下状态转换：

```mermaid
stateDiagram-v2
    [*] --> TemplateBuilder: 初始化
    TemplateBuilder --> TemplateBuilder: 添加指令
    TemplateBuilder --> TemplateBuilder: 安装依赖
    TemplateBuilder --> TemplateFinal: set_start_cmd()
    TemplateFinal --> [*]: Template.build()
    
    state TemplateBuilder {
        [*] --> withInstructions
        withInstructions --> withInstructions
    }
    
    state TemplateFinal {
        [*] --> readyToBuild
    }
```

- **TemplateBuilder**：模板构建器状态，可以添加各种构建指令
- **TemplateFinal**：模板最终状态，仅在设置启动命令后达到，此时模板才能被构建

资料来源：[packages/js-sdk/src/template/types.ts:50-55]()

### 基础镜像选择

E2B 支持多种基础镜像类型，通过不同的方法选择：

| 方法 | 描述 | 用途 |
|------|------|------|
| `fromBaseImage()` | 使用默认基础镜像 | 创建通用沙箱环境 |
| `fromPythonImage(tag?)` | 使用 Python 镜像 | Python 应用开发 |
| `fromImage(name)` | 使用指定镜像 | 自定义镜像需求 |

资料来源：[packages/js-sdk/src/template/index.ts](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/index.ts)

## JavaScript SDK 模板 API

### 安装包管理器

#### Bun 安装

```typescript
// 安装单个包
template.bunInstall('express')

// 安装多个包
template.bunInstall(['lodash', 'axios'])

// 全局安装
template.bunInstall('typescript', { g: true })

// 安装为开发依赖
template.bunInstall('tsx', { dev: true })

// 从 package.json 安装
template.bunInstall()
```

资料来源：[packages/js-sdk/src/template/types.ts:100-115]()

#### npm 安装

```typescript
// 安装单个包
template.npmInstall('express')

// 安装多个包
template.npmInstall(['lodash', 'axios'])

// 全局安装
template.npmInstall('typescript', { g: true })
```

#### pip 安装

```typescript
// 安装单个包
template.pipInstall('flask')

// 安装多个包
template.pipInstall(['flask', 'requests'])

// 安装 requirements.txt
template.pipInstall()
```

### 系统包安装

#### apt-get 安装

```typescript
// 安装单个系统包
template.aptInstall('vim')

// 安装多个系统包
template.aptInstall(['git', 'curl', 'wget'])

// 不安装推荐包
template.aptInstall(['vim'], { noInstallRecommends: true })

// 修复缺失依赖
template.aptInstall(['vim'], { fixMissing: true })
```

资料来源：[packages/js-sdk/src/template/types.ts:125-140]()

### 环境变量配置

```typescript
// 设置环境变量
template.setEnvs({
  NODE_ENV: 'production',
  PORT: '8080',
  DATABASE_URL: 'postgres://localhost:5432/mydb'
})
```

环境变量通过 `InstructionType.ENV` 指令类型添加到指令列表中。

### MCP 服务器集成

E2B 支持通过 mcp-gateway 集成 MCP (Model Context Protocol) 服务器：

```typescript
// 添加单个 MCP 服务器
template.addMcpServer('exa')

// 添加多个 MCP 服务器
template.addMcpServer(['brave', 'firecrawl', 'duckduckgo'])
```

**注意**：使用 MCP 服务器功能需要基础镜像预装 mcp-gateway（如 `mcp-gateway` 镜像）。

资料来源：[packages/js-sdk/src/template/types.ts:150-160]()

### Devcontainer 支持

```typescript
// 克隆仓库并启动 devcontainer
template
  .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
  .startDevcontainer('/my-devcontainer')

// 预构建并启动 devcontainer
template
  .gitClone('https://myrepo.com/project.git', '/my-devcontainer')
  .betaDevContainerPrebuild('/my-devcontainer')
  .betaSetDevContainerStart('/my-devcontainer')
```

### 设置启动命令

```typescript
// 使用字符串命令
template.setStartCmd(
  'python app.py',
  'curl -f http://localhost:3000/health'
)

// 使用 ReadyCmd 对象
template.setStartCmd(
  'python app.py',
  {
    cmd: 'curl -f http://localhost:3000/health',
    timeout: 30000
  }
)
```

`setStartCmd` 方法将模板状态从 `TemplateBuilder` 转换为 `TemplateFinal`，此时模板才能被构建。

## Python SDK 模板 API

### 初始化与构建

```python
from e2b import Template

template = (
    Template()
    .from_base_image()
    .run_cmd("echo Hello World E2B!")
)

# 构建模板
build_info = Template.build(template, "my-template:v1.0")
```

### 安装依赖

#### Bun 安装

```python
# 安装单个包
template.bun_install('express')

# 安装多个包
template.bun_install(['lodash', 'axios'])

# 全局安装
template.bun_install('typescript', g=True)

# 开发依赖
template.bun_install('tsx', dev=True)
```

资料来源：[packages/python-sdk/e2b/template/main.py:150-175]()

#### apt-get 安装

```python
# 安装系统包
template.apt_install('vim')
template.apt_install(['git', 'curl', 'wget'])

# 不安装推荐包
template.apt_install('vim', no_install_recommends=True)

# 修复缺失依赖
template.apt_install('vim', fix_missing=True)
```

资料来源：[packages/python-sdk/e2b/template/main.py:190-215]()

### MCP 服务器

```python
# 添加 MCP 服务器
template.add_mcp_server('exa')
template.add_mcp_server(['brave', 'firecrawl', 'duckduckgo'])
```

## 构建选项

### JavaScript SDK

```typescript
interface BuildOptions {
  // 镜像标签（可选）
  tags?: string[]
}
```

```typescript
// 简单命名
await Template.build(template, 'my-template:v1.0')

// 多标签构建
await Template.build(template, 'my-template', { 
  tags: ['v1.0', 'stable', 'latest'] 
})
```

### Python SDK

```python
# 异步构建
import asyncio
from e2b import Template, AsyncTemplate

async def build_template():
    template = Template().from_base_image().run_cmd("echo test")
    build_info = await AsyncTemplate.build(template, "my-template:v1.0")
```

## Docker 注册表配置

E2B 支持配置通用 Docker 注册表认证：

```typescript
type GenericDockerRegistry = {
  type: 'registry'
  username: string
  password: string
}
```

此配置允许访问私有 Docker 镜像仓库。

## CLI 命令行工具

E2B CLI 提供了模板构建的命令行接口：

```bash
# 构建模板
e2b template build

# 初始化新模板
e2b template init
```

CLI 使用 `getDockerfile` 函数获取 Dockerfile 内容：

```typescript
export function getDockerfile(root: string, file?: string) {
  // 检查用户指定的 Dockerfile
  if (file) {
    const dockerfilePath = path.join(root, file)
    // ...
  }
  // 否则使用默认 Dockerfile
}
```

资料来源：[packages/cli/src/commands/template/build.ts:55-80]()

## 模板构建流程

```mermaid
graph TD
    A[创建 Template] --> B[选择基础镜像]
    B --> C[安装系统包]
    C --> D[安装应用包]
    D --> E[设置环境变量]
    E --> F[配置 MCP 服务器]
    F --> G[设置启动命令]
    G --> H[调用 build 方法]
    H --> I[上传到 E2B 云端]
    I --> J[构建 Docker 镜像]
    J --> K[模板就绪]
```

## 缓存控制

模板系统支持选择性跳过缓存层：

```typescript
// 跳过后续构建指令的缓存
template.skip_cache().runCmd('apt-get update')
```

这对于需要强制重新执行某些关键指令的场景非常有用。

## 错误处理

### SDK 版本兼容性检查

```typescript
if (compareVersions(res.data!.envdVersion, '0.1.0') < 0) {
  await this.kill(res.data!.sandboxID, opts)
  throw new TemplateError(
    'You need to update the template to use the new SDK.'
  )
}
```

### CLI 构建错误

```typescript
case 'error':
  throw new Error(
    `Building sandbox template failed.\n` +
    `Check the logs above for more details or contact us (https://e2b.dev/docs/support)`
  )
```

## 最佳实践

1. **使用特定版本标签**：为模板指定明确的版本号，避免使用 `latest` 造成不一致
2. **合理拆分依赖**：将系统依赖和应用依赖分开，便于缓存复用
3. **使用 skip_cache 策略**：仅在必要时跳过缓存，减少构建时间
4. **健康检查命令**：为 `set_start_cmd` 配置合理的 ready_cmd，确保沙箱真正就绪
5. **环境变量管理**：使用环境变量而非硬编码配置值，提高模板可复用性

## 相关资源

- [JavaScript SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)
- [Python SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)
- [CLI 工具文档](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)

---

<a id='page-10'></a>

## 模板生成器与 Handlebars 模板

### 相关页面

相关主题：[模板系统与构建](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli/src/commands/template/generators/handlebars.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/generators/handlebars.ts)
- [packages/cli/src/commands/template/generators/template-generator.ts](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/commands/template/generators/template-generator.ts)
- [packages/cli/src/templates/python-template.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/python-template.hbs)
- [packages/cli/src/templates/typescript-template.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/typescript-template.hbs)
- [packages/cli/src/templates/python-build-sync.hbs](https://github.com/e2b-dev/E2B/blob/main/packages/cli/src/templates/python-build-sync.hbs)
</details>

# 模板生成器与 Handlebars 模板

## 概述

E2B 的模板生成器（Template Generator）是 CLI 工具中负责将 `Template` 类实例转换为可部署模板的核心组件。它使用 [Handlebars](https://handlebarsjs.com/) 模板引擎来生成各种格式的输出，包括 Dockerfile、启动脚本和使用示例代码。

模板生成器的主要职责包括：

- 将 `TemplateClass` 实例序列化为中间 JSON 格式
- 通过 Handlebars 模板引擎处理数据并生成最终输出
- 支持多种编程语言的代码示例生成（Python SDK、JS/TS SDK）
- 提供自定义 Handlebars helpers 用于模板逻辑处理

## 架构设计

### 组件关系

```mermaid
graph TD
    A[TemplateClass 实例] --> B[transformTemplateData]
    B --> C[TemplateJSON + HandlebarStep]
    C --> D[Handlebars 模板引擎]
    D --> E[最终输出]
    
    F[Handlebars 类] --> G[eq helper]
    F --> H[escapeQuotes helper]
    F --> I[escapeDoubleQuotes helper]
    
    J[模板类型] --> K[python-template.hbs]
    J --> L[typescript-template.hbs]
    J --> M[python-build-sync.hbs]
```

### 处理流程

```mermaid
sequenceDiagram
    participant CLI as CLI 命令
    participant TG as TemplateGenerator
    participant HB as Handlebars
    participant TPL as .hbs 模板文件
    
    CLI->>TG: 调用生成方法
    TG->>TG: transformTemplateData()
    TG->>TG: 解析 Template.toJSON()
    TG->>HB: 编译模板
    HB->>TPL: 读取 .hbs 文件
    TPL-->>HB: 模板内容
    HB-->>TG: 渲染结果
    TG-->>CLI: 返回生成的代码
```

## Handlebars 核心实现

### Handlebars 类

`Handlebars` 类是 Handlebars 库的封装，提供了模板编译和自定义 helpers 的支持。

**文件位置**: `packages/cli/src/commands/template/generators/handlebars.ts`

#### 类结构

```typescript
class Handlebars {
  private handlebars: typeof HandlebarsLib

  constructor() {
    const handlebars = HandlebarsLib.create()
    handlebars.registerHelper('eq', function (a: any, b: any, options: any) {
      if (a === b) {
        return options.fn(this)
      }
      return ''
    })

    handlebars.registerHelper('escapeQuotes', function (str) {
      return str ? str.replace(/'/g, "\\'") : str
    })

    handlebars.registerHelper('escapeDoubleQuotes', function (str) {
      return str ? str.replace(/"/g, '\\"') : str
    })

    this.handlebars = handlebars
  }

  compile(template: string) {
    return this.handlebars.compile(template)
  }
}
```

资料来源：[packages/cli/src/commands/template/generators/handlebars.ts:1-40]()

### 自定义 Helpers

模板系统提供了三个核心自定义 helpers：

| Helper 名称 | 功能 | 示例 |
|------------|------|------|
| `eq` | 相等比较，类似于 `{{#if (eq a b)}}` | `{{#eq type "RUN"}}...{{/eq}}` |
| `escapeQuotes` | 转义单引号 | `{{escapeQuotes str}}` |
| `escapeDoubleQuotes` | 转义双引号 | `{{escapeDoubleQuotes str}}` |

#### eq Helper

用于在模板中进行条件渲染，类似于 Handlebars 内置的 `if` 但支持相等判断：

```handlebars
{{#eq instruction.type "RUN"}}
RUN {{instruction.args.[0]}}
{{/eq}}
```

#### escapeQuotes Helper

用于转义字符串中的单引号，防止在 JavaScript/TypeScript 代码中产生语法错误：

```handlebars
{{escapeQuotes command}}
```

#### escapeDoubleQuotes Helper

用于转义字符串中的双引号，防止在需要双引号包裹的上下文中产生语法错误：

```handlebars
{{escapeDoubleQuotes filename}}
```

## 数据转换层

### transformTemplateData 函数

该函数负责将 `TemplateClass` 实例转换为 Handlebars 模板可用的数据格式。

**签名**:

```typescript
export async function transformTemplateData(
  template: TemplateClass
): Promise<TemplateJSON & { steps: HandlebarStep[] }>
```

#### HandlebarStep 接口

```typescript
interface HandlebarStep {
  type: string
  args?: string[]
  envVars?: Record<string, string>
  src?: string
  dest?: string
}
```

#### 转换过程

1. 调用 `Template.toJSON(template, false)` 获取 JSON 表示
2. 解析 JSON 为 `TemplateWithStepsJSON` 类型
3. 返回包含 steps 数组的合并结果

资料来源：[packages/cli/src/commands/template/generators/handlebars.ts:59-74]()

## 模板类型

### 模板文件列表

E2B CLI 提供了多种预定义的 Handlebars 模板：

| 模板文件 | 用途 |
|---------|------|
| `python-template.hbs` | Python SDK 使用示例生成 |
| `typescript-template.hbs` | TypeScript SDK 使用示例生成 |
| `python-build-sync.hbs` | Python 构建同步代码生成 |

### python-template.hbs

用于生成 Python SDK 的使用示例代码，包含：

- 模板初始化代码
- 环境变量设置
- 包安装指令
- 启动命令配置

### typescript-template.hbs

用于生成 TypeScript/JavaScript SDK 的使用示例代码，包含：

- TypeScript 类型安全的模板构建
- 异步操作处理
- 错误处理模式

### python-build-sync.hbs

用于生成同步构建相关的 Python 代码，支持：

- 同步模板构建流程
- 构建状态轮询
- 结果处理

## 模板指令类型

在 E2B 模板系统中，每条构建指令都被序列化为特定的数据结构：

### 指令类型枚举

| 类型 | 说明 | 生成的 Dockerfile 指令 |
|------|------|----------------------|
| `RUN` | 执行命令 | `RUN <command>` |
| `COPY` | 复制文件 | `COPY <src> <dest>` |
| `ENV` | 设置环境变量 | `ENV <key>=<value>` |
| `WORKDIR` | 设置工作目录 | `WORKDIR <path>` |
| `USER` | 设置用户 | `USER <username>` |

### 指令数据结构

```typescript
interface Instruction {
  type: InstructionType
  args: string[]
  force?: boolean
  forceUpload?: string | null
}
```

## Dockerfile 生成

`Template` 类提供了 `toDockerfile()` 方法用于生成 Dockerfile 内容：

```typescript
private toDockerfile(): string {
  let dockerfile = `FROM ${this.baseImage}\n`
  for (const instruction of this.instructions) {
    if (instruction.type === InstructionType.RUN) {
      dockerfile += `RUN ${instruction.args[0]}\n`
      continue
    }
    if (instruction.type === InstructionType.COPY) {
      dockerfile += `COPY ${instruction.args[0]} ${instruction.args[1]}\n`
      continue
    }
    if (instruction.type === InstructionType.ENV) {
      const values: string[] = []
      for (let i = 0; i < instruction.args.length; i += 2) {
        values.push(`${instruction.args[i]}=${instruction.args[i + 1]}`)
      }
      dockerfile += `ENV ${values.join(' ')}\n`
      continue
    }
    dockerfile += `${instruction.type} ${instruction.args.join(' ')}\n`
  }
  if (this.startCmd) {
    dockerfile += `ENTRYPOINT ${this.startCmd}\n`
  }
  return dockerfile
}
```

资料来源：[packages/js-sdk/src/template/index.ts]()

## 使用示例

### 基础模板构建

```python
from e2b import Template

template = (
    Template()
    .from_python_image("3.11")
    .pip_install("flask")
    .run_cmd("mkdir -p /app")
    .set_workdir("/app")
    .set_start_cmd("python app.py", "curl http://localhost:5000/health")
)
```

### CLI 命令行使用

```bash
e2b template build --name my-template
```

生成的输出包含：

- ✅ 构建成功的确认消息
- Python SDK 使用示例
- JavaScript/TypeScript SDK 使用示例

资料来源：[packages/cli/src/commands/template/create.ts]()

## 错误处理

模板生成过程中的错误处理机制：

| 错误场景 | 处理方式 |
|---------|---------|
| Dockerfile 不存在 | 抛出文件未找到错误 |
| 构建失败 | 输出错误日志并显示支持链接 |
| 指令解析失败 | 抛出 JSON 解析错误 |

```typescript
if (dockerfileContent === undefined) {
  throw new Error(
    `No ${asLocalRelative(dockerfileRelativePath)} found in the root directory.`
  )
}
```

资料来源：[packages/cli/src/commands/template/build.ts]()

## 最佳实践

### 1. 模板命名规范

- 使用描述性名称：`my-app-template`
- 支持标签语法：`my-app:v1.0`

### 2. 指令顺序

推荐顺序：

1. `from_image()` 或其他基础镜像方法
2. `set_envs()` 环境变量设置
3. `run_cmd()` 系统命令
4. `pip_install()` / `npm_install()` 包安装
5. `copy()` 文件复制
6. `set_workdir()` 工作目录设置
7. `set_start_cmd()` 启动命令

### 3. 缓存优化

使用 `skip_cache()` 方法跳过特定指令的缓存：

```python
template.skip_cache().run_cmd("apt-get update")
```

### 4. 环境变量转义

当在模板中使用特殊字符时，使用相应的转义 helpers：

```handlebars
{{escapeQuotes env_value}}
```

## 相关文档

- [E2B Python SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/python-sdk/README.md)
- [E2B JS SDK 文档](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/README.md)
- [E2B CLI 文档](https://github.com/e2b-dev/E2B/blob/main/packages/cli/README.md)
- [模板 API 类型定义](https://github.com/e2b-dev/E2B/blob/main/packages/js-sdk/src/template/types.ts)

---

---

## Doramagic 踩坑日志

项目：e2b-dev/E2B

摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：配置坑 - 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths。

## 1. 配置坑 · 来源证据：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：RFC: Deterministic OPA/Rego parameter firewalls for outbound sandbox tool execution paths
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2b063fe8cb80490584e7647332a2c4c6 | https://github.com/e2b-dev/E2B/issues/1331 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 配置坑 · 来源证据：process was not killed when auto paused

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：process was not killed when auto paused
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_66994844a2ec44a784ad5b80307d82e9 | https://github.com/e2b-dev/E2B/issues/1031 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：Closed Port Error

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Closed Port Error
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_33133a8885a44301a7f98b23844205cc | https://github.com/e2b-dev/E2B/issues/907 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：Please add skills to use with any ai agent to use e2b in our project

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Please add skills to use with any ai agent to use e2b in our project
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8cebd572dbd2485ab6cdbc13733fdee0 | https://github.com/e2b-dev/E2B/issues/1138 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 来源证据：[Bug]: Incorrect info about webhooks in docs and dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Incorrect info about webhooks in docs and dashboard
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8b25841679fd4eaea5d759a33dfad3b1 | https://github.com/e2b-dev/E2B/issues/1103 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 安装坑 · 来源证据：[Bug]: Sandbox create fails from template, but succeeds without template

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Sandbox create fails from template, but succeeds without template
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3ae274a17e7e420ca9f2cd6e7c6105bd | https://github.com/e2b-dev/E2B/issues/1130 | 来源类型 github_issue 暴露的待验证使用条件。

## 7. 安装坑 · 来源证据：build status polling timed out

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：build status polling timed out
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_88fc7403d6a44edb8b8d4c9deaff0279 | https://github.com/e2b-dev/E2B/issues/1009 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 配置坑 · 来源证据：Paused sandbox is not persisting the file changes / addition after second time resumed and onward

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Paused sandbox is not persisting the file changes / addition after second time resumed and onward
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2fc5340254c94ae2931673fede53e25b | https://github.com/e2b-dev/E2B/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 配置坑 · 社区讨论暴露的待验证问题：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8

- 严重度：medium
- 证据强度：source_linked
- 发现：[Bug]: torch.compile fails for Gemma3n on pytorch 2.8 ### Your current environment <details> <summary>The output of <code>python collect_env.py</code></summary> ```text Your output of `python collect_env.py` here ``` </details> ### 🐛 Describe the bug run ``` vllm serve google/gemma-3n-E2B-it -tp 1 ``` on torch==2.8.0:…
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:github | ssig_3c3209f718cd4d108c88e3bf9d35db24 | https://github.com/vllm-project/vllm/issues/24547 | [Bug]: torch.compile fails for Gemma3n on pytorch 2.8

## 10. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:609539715 | https://github.com/e2b-dev/E2B | README/documentation is current enough for a first validation pass.

## 11. 运行坑 · 来源证据：Support `AbortSignal` in JS SDK methods for request cancellation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Support `AbortSignal` in JS SDK methods for request cancellation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f74f7dd596784e88aff40ef33d5b505e | https://github.com/e2b-dev/E2B/issues/1312 | 来源类型 github_issue 暴露的待验证使用条件。

## 12. 维护坑 · 来源证据：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：When using autoPause in sandbox creation, connect overrides this when resuming the sandbox again
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3002fb1e72dd4aa2ab6baed80425d7b2 | https://github.com/e2b-dev/E2B/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | last_activity_observed missing

## 14. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium

## 15. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:609539715 | https://github.com/e2b-dev/E2B | no_demo; severity=medium

## 16. 安全/权限坑 · 来源证据：(feature request) Run-scoped messaging for multi-sandbox agent workflows

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：(feature request) Run-scoped messaging for multi-sandbox agent workflows
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a6ad64f1b6d54498906e63b880471ac4 | https://github.com/e2b-dev/E2B/issues/1330 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 安全/权限坑 · 来源证据：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AuthenticationError: Unauthorized, please check your credentials. - Invalid API key
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c6225e71e02943b7a367a36c86c96b65 | https://github.com/e2b-dev/E2B/issues/980 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 18. 安全/权限坑 · 来源证据：Docker Build Secrets Support

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docker Build Secrets Support
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6d5e325b8d00480b8ac7acf0b5b01379 | https://github.com/e2b-dev/E2B/issues/815 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 19. 安全/权限坑 · 来源证据：How to use the file that I uploaded when I create template

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to use the file that I uploaded when I create template
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_57466d7f984143c1bb2ae3fb20b9b4f0 | https://github.com/e2b-dev/E2B/issues/1049 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 20. 安全/权限坑 · 来源证据：Template Build Fails with "syncing took too long" Error

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Template Build Fails with "syncing took too long" Error
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4c757d3a005b45989cf3f2e3a6f4433b | https://github.com/e2b-dev/E2B/issues/996 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 21. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | issue_or_pr_quality=unknown

## 22. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:609539715 | https://github.com/e2b-dev/E2B | release_recency=unknown

<!-- canonical_name: e2b-dev/E2B; human_manual_source: deepwiki_human_wiki -->