☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
bolt.diy 贡献指南：从本地开发环境搭建到 Docker 部署的完整参与手册
2026/9/20 6:24:25 网站建设 项目流程
  • AI 应用
  • 代码智能体
  • AI Agent
  • 大模型
  • 开发工具

【免费下载链接】bolt.diy

Prompt, run, edit, and deploy full-stack web applications using any LLM you want!

项目地址：https://gitcode.com/gh_mirrors/bo/bolt.diy
点击查看免费下载

本指南以 bolt.diy 仓库根目录的 CONTRIBUTING.md 为骨架，面向希望为 bolt.diy 贡献代码、报告问题或搭建本地/容器化开发环境的开发者。通过阅读本文，你将掌握完整的贡献流程（Issue 报告 → Fork → 分支开发 → 提交 PR）、基于 pnpm + Remix + Vite + Cloudflare Workers 的本地开发环境配置（含全部环境变量语义）、单元测试与代码规范校验方法，以及覆盖开发与生产两套场景的 Docker 多阶段构建与 Compose 部署方案。全文所有命令、配置项与脚本均以当前仓库中的 package.json、.env.example、docker-compose.yaml、Dockerfile 等真实文件为准，可复制执行。

一、项目定位与贡献总览

bolt.diy 是一个"用任意 LLM 驱动全栈 Web 应用"的开源 AI Agent（见 package.json 的项目描述），它基于 Remix + Vite 构建，运行在 Cloudflare Workers / Pages 生态上，并同时支持 Docker 容器化与 Electron 桌面化运行。

贡献者需要先明确参与方式，再按规范提交代码。文档将其分为三类：

  1. 报告 Bug 或提出功能需求：先在 Issue 追踪器中检索避免重复提交，尽量使用项目提供的 Issue 模板（如果可用），并在描述中提供详细、可复现的步骤。
  2. 代码贡献：标准的 Fork → 新建功能/修复分支 → 编写并测试代码 → 提交 Pull Request（PR）流程。
  3. 成为核心贡献者：有意长期参与维护的开发者可填写项目维护者提供的贡献者申请表单。

注意：仓库是只读镜像，本文只介绍查看、安装、运行与配置方式；实际贡献请基于你的 Fork 仓库操作。

二、Pull Request 规范与评审流程

PR 提交清单

  • 从main分支切出工作分支，不要直接在 main 上开发；
  • 如果改动涉及行为变化，同步更新相关文档；
  • 提交前对所有功能做手动测试；
  • 每个 PR 聚焦一个功能或一个 Bug，避免混入无关改动。

评审流程

  1. 评审人员会对 PR 进行手动测试验证；
  2. 至少需要一名维护者审核通过；
  3. 开发者需要针对评审意见逐条修改并回复；
  4. 保持干净的提交历史（建议使用git rebase整理提交，避免大量冗余 merge commit）。

编码标准

  • 遵循仓库现有代码风格（ESLint + Prettier 已配置，见 eslint.config.mjs）；
  • 对复杂逻辑必须写注释；
  • 函数保持短小、单一职责；
  • 使用有意义的变量命名。

仓库的 package.json 提供了与上述标准配套的校验脚本：

npm run lint # 对 app 目录执行 eslint（带缓存） npm run lint:fix # eslint --fix 后自动运行 prettier 格式化 npm run typecheck # 运行 tsc 全量类型检查

三、本地开发环境搭建

1. 克隆仓库与安装依赖

git clone https://gitcode.com/gh_mirrors/bo/bolt.diy.git cd bolt.diy pnpm install

项目使用pnpm作为包管理器（package.json 中声明packageManager: "pnpm@9.14.4"），Node 版本要求>= 18.18.0。请勿混用 npm/yarn 安装依赖，否则锁文件pnpm-lock.yaml会失真。

2. 配置环境变量

环境变量配置分两步：

# 1) 从模板复制 cp .env.example .env.local # 2) 填入你要使用的服务 API Key

.env.example 是全仓库唯一的环境变量权威清单，按其注释可分为五类：

