bolt.diy 保姆级部署教程：浏览器里的 AI 全栈编程工作台

bolt.diy 是 StackBlitz Labs 开源的 AI 全栈开发工作台，官方定位「the open-source AI developer workspace that lets you select your preferred LLM for every prompt」。你用自然语言描述需求，它在浏览器里直接生成完整 Web 应用，并自带代码编辑器、终端、预览窗口。前身是 StackBlitz 出的 bolt.new 开源版，支持 22+ 模型供应商。本文基于官方 README 的 Quick Start 与 Docker 章节。

一、项目介绍与适用场景

bolt.diy 是一个跑在浏览器里的 AI 编程 Agent：它用 WebContainers 技术在浏览器里模拟 Node.js 环境，AI 生成的代码直接在浏览器中安装依赖、运行开发服务器、预览效果。你不需要在本地准备任何项目脚手架。

典型场景：

• 快速原型验证：一句话生成一个落地页、待办应用、小游戏。
• 学习全栈开发：看 AI 怎么写 React + API 代码。
• 对接自有模型：接 Ollama / LM Studio 本地模型，离线使用。
• 团队共享内部 AI 工作台：Docker 部署在内网，多人共用。

二、核心功能逐条拆解

1. 浏览器内全栈开发：WebContainers 直接在浏览器跑 Node.js。
2. 22+ 模型供应商：OpenAI、Anthropic、Gemini、DeepSeek、Groq、xAI、Ollama、LM Studio 等。
3. 交互工作台：集成代码编辑器、终端、可视化 diff、实时预览。
4. 项目工作流：Git clone/push、快照恢复、文件冲突锁定、ZIP 导出。
5. 一键部署：生成的应用可直接部署到 Netlify、Vercel、GitHub Pages。
6. Electron 桌面版：官方提供 Windows/macOS/Linux 安装包。
7. MCP 工具：支持 Model Context Protocol 接入外部工具。

三、全套官方链接

四、硬件与环境前置要求

官方 README Quick Start 明确：

• Node.js >= 22.12.0
• pnpm >= 9.15.9（npm install -g pnpm）
• 内存：2GB 起步；磁盘：2GB。
• 模型 API Key 或本地 Ollama。

五、多平台部署步骤

5.1 源码部署（官方推荐开发方式）

官方 README 原文三步：

git clone https://github.com/stackblitz-labs/bolt.diy.git
cd bolt.diy
pnpm install

逐段解释：克隆仓库；pnpm install 安装所有依赖（官方要求 pnpm >= 9.15.9）。

启动开发服务器：

pnpm run dev

官方说明：浏览器打开 http://localhost:5173 。

5.2 Docker 部署

官方 README 原文两步：

cp .env.example .env.local

开发模式：

docker compose --profile development up

生产构建：

pnpm run dockerbuild:prod
docker compose --profile production up

逐段解释：cp .env.example .env.local 准备环境变量；--profile development 启用热重载；生产模式先本地 build 镜像再起容器。

5.3 Electron 桌面版

官方提供预编译安装包：https://github.com/stackblitz-labs/bolt.diy/releases/latest ，直接下载 Windows/macOS/Linux 安装包。源码构建：

pnpm electron:build:dist

六、配置文件全部参数解释

官方 README 给出的环境变量（写入 .env.local）：

官方同时说明：也可以直接在 Web UI 的 Settings → Providers 里填 Key，Key 存在浏览器 Cookie 中。

七、启动、后台常驻与开机自启

7.1 启动

源码：pnpm run dev；Docker：docker compose --profile production up。

7.2 后台常驻

Docker 方式天然后台运行；源码方式用 nohup pnpm run dev & 或 pm2。

7.3 开机自启

Docker 加 restart: always；桌面版安装包自带。

7.4 修改端口

默认 Vite 5173；改 vite.config.ts 或 --port 参数。

八、功能实操教程

第 1 步：pnpm run dev 后访问 http://localhost:5173。

第 2 步：左下角设置图标 → Providers，填入你的 API Key（如 DeepSeek 或 OpenAI）。

第 3 步：在对话框输入「帮我做一个倒计时番茄钟网页」，观察 AI 生成代码。

第 4 步：右侧 Workbench 自动打开，可看到文件树、终端、预览窗。

第 5 步：预览窗里直接操作生成的应用；不满意继续对话让 AI 修改。

第 6 步：点「Export」导出 ZIP，或一键部署到 Netlify/Vercel。

第 7 步：接 Ollama：设置里 Ollama 地址填 http://host.docker.internal:11434（Docker 部署时）或 http://127.0.0.1:11434（本地源码）。

九、全套报错故障排查

1. 报错原文：pnpm: command not found 原因分析：未装 pnpm。 解决方案：npm install -g pnpm。

2. 报错原文：Node 版本过低 原因分析：官方要求 Node >= 22.12.0。 解决方案：用 nvm 安装 nvm install 22。

3. 报错原文：WebContainers 在浏览器里报无法加载 原因分析：浏览器不支持（需 Chrome/Edge 桌面版）。 解决方案：换 Chrome 最新版。

4. 报错原文：模型列表为空 原因分析：未配置 Provider。 解决方案：Settings → Providers 填 Key。

5. 报错原文：Docker 启动后 5173 打不开 原因分析：端口未映射或容器未 ready。 解决方案：docker compose ps 看状态。

十、升级、回滚与卸载

升级：git pull && pnpm install && pnpm run dev。

卸载：rm -rf bolt.diy；Docker docker compose down。

十一、商用许可与合规风险提示

bolt.diy 项目代码为 MIT，可自由商用。但官方 README 特别提示：它依赖的 WebContainers API 有单独的商用条款（webcontainers.io/enterprise），企业级大规模使用需联系 StackBlitz 授权。这是最容易被忽略的合规点。

参考链接：

• bolt.diy GitHub README：https://github.com/stackblitz-labs/bolt.diy
• 官方文档：https://stackblitz-labs.github.io/bolt.diy/
• Releases：https://github.com/stackblitz-labs/bolt.diy/releases/latest