开源AI代码沙盒E2B Fragments：从部署到深度定制实战指南

1. 项目概述：一个开源的AI代码生成与执行平台

最近在折腾AI驱动的应用开发，发现一个痛点：很多AI生成的代码，你得手动复制粘贴到本地环境去跑，才能验证它到底能不能用、有没有bug。这个过程不仅打断了流畅的开发体验，还经常因为环境差异（比如缺少某个依赖包、版本不兼容）而报错。直到我遇到了E2B Fragments，一个开源的、能让你在浏览器里直接生成、编辑并实时运行代码的“AI代码沙盒”。

简单来说，Fragments 就像是把 Anthropic 的 Claude Artifacts、Vercel 的 v0 或者 GPT Engineer 这类工具的核心能力，打包成了一个你可以自己部署和定制的开源项目。它的核心价值在于，通过集成E2B SDK提供的安全代码执行沙箱，让 AI 生成的代码能够在一个隔离的、可配置的容器环境中立刻运行起来，并将结果（无论是网页预览、控制台输出还是图表）实时流式地展示在 UI 上。这意味着，你可以用自然语言描述一个需求，看着 AI 一步步写出代码，并立刻看到运行效果，形成一个“描述-生成-验证”的闭环。

这个项目非常适合几类人：一是前端或全栈开发者，想快速构建原型或内部工具；二是对 AI 应用开发感兴趣的工程师，想学习如何将大语言模型（LLM）与代码执行环境深度集成；三是任何希望提升开发效率，探索“用 AI 写代码”新工作流的人。它基于现代 Web 技术栈（Next.js 14, shadcn/ui, TailwindCSS），支持多种主流 LLM 提供商和开发框架，并且高度可定制，你可以把它当作一个强大的基础，在上面构建属于自己的 AI 编程助手。

2. 核心架构与工作原理拆解

要理解 Fragments 为什么好用，得先拆开看看它的“引擎盖”下面是什么。整个系统的运转可以概括为“前端交互 -> AI 生成 -> 沙箱执行 -> 流式回显”这样一个管道。

2.1 技术栈选型背后的考量

项目选择了 Next.js 14（App Router）作为全栈框架，这是一个非常务实的选择。App Router 的 Server Actions 特性允许直接在 React 组件中编写服务器端逻辑，这对于处理需要调用外部 API（如 OpenAI、E2B）的 AI 交互流程来说，代码组织更直观，减少了传统 API 路由的样板代码。shadcn/ui 和 TailwindCSS 的组合，则保证了 UI 组件既美观又可高度定制，避免了被某个 UI 库“绑架”的风险。Vercel AI SDK 的集成，为处理不同 LLM 提供商的流式响应提供了统一、优雅的抽象，省去了自己处理各种 API 差异的麻烦。

最核心的部件是E2B SDK。你可以把它理解为一个“云函数”或“容器即服务”的超级简化版。它负责在云端按需启动一个轻量级、安全的 Docker 容器（即沙箱），这个容器预装了指定的语言运行时和依赖库（比如 Python 3.11 和 numpy、pandas）。当 AI 生成了一段代码后，Fragments 的后端会通过 E2B SDK 将代码发送到这个沙箱中执行，并将执行过程（标准输出、错误信息）和结果（如启动的 Web 服务端口）实时地流式传输回来。

注意：E2B 沙箱是短暂存在的，通常在一次会话或一个任务完成后就会被销毁。这确保了安全性和隔离性，你完全不用担心用户执行的恶意代码会影响你的主机服务器。这也是为什么 Fragments 敢宣称能“安装和使用任何来自 npm、pip 的包”——因为它们都被限制在沙箱内部。

2.2 支持的“人格”与模型：灵活性的体现

Fragments 内置了对多种技术栈（它称之为“Personas”，即人格）和 LLM 模型的支持，这直接决定了它的应用广度。

• 技术栈（Personas）：目前官方支持 Python 解释器、Next.js、Vue.js、Streamlit 和 Gradio。这覆盖了从纯脚本、前端应用到数据可视化仪表盘的常见场景。例如，选择“Streamlit developer”人格，AI 就会倾向于生成一个基于 Streamlit 的交互式数据应用，并且沙箱环境会预装好 Streamlit 及其常用数据科学库，生成后能一键运行。
• LLM 模型：支持几乎所有主流提供商，包括 OpenAI (GPT-4o)、Anthropic (Claude 3.5 Sonnet)、Google AI (Gemini)、Mistral、Groq、Fireworks 等。这意味着你可以根据对成本、速度、代码能力的偏好自由切换“大脑”。项目还集成了Morph服务，这是一个专门针对代码编辑进行优化的模型，能更准确、更高效地执行“根据反馈修改代码”这类任务，提升了交互迭代的效率。