分类变量说明
AI Provider API KeysANTHROPIC_API_KEY、OPENAI_API_KEY、GROQ_API_KEY、GOOGLE_GENERATIVE_AI_API_KEY、MISTRAL_API_KEY、DEEPSEEK_API_KEY、COHERE_API_KEY、CEREBRAS_API_KEY、FIREWORKS_API_KEY、PERPLEXITY_API_KEY、XAI_API_KEY、MOONSHOT_API_KEY、ZAI_API_KEY、TOGETHER_API_KEY、HuggingFace_API_KEY、HYPERBOLIC_API_KEY、OPEN_ROUTER_API_KEY、GITHUB_API_KEY对应各 LLM 服务商，其中GITHUB_API_KEY用于 GitHub Models（需 Fine-grained token 并开启 "GitHub Models" 权限）
自定义 Base URLOLLAMA_API_BASE_URL、OPENAI_LIKE_API_BASE_URL、OPENAI_LIKE_API_KEY、TOGETHER_API_BASE_URL、HYPERBOLIC_API_BASE_URL、LMSTUDIO_API_BASE_URL用于本地模型与兼容 OpenAI 协议的服务；Ollama/LMStudio 因 IPv6 问题不要用localhost，应写http://127.0.0.1:11434/http://127.0.0.1:1234
云服务AWS_BEDROCK_CONFIGJSON 格式，如{"region": "us-east-1", "accessKeyId": "...", "secretAccessKey": "..."}
平台集成VITE_GITHUB_ACCESS_TOKEN/VITE_GITHUB_TOKEN_TYPE、VITE_GITLAB_ACCESS_TOKEN/VITE_GITLAB_URL/VITE_GITLAB_TOKEN_TYPE、VITE_VERCEL_ACCESS_TOKEN、VITE_NETLIFY_ACCESS_TOKEN、VITE_SUPABASE_URL/VITE_SUPABASE_ANON_KEY/VITE_SUPABASE_ACCESS_TOKEN带VITE_前缀的变量会被 Vite 注入前端，用于 GitHub/GitLab 代码导入、Vercel/Netlify 部署、Supabase 数据访问等自动连接能力
开发设置NODE_ENV、PORT、VITE_LOG_LEVEL、DEFAULT_NUM_CTX见下文

其中两个关键调优项：

# 日志级别：debug / info / warn / error VITE_LOG_LEVEL=debug # 默认上下文窗口大小（用于本地模型），仓库默认 32768 DEFAULT_NUM_CTX=32768

安全红线：.env.local（以及 Docker 场景下的.env）已被 .gitignore 忽略，严禁提交到版本控制，否则 API Key 会泄露。

Docker 用户额外注意：docker-compose.yaml 需要.env做变量替换。仓库提供了官方脚本 scripts/setup-env.sh 自动同步：

# 方式一：运行官方脚本（自动把 .env.local 同步到 .env） ./scripts/setup-env.sh # 方式二：手动复制 cp .env.local .env

该脚本的逻辑是：若存在.env.local且.env缺失或比.env.local旧，则将.env.local复制为.env；若连.env.local都没有，则交互式询问是否从.env.example生成两份文件。

3. 启动开发服务器

pnpm run dev

该命令实际执行node pre-start.cjs && remix vite:dev（见 package.json）。pre-start.cjs 会在启动前打印当前版本号（来自package.json的version）与 Git 短提交哈希，便于你确认自己在正确的代码版本上调试。

提示：原文档建议本地测试时使用Google Chrome Canary，这主要针对 WebContainer 与前端调试场景。

四、测试体系

运行全部测试：

pnpm test # 等价于 vitest --run（单次执行，非 watch 模式） pnpm test:watch # watch 模式，开发时持续监听

测试框架为Vitest（package.json 中vitest@^2.1.7），覆盖了从前端组件到运行时解析器的多个层次，可供你在贡献时参考测试写法：

  • app/components/chat/Markdown.spec.ts：Markdown 渲染组件测试；
  • app/lib/runtime/message-parser.spec.ts 及其快照 app/lib/runtime/snapshots/message-parser.spec.ts.snap：AI 消息解析器的行为测试与快照断言；
  • app/utils/diff.spec.ts：diff 工具函数测试。

新增功能时，遵循"同一 PR 内提交对应测试用例"的原则，能让评审更快通过。

五、构建与部署：Cloudflare Pages

本地预览构建产物：

pnpm run build # remix vite:build，产出 SSR + client pnpm run start # 用 Wrangler 本地托管 ./build/client（自动识别平台执行 bindings.sh）

