🧪 开发分支指南
想在正式发布前体验最新功能吗？dev 分支包含前沿改进和实验性功能，它们最终会进入主发行版。
dev 分支处于实验阶段，可能包含缺陷、未完成功能或破坏性变更。只有在你能接受潜在的不稳定性并愿意帮助改进 Libre WebUI 时才应使用它。
🎯 什么是 Dev 分支？
开发分支（dev）用于在新功能合并到稳定的 main 分支之前进行测试。它包括：
- 尚未进入稳定发行版的最新功能
- 正在测试的缺陷修复
- 针对界面和功能的实验性改进
- 正在开发的性能优化
🚀 如何使用 Dev 分支
Docker 设置（推荐）
开发版 Compose 文件会挂载主机 Docker socket，因此在 Docker 可用时，Work 默认即可运行。任务容器在主机守护进程上运行，并会显示在 docker ps 中。在 Linux 上，请先在 .env 中设置 DOCKER_GID。
使用外部 Ollama：
# Clone the repository
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui
# Switch to dev branch
git checkout dev
# Start the dev image with external Ollama
docker compose -f docker-compose.dev.external-ollama.yml up -d
简单 Docker 方式：
# Use the dev branch image
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev
从源代码运行
# Clone and switch to dev branch
git clone https://github.com/libre-webui/libre-webui.git
cd libre-webui
git checkout dev
# Install dependencies
npm install
# Start development server
npm run dev
Vite 可能会在后端完成启动检查之前就绪。对于本地后端，开发代理在转发 API 请求前最多等待 10 秒，直到其监听端口就绪。每个请求只会转发一次，写请求也一样；失败的请求不会重放。如果后端仍不可用，代理会返回 HTTP 503 并附带重试提示。等待期间静态前端文件仍可正常访问。
聊天在后端出现短暂中断后会持续重新连接，重连间隔上限为 30 秒。连接成功后间隔会重置；退出登录会取消待处理的重试。身份验证失败会停止自动重连。
测试 Work
- 启动 Docker，并以运行后端的同一用户确认
docker info成功。 - 使用
npm run dev从源代码启动 Libre WebUI。 - 以管理员身份登录。
- 选择 Work，并使用支持工具调用的 Ollama、Ollama Cloud 或已配置的插件模型。
运行专门的后端提供商和容器策略测试：
npm run test:work
这些测试会验证生成的 Docker 策略、路径包含关系、生命周期与容量行为，以及 OpenAI 兼容、Anthropic 和 Gemini 工具适配器。完整运行时边界请参阅 Work：隔离工作区。
🔄 保持更新
dev 分支更新频繁。获取最新变更：
# Update your local dev branch
git pull origin dev
# Refresh the dev Compose stack
docker compose -f docker-compose.dev.external-ollama.yml pull
docker compose -f docker-compose.dev.external-ollama.yml up -d
# Or restart simple Docker
docker pull ghcr.io/libre-webui/libre-webui:dev
docker stop libre-webui-dev && docker rm libre-webui-dev
docker run -d -p 3000:3001 -v libre-webui:/app/backend/data --name libre-webui-dev --restart always ghcr.io/libre-webui/libre-webui:dev
🐛 发现缺陷？帮助我们改进！
你的缺陷报告非常宝贵！以下是有效报告问题的方法：
报告前
- 检查现有问题：搜索 GitHub Issues，避免重复报告
- 尝试稳定版：确认缺陷只存在于 dev，而不在 main 分支中
- 稳定复现：能否让缺陷再次出现？
如何报告缺陷
请包含以下信息：
**Environment:**
- Branch: dev
- Version: [git commit hash or date]
- OS: [Windows/macOS/Linux]
- Browser: [Chrome/Firefox/Safari version]
- Setup: [Docker/Source/etc.]
- Docker: [version and whether `docker info` succeeds, for Work issues]
- Work model/provider: [exact route, when applicable]
**Bug Description:**
Clear description of what went wrong
**Steps to Reproduce:**
1. Go to...
2. Click on...
3. See error...
**Expected Behavior:**
What should have happened
**Actual Behavior:**
What actually happened
**Screenshots/Logs:**
[If applicable, add screenshots or error logs]
**Work Activity:**
[Relevant tool call/result or preview output, with secrets removed]
获取 Git 提交哈希
# Find your current dev branch commit
git rev-parse HEAD
# Or get a short version
git rev-parse --short HEAD
🏆 贡献与认可
使用 dev 分支就意味着你加入了我们的测试社区！贡献者会通过多种方式获得认可：
对贡献者的认可
- 列入 CONTRIBUTORS.md
- 对重大贡献在发行说明中提及
- 在提交消息中标注共同作者
- 在项目公告中特别致谢
当前贡献者
我们出色的社区包括：
想贡献代码？
- 复刻仓库
- 从
dev创建功能分支：git checkout -b feature/amazing-feature dev - 进行修改
- 向
dev分支提交 Pull Request
详细说明请参阅贡献指南，项目道德准则和治理模式请参阅社区宪章。
Pull Request 检查
每个 Pull Request 都会运行 Format & Lint 工作流，包括合并到中间功能或修复分支的堆叠式 Pull Request。其独立作业会检查格式、前端和后端 lint、TypeScript 类型、软件包与回归测试，以及 Playwright 浏览器测试套件。Chromium 运行完整的浏览器测试套件。WebKit 和 Firefox 也会运行关键的身份验证、流式传输、对话框、标签页、自动化、存储、Work 和语音播放流程。每个浏览器引擎都在各自的 CI 作业中运行，运行失败时会分别上传测试结果。
经过测试的 npm tarball 会在 Linux、macOS 和 Windows 上安装到一个全新的使用方目录中，并且同时使用 Node 22.22 和 Node 24。这些检查会安装真实的生产依赖，不借用检出目录中的 node_modules，然后验证 CLI 启动、就绪状态、前端服务，以及重启后的数据。要在本地运行相同的检查，请在 npm run build 之后执行 npm run test:package-install；传入一个 tarball，或传入只包含一个 tarball 的目录，即可测试特定产物。预构建依赖不可用时，全新安装需要能够访问软件包注册表，并满足该平台构建原生模块的常规前提条件。
另有一个单独的 Work Computer 作业，它会基于运行时固定的基础镜像构建 GUI 镜像，并运行真实的交互回归测试。设置 TEST_WORK_COMPUTER=1 后，缺少 Docker 守护进程或镜像会让检查失败，而不是跳过。要在本地复现，请设置该标志，并将 WORK_COMPUTER_TEST_IMAGE 设为单独构建的测试镜像，然后运行 npm run test:work-computer。未启用强制模式时，如果可选的 GUI 测试夹具不存在，本地运行仍会报告为跳过。
此矩阵为受支持的功能面增加了检查，但不会启用不受支持的组合。节点本地的 CLI 凭据对外部团队工作节点仍然不可用。
CodeQL 会在每个 Pull Request 上覆盖 JavaScript/TypeScript、Python 和工作流代码。examples/ 下可执行的 Python 提供商服务器在 .gitattributes 中被明确归类为代码，因此 GitHub 的语言检测会包含它们。单独托管的 Code Quality 设置应同时包含 JavaScript/TypeScript 和 Python。如果修复后仍有历史发现项，请核实所分析的修订版本和语言覆盖范围，并在发布更改后刷新相应的分析。不要为了提高显示的评分而忽略有效的发现项，或者修改原本正确的异步行为。
Electron Dev Build 工作流还会打包 macOS、Windows 和 Linux 产物。macOS Pull Request 构建会保留项目不使用凭据的临时签名，以便在上传前验证打包应用。Pull Request 工作流不会接收 Developer ID 或公证凭据。
Docker Build Test and Push 工作流会为每个 Pull Request 构建 amd64 和 arm64 镜像，包括进入中间分支的堆叠式 Pull Request。Pull Request 构建不会登录容器注册表、推送镜像摘要或发布多架构清单。
打开 Pull Request 前，请在本地运行相同的应用级检查：
npm run format:check
npm run lint
npm run test:package
npm run test:e2e
⚠️ 重要说明
数据安全
- 切换到 dev 分支前请备份数据
- Work 任务文件位于单独的
libre-work-*Docker 命名卷中。测试破坏性任务或用户生命周期变更前，请将它们与 SQLite 数据目录分开备份。 - dev 测试请使用单独的 Docker 卷：
# Use different volume name for devdocker run -d -p 3000:3001 -v libre-webui-dev:/app/backend/data --name libre-webui-dev ghcr.io/libre-webui/libre-webui:dev
潜在问题
- 破坏性变更可能需要更新配置
- 功能可能尚未完成，或在不另行通知的情况下发生变化
- 测试优化期间，性能可能有所波动
- 界面元素可能外观不同或行为异常
何时使用稳定版
如果存在以下情况，请切回稳定的 main 分支：
- 重要工作需要可靠性
- 遇到太多缺陷
- 希望获得经过测试的稳定体验
# Switch back to stable
git checkout main
docker compose -f docker-compose.external-ollama.yml pull
docker compose -f docker-compose.external-ollama.yml up -d
🌟 加入社区
- GitHub Discussions：分享想法并提出问题
- Issues：报告缺陷和请求功能
- 贡献者：看看谁在帮助构建 Libre WebUI
准备好帮助塑造 Libre WebUI 的未来了吗？ 🚀
你在 dev 分支上的测试、反馈和贡献会直接改善所有用户的体验。感谢你成为开发社区的一员！