这种设计哲学很清晰：解耦与可插拔。前端界面、AI 模型、执行环境被设计成独立的模块，通过清晰的接口（配置文件、环境变量）连接。这为深度定制打开了大门。

3. 从零开始部署与配置实战

纸上谈兵终觉浅，我们直接上手，把一个完整的 Fragments 实例跑起来。我会基于官方指南，补充一些实际操作中容易踩坑的细节。

3.1 环境准备与依赖安装

首先确保你的本地开发环境就绪：

1. Git：用于克隆代码库。
2. Node.js 18+ 及 npm：这是运行 Next.js 应用的基础。我推荐使用nvm(Node Version Manager) 来管理 Node.js 版本，可以避免全局版本冲突。安装后，在项目目录下可以运行nvm use 18（如果项目有.nvmrc文件会更方便）。
3. 获取 API 密钥：
   • E2B API Key：去 e2b.dev 注册账号，在控制台就能找到。这是整个项目的“发动机燃油”，没有它代码沙箱无法启动。
   • LLM Provider API Key：根据你想使用的模型，去对应平台申请。例如，如果你主要用 OpenAI，就去 OpenAI 平台申请。建议初期先准备一个即可（比如 OpenAI 的），减少配置复杂度。

打开终端，开始操作：

# 1. 克隆仓库 git clone https://github.com/e2b-dev/fragments.git cd fragments # 2. 安装依赖 npm install

这里有个小技巧：如果npm install速度慢或遇到网络问题，可以尝试使用npm install --registry=https://registry.npmmirror.com切换至国内镜像源，或者使用pnpm、yarn替代（需确保package-lock.json或yarn.lock文件被正确识别）。

3.2 环境变量配置详解

这是配置环节最关键的一步，很多运行错误都源于此。在项目根目录创建.env.local文件（Next.js 会自动加载此文件的环境变量）。

# --- 必需配置 --- # 你的 E2B API 密钥 E2B_API_KEY="e2b-xxxxxx-your-actual-key-xxxxxx" # 至少配置一个 LLM 提供商的密钥，这里以 OpenAI 为例 OPENAI_API_KEY="sk-xxxxxx" # --- 可选配置（按需启用）--- # 如果你想用 Claude，取消注释并填写 # ANTHROPIC_API_KEY="your-key" # Morph 服务密钥，用于增强代码编辑能力，建议开启 MORPH_API_KEY="morph-xxxxxx" # 如果你部署到了线上（如 Vercel），需要设置站点域名，用于生成可分享的链接 # NEXT_PUBLIC_SITE_URL="https://your-deployment-url.vercel.app" # 速率限制，保护你的 API 不被滥用 # RATE_LIMIT_MAX_REQUESTS="100" # RATE_LIMIT_WINDOW="3600" # 单位：秒，表示1小时内最多100次请求 # --- 高级功能（初期可忽略）--- # 如果需要短链接、更复杂的限流，或用户认证、数据分析，才需要配置下面这些 # KV_REST_API_URL="" # KV_REST_API_TOKEN="" # SUPABASE_URL="" # SUPABASE_ANON_KEY="" # NEXT_PUBLIC_POSTHOG_KEY="" # NEXT_PUBLIC_POSTHOG_HOST=""

实操心得：.env.local文件务必添加到.gitignore中，切勿提交到代码仓库，以免密钥泄露。对于团队项目，可以创建一个.env.example文件，列出所有需要的变量名（不含真实值），供团队成员参考。

3.3 启动开发服务器与构建

配置完成后，启动开发服务器就非常简单了：

npm run dev

正常情况下，终端会输出> Ready on http://localhost:3000。打开浏览器访问这个地址，你应该能看到 Fragments 的界面。

如果你想构建用于生产环境的应用：

npm run build npm start

npm run build会执行 Next.js 的优化构建过程。构建完成后，使用npm start启动生产服务器。在部署到 Vercel、Netlify 等平台时，平台的构建命令通常会自动处理这一步。

常见问题排查：