发布到 Cloudflare Pages：

pnpm run deploy # npm run build && wrangler pages deploy

前置条件：拥有对应 Cloudflare 账号权限，且已配置好Wrangler（项目根目录含 wrangler.toml 与 worker-configuration.d.ts）。注意pnpm run deploy只发布静态产物，API 路由等 Worker 能力依赖 Cloudflare 平台配置。

六、Docker 部署（开发环境 / 生产环境）

多阶段构建结构

Dockerfile 采用多阶段构建，定义了四个关键阶段，理解它能帮你正确使用下面的命令：

  1. build：基于node:22-bookworm-slim，启用 pnpm 并安装 Git（构建期需要），执行pnpm install --offline --frozen-lockfile后运行pnpm run build（设置NODE_OPTIONS=--max-old-space-size=4096防止 OOM）；
  2. prod-deps：在 build 基础上pnpm prune --prod，只保留生产依赖；
  3. bolt-ai-production：生产运行时镜像，包含HEALTHCHECK（每 10s curlhttp://localhost:5173/）、关闭 Wrangler 遥测，默认执行pnpm run dockerstart；
  4. development：开发运行时镜像，保留全部依赖与源码，默认执行pnpm run dev --host。

镜像内 API Key 一律在运行时通过-e或 Compose 注入，Dockerfile 中已明确注释这一点，避免把密钥烘焙进镜像层。

开发环境构建（三种等价方式）

# 方式一：npm 辅助脚本 npm run dockerbuild # docker build -t bolt-ai:development -t bolt-ai:latest --target development . # 方式二：直接指定构建目标 docker build . --target bolt-ai-development # 方式三：Compose profile docker compose --profile development up

启动开发容器：

docker run -p 5173:5173 --env-file .env.local bolt-ai:development

生产环境构建（三种等价方式）

# 方式一：npm 辅助脚本 npm run dockerbuild:prod # 同时打 bolt-ai:production 与 bolt-ai:latest 两个 tag # 方式二：直接指定构建目标 docker build . --target bolt-ai-production # 方式三：Compose profile docker compose --profile production up

启动生产容器：

docker run -p 5173:5173 --env-file .env.local bolt-ai:production

docker-compose.yaml 的三个服务

docker-compose.yaml 定义了三个服务，与文档中的 profile 方式一一对应：

服务镜像/构建目标profile关键差异
app-devdevelopment阶段development、default挂载源码卷 +/app/node_modules匿名卷，开启CHOKIDAR_USEPOLLING/WATCHPACK_POLLING支持容器内热更新，设置VITE_HMR_*以便 HMR 走 WebSocket
app-prodbolt-ai-production阶段production只拷贝构建产物与生产依赖，执行dockerstart
app-prebuildghcr.io/stackblitz-labs/bolt.diy:latest预构建镜像prebuilt免构建直接拉取官方镜像运行

两个自建服务都通过env_file同时读取.env与.env.local，并在environment中显式透传各 API Key，同时设置RUNNING_IN_DOCKER=true、DEFAULT_NUM_CTX=${DEFAULT_NUM_CTX:-32768}、VITE_LOG_LEVEL=${VITE_LOG_LEVEL:-debug}等默认值；extra_hosts中的host.docker.internal:host-gateway保证容器内能访问宿主机上的 Ollama 等本地服务。这正是前文要求把.env.local同步到.env的原因——Compose 依赖.env完成environment段的${VAR}替换。

在 Coolify 等 PaaS 上部署

对于需要图形化面板的部署场景，原文档给出了一条基于 Docker Compose 的通用路径（可类比 Coolify 等支持 Compose build pack 的平台）：

  1. 将 Git 仓库导入平台；
  2. 选择Docker Compose作为构建方式；
  3. 在平台面板中配置环境变量（各 API Key）；
  4. 将启动命令设置为：
docker compose --profile production up

七、VS Code Dev Containers 集成

仓库根目录的 docker-compose.yaml 与 Dev Containers 规范兼容，可在 VS Code 中一键获得预配置的开发环境：

  1. 打开命令面板：Ctrl+Shift+P（macOS 为Cmd+Shift+P）；
  2. 执行Dev Containers: Reopen in Container；
  3. 出现提示时选择developmentprofile；
  4. VS Code 会基于app-dev服务重建容器并自动打开工作区。