• 启动失败，提示端口占用：默认端口是 3000。你可以通过npm run dev -- -p 3001指定另一个端口。
• 页面打开空白或报错：首先检查终端是否有编译错误。最常见的原因是环境变量未正确加载。确保.env.local文件在项目根目录，且变量名拼写正确。可以在代码中临时console.log(process.env.E2B_API_KEY)来验证是否读取成功（记得重启 dev server）。
• 沙箱执行失败：检查E2B_API_KEY是否正确且未过期。去 E2B 控制台查看额度是否用完。网络问题也可能导致连接 E2B 服务超时。

4. 深度定制：打造专属的AI编程助手

Fragments 真正的威力在于其可定制性。官方文档给出了方向，但实际操作中有些细节值得深究。

4.1 添加自定义技术栈（Persona）

假设我们团队内部常用FastAPI来快速搭建后端 API，我们希望添加一个 “FastAPI Developer” 的人格。

步骤详解：

1. 安装并登录 E2B CLI：

   npm install -g @e2b/cli e2b login

   按照提示完成浏览器认证。CLI 是你与 E2B 模板系统交互的工具。

2. 创建模板目录： 在项目的sandbox-templates/目录下，新建一个文件夹，例如fastapi-template。

   cd fragments mkdir -p sandbox-templates/fastapi-template cd sandbox-templates/fastapi-template

3. 初始化模板：

   e2b template init

   这个命令会交互式地引导你，并最终生成两个核心文件：e2b.Dockerfile和e2b.toml。

4. 编写 Dockerfile： 打开生成的e2b.Dockerfile，我们需要定义一个包含 Python 和 FastAPI 的环境。

   # 使用官方的 Python 轻量级镜像 FROM python:3.11-slim # 安装系统依赖，某些Python包可能需要（如用于编译） RUN apt-get update && apt-get install -y \ gcc \ && rm -rf /var/lib/apt/lists/* # 安装 Python 依赖 # 使用 requirements.txt 是更规范的做法，这里为演示直接安装 RUN pip install --no-cache-dir fastapi uvicorn[standard] pydantic # 设置工作目录并复制代码 WORKDIR /home/user/app COPY . /home/user/app # 暴露 FastAPI 默认端口 EXPOSE 8000

   注意：镜像宜小不宜大。slim版本比完整版体积小很多，能加快沙箱启动速度。只安装必要的依赖。

5. 配置启动命令： 编辑e2b.toml文件，指定沙箱启动后运行的命令。

   start_cmd = "cd /home/user/app && uvicorn main:app --host 0.0.0.0 --port 8000 --reload"

   这里假设 AI 生成的入口文件是main.py，其中包含一个名为app的 FastAPI 实例。--reload参数在开发时有用，但生产沙箱可能不需要，可根据情况调整。

6. 构建并部署模板：

   e2b template build --name fastapi-developer

   这个过程会将你的 Dockerfile 构建成镜像，并上传到 E2B 的托管服务。完成后，命令行会输出一个模板 ID（如tmpl_xxxx），记下它。

7. 在 Fragments 前端注册新人格： 打开项目中的lib/templates.json文件。在 JSON 对象里添加一个新条目：

   "fastapi-developer": { "name": "FastAPI Developer", "lib": ["fastapi", "uvicorn", "pydantic"], "file": "main.py", "instructions": "You are an expert FastAPI developer. Create a RESTful API server. The main application instance must be named 'app' and be defined in a file called main.py. Always include comprehensive error handling and input validation using Pydantic models.", "port": 8000 }

   • "fastapi-developer"：这个键（Key）必须和上一步e2b template build时使用的--name一致，或者使用命令行返回的模板 ID。
   • instructions：这是给 AI 模型的系统提示词的一部分，非常重要！清晰的指令能引导 AI 生成更符合预期的代码结构（比如强制要求main.py和app变量名）。
   • port: 必须和e2b.toml里EXPOSE的端口一致，这样前端才知道如何预览你的应用。

8. （可选）添加人格图标： 在public/thirdparty/templates/目录下，添加一个fastapi-developer.svg（或.png,.jpg）图标文件，它会在人格选择下拉框中显示。

完成以上步骤后，重启你的开发服务器 (npm run dev)，刷新页面，你应该能在人格选择列表里看到新添加的 “FastAPI Developer” 了。选择它，然后让 AI 生成一个 FastAPI 应用试试看。

4.2 添加自定义LLM模型与提供商

也许你公司内部部署了一个开源模型（如通过 Ollama），或者使用某个小众但高效的 API，Fragments 也能接入。