该方式直接复用上文developmentprofile 的源码挂载与热更新配置，无需额外编写.devcontainer文件，环境一致性由同一份 Compose 配置保证。

八、环境变量速查与常见坑

高频变量一览

  • DEFAULT_NUM_CTX：本地模型的上下文窗口大小。原文档给出的一个典型调优示例为DEFAULT_NUM_CTX=24576 # 约占用 32GB VRAM；仓库默认值32768对应 .env.example 与 docker-compose.yaml 中的默认配置。显存较小（如 24GB 及以下）的机器建议调低，避免 OOM。
  • VITE_LOG_LEVEL：前端日志级别，调试阶段设为debug，生产可降为info/warn。
  • PORT：应用端口，默认5173，Docker 场景已在 Dockerfile 中以ENV PORT=5173、ENV HOST=0.0.0.0固化，便于容器外访问。

常见坑

  1. 本地模型连不上：Ollama/LMStudio 的 Base URL 必须用127.0.0.1而非localhost（IPv6 解析问题，见 .env.example 注释）；在 Docker 内访问宿主机服务时，则依赖host.docker.internal映射。
  2. Compose 变量未注入：docker compose up前务必保证.env存在（运行 scripts/setup-env.sh），否则${OPENAI_API_KEY}等引用会被替换为空。
  3. 密钥入库：.env.local与.env均在.gitignore中，提交前可用git status复核。

九、参与 checklist

最后，将全文要点收敛为一份可对照执行的贡献清单：

  1. 阅读并遵守项目 Code of Conduct；
  2. 从main分支切出单功能分支；
  3. 修改代码并遵循现有风格（npm run lint、npm run typecheck通过）；
  4. 为改动补充测试，pnpm test全绿；
  5. 本地或容器内手动验证功能（含环境变量正确注入）；
  6. 更新相关文档与pnpm-lock.yaml（若依赖有变更）；
  7. 保持提交历史干净，提交 PR 并等待至少一名维护者评审。

完成以上步骤，你就走完了从"报告 Issue"到"代码合入"的完整贡献闭环，也顺带掌握了 bolt.diy 从本地、容器到 Cloudflare Pages 的整套运行与部署能力。

  • AI 应用
  • 代码智能体
  • AI Agent
  • 大模型
  • 开发工具

【免费下载链接】bolt.diy

Prompt, run, edit, and deploy full-stack web applications using any LLM you want!

项目地址：https://gitcode.com/gh_mirrors/bo/bolt.diy
点击查看免费下载

相关推荐

上一篇：PyTorch AO项目中torch._inductor模块配置属性缺失问题解析
下一篇：解决Micro编辑器在终端中Ctrl+S失效的终极方案

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

Ramda 类型系统实战：@types/ramda 类型推导与 5 大常见坑位排查指南
2026/9/20 6:23:06 网站建设

Ramda 类型系统实战：@types/ramda 类型推导与 5 大常见坑位排查指南

Ramda 类型系统实战：types/ramda 类型推导与 5 大常见坑位排查指南 【免费下载链接】ramda :ram: Practical functional Javascript 项目地址: https://gitcode.com/gh_mirrors/ra/ramda Ramda（ramda）是 JavaScript 世界最流行的实用函…...

阅读更多 →
扫码备份QQ空间：GetQzonehistory 10分钟把整段空间说说导出到本地
2026/9/20 6:22:35 网站建设

扫码备份QQ空间：GetQzonehistory 10分钟把整段空间说说导出到本地

扫码备份QQ空间：GetQzonehistory 10分钟把整段空间说说导出到本地 【免费下载链接】GetQzonehistory 获取QQ空间发布的历史说说 项目地址: https://gitcode.com/GitHub_Trending/ge/GetQzonehistory 上周我想翻一条大学时写的说说，QQ空间往回翻了…...

阅读更多 →
COSCon‘25双认可背后：开源十年演进与开发者真实需求
2026/9/20 6:21:57 网站建设

COSCon‘25双认可背后：开源十年演进与开发者真实需求

一条消息在开源圈里传了一阵：COSCon25 第十届中国开源年会，登上了中国日报，同时被思否评为「最受开发者欢迎的技术活动」。如果你不是混开源圈的人，可能觉得这就是条普通获奖新闻；但在里面待久了的人，看到这…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询