添加自定义模型：模型列表定义在lib/models.ts中。找到export const models这个数组，添加一个新对象：

{ id: 'qwen2.5:32b', // 模型在提供商处的唯一标识 name: 'Qwen2.5 32B', // 在UI中显示的名称 provider: 'Ollama', // 提供商名称 providerId: 'ollama' // 提供商ID，需与下一步的配置对应 }

添加自定义提供商：在同一个文件的providerConfigs对象中，你需要为新的providerId（比如ollama）添加一个配置函数。这个函数返回一个符合 Vercel AI SDK 要求的语言模型调用实例。

// 在 providerConfigs 对象内部添加 ollama: (modelName: string, apiKey?: string, baseURL?: string) => { // 通常Ollama本地部署不需要API Key，baseURL指向本地服务 const finalBaseURL = baseURL || 'http://localhost:11434/v1'; // Ollama 的 OpenAI 兼容端点 return createOpenAI({ apiKey: 'not-needed', // Ollama 通常不需要密钥，但SDK要求有值 baseURL: finalBaseURL, })(modelName); },

同时，你还需要在getDefaultMode函数中，为这个提供商指定默认的“结构化输出模式”。对于代码生成，'json'模式通常更好，因为它强制模型返回格式化的 JSON，便于解析。

if (providerId === 'ollama') { return 'json'; }

最后，别忘了在前端环境变量配置中，允许用户输入这个新提供商的 Base URL。通常，你需要修改相关的前端组件，让用户界面支持选择和配置你的自定义提供商。

注意事项：添加自定义提供商涉及修改 TypeScript 源码，需要一定的前端开发知识。务必注意函数签名和返回类型要与providerConfigs中其他条目保持一致。修改后，可能需要重新运行npm run dev来编译类型。

5. 高级使用技巧与性能优化

当基本功能跑通后，如何用得更好、更稳、更省，就是接下来要关注的问题。

5.1 利用Morph提升代码编辑效率

Fragments 集成了 Morph，这不是一个必选项，但我强烈建议开启。它的作用是在你提出“修改代码”的指令时，替代通用的 LLM（如 GPT-4）来执行。Morph 是专门针对“代码补丁生成”任务训练的模型，实测下来有两个明显优势：

1. 更高准确性：对于“在第X行添加一个函数”、“将变量名从foo改为bar”这类精确编辑指令，它比通用模型犯错的概率更低。
2. 更低成本与延迟：它通常比调用一次完整的 GPT-4 生成全部代码要便宜和快速。

启用方法很简单，在.env.local中配置MORPH_API_KEY即可。Fragments 的后端逻辑会自动判断当前操作是“生成新代码”还是“编辑现有代码”，并智能地路由到合适的模型。

5.2 管理沙箱生命周期与成本

E2B 的沙箱按执行时间计费。虽然个人使用成本很低，但在公开部署或团队使用时，需要做好管理。

• 设置超时：在代码中，可以配置沙箱的最大运行时间。避免用户启动一个长期运行的后台进程导致沙箱一直不释放。
• 资源限制：E2B 允许为沙箱配置 CPU 和内存上限。对于简单的脚本任务，使用默认的较低配置即可；对于需要运行数据分析或训练的任务，可以在创建沙箱时请求更高的资源。
• 会话管理：Fragments 的默认逻辑可能是一个聊天会话对应一个沙箱。理解这一点有助于设计应用逻辑，比如可以考虑实现“重置沙箱”的功能，让用户能在同一个会话中重新开始，而不是必须开启新会话。

5.3 前端UI与体验优化

Fragments 的 UI 是基于 shadcn/ui 构建的，这意味着你可以像修改任何 React 组件一样去定制它。

• 修改主题：tailwind.config.js和app/globals.css控制了主题样式。你可以轻松切换为深色/浅色主题，或自定义品牌色。
• 调整布局：如果你觉得代码编辑器和预览窗口的布局不合适，可以直接修改app/page.tsx或相关布局组件。
• 添加快捷键：为常用操作（如运行代码、格式化）添加快捷键可以极大提升效率。这需要修改前端组件并集成类似@dnd-kit或自定义键盘事件监听。

5.4 安全加固部署

如果你打算将 Fragments 部署到公网供他人使用，安全是首要考虑。

1. 身份认证：项目支持 Supabase 集成。在.env.local中配置 Supabase 后，前端会启用登录功能。确保只有授权用户才能使用，避免 API 密钥被滥用。
2. 速率限制：务必设置RATE_LIMIT_MAX_REQUESTS和RATE_LIMIT_WINDOW。这是防止恶意用户刷爆你的 E2B 和 LLM API 额度的第一道防线。
3. 输入过滤与输出净化：虽然 E2B 沙箱提供了隔离，但仍需警惕提示词注入攻击。不要将用户输入未经处理就直接拼接成给 AI 的系统提示词。对于 AI 生成的代码在预览 iframe 中执行的情况（如网页应用），要确保沙箱返回的 HTML/JS 内容被安全地渲染，避免 XSS 攻击。
4. 密钥管理：永远不要将 API 密钥硬编码在客户端代码中。Fragments 的架构是合理的：LLM 和 E2B 的调用都在 Server Action 中完成，密钥存储在服务器端环境变量里。部署时，使用 Vercel、Railway 等平台的环境变量管理功能。

6. 常见问题与故障排除实录

在实际部署和使用中，我遇到并总结了一些典型问题及其解决方法。

问题现象	可能原因	排查步骤与解决方案
启动npm run dev时报错，提示模块找不到	1.node_modules不完整或损坏。 2. Node.js 版本不兼容。	1. 删除node_modules文件夹和package-lock.json，重新运行npm install。 2. 检查package.json中的engines字段，确保本地 Node.js 版本符合要求。使用nvm use切换版本。
页面能打开，但选择模型后发送消息无反应，或提示“Failed to create sandbox”	1.E2B_API_KEY未设置或错误。 2. E2B 账户额度已用尽。 3. 网络问题，无法连接到 E2B 服务。	1. 检查.env.local文件，确认E2B_API_KEY已正确填写且无多余空格。 2. 登录 E2B 控制台，查看额度使用情况。 3. 在服务器终端尝试curlE2B API 端点，或检查防火墙/代理设置。
AI 能回复，但生成的代码点击“运行”后一直转圈或失败	1. 沙箱模板配置错误（如e2b.Dockerfile有误）。 2. 生成代码的入口文件与模板配置不符。 3. 沙箱内依赖安装失败。	1. 检查对应人格在lib/templates.json中的file字段，是否与 AI 生成的文件名一致。 2. 查看浏览器开发者工具（F12）的“网络”选项卡，找到执行请求的响应，里面通常会有详细的错误信息。 3. 检查e2b.Dockerfile中的依赖安装命令是否正确，特别是网络连通性（有些源需要换）。
流式输出中断，或页面卡死	1. Server Action 或 API 路由超时。 2. 网络连接不稳定。 3. 生成的代码陷入死循环，沙箱无响应。	1. 如果是本地开发，检查终端是否有报错。如果是部署环境，查看平台（如 Vercel）的函数执行日志和超时设置（Vercel Hobby 计划有10秒超时限制）。 2. 对于复杂任务，提示 AI 分步生成，避免单次生成过长的代码。 3. 考虑在 E2B SDK 调用处设置合理的超时时间。
自定义人格添加后，在列表中不显示	1.lib/templates.json文件格式错误（如缺少逗号）。 2. 模板 ID 或名称与 E2B CLI 部署的不匹配。 3. 前端缓存。	1. 使用 JSON 验证工具检查templates.json格式。 2. 确认e2b template build输出的模板 ID，并在templates.json中使用完全相同的 ID 作为键（Key）。 3. 重启开发服务器并硬刷新浏览器（Ctrl+Shift+R）。
部署到 Vercel 后，环境变量不生效	1. 环境变量未在 Vercel 项目设置中正确配置。 2. 变量名拼写错误。 3. 构建后未重新部署。	1. 登录 Vercel 控制台，进入项目设置，在Environment Variables部分逐一添加.env.local中的所有变量。 2. 仔细核对拼写，区分大小写。 3. 在 Vercel 上每次更新环境变量，通常需要触发一次新的部署。

一个我踩过的坑：有一次我自定义了一个需要安装torch（PyTorch）的 Python 模板。直接pip install torch在构建镜像时非常慢且容易失败。解决方案是在e2b.Dockerfile中使用预编译的 wheel 包并指定镜像源：

RUN pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

这大大加快了构建速度。所以，定义模板时，充分考虑依赖包的安装效率很重要。

最后，Fragments 是一个活跃的开源项目，遇到问题时，除了以上排查方法，最好的途径是去其 GitHub Issues 页面搜索或提问。社区和开发者通常很乐意帮忙。