跳到主要内容

🤝 参与贡献 (Contributing)

帮助我们共同构建每个人都值得拥有的优秀 AI 交互界面。

Open WebUI 是一个独立的开源项目，由一个规模精简且充满激情的核心团队进行开发与日常维护。事实上，许多最宝贵的贡献并不一定局限于编写代码——测试开发分支的最新构建、提交清晰的 Bug 报告、在社区论坛中建言献策、持续改进文档翻译，以及进行网页 UI 的多语言本地化，均能对本项目产生极为巨大的影响。本页面将向您介绍如何参与其中以及后续的贡献期望。

社区行为准则​

所有贡献者及社区参与者都必须无条件遵守我们的 行为准则 (Code of Conduct)。我们执行严格的 零容忍政策：对任何社区成员采取不尊重、理所当然的态度或敌意行为，均将导致相关账号及人员在无需事先预警的情况下，立即被移除出社区。

本开源项目是由志同道合的志愿者们在业余时间无偿奉献建立的。请在每一次沟通中都保持绝对的专业、善意与互相尊重。

贡献方式​

1. 测试开发分支 (dev branch)​

这是无需编写任何代码便能做出的最宝贵的贡献之一。直接运行我们的开发分支，将其作为您的日常工具使用，并积极报告发生的任何异常或破损。

docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:dev

由于开发分支（dev branch）迭代频繁、更新速度极快，请定期拉取最新的 Docker 镜像。如果您不想使用 Docker，请参考 Open WebUI 本地开发环境搭建 教程进行手动构建。

若发现问题，请在 GitHub Issues 提交报告，并附带清晰的复现步骤。没有社区的高频测试，我们就无法交付高质量的稳定版本。

2. 提交代码 (PR)​

对项目最有影响力的贡献方式还包括：撰写高品质的 Bug 报告、参与功能的深度技术论证，以及在 GitHub Discussions 中提出富有远见的想法。这些意见将直接塑造 Open WebUI 的未来走向。

如果您决定向我们提交 Pull Request (PR)，请理解 Open WebUI 对代码质量、一致性以及系统架构的连贯性均执行行业极其严苛的标准。任何一行被合并的代码，都意味着核心开发团队必须在未来无限期地为其承担运维、重构和技术支持责任。因此，您提交的代码可能会被核心团队重新重构、改写，甚至仅作为实现另一套不同设计方案的灵感来源。这绝不是对您工作质量的否定，而是我们确保一个微型核心开发团队能够深度掌控、演进系统每个核心组件的必要手段。

在提交 PR 之前，请务必遵守：

  1. 先发起社区讨论：在开始编写代码前，请先在 社区讨论区 提出您的构想，以便团队在技术路线上与您达成共识。
  2. 遵循现有的代码规范：代码编写必须与项目既有的编码风格、命名模式及底层架构保持高度一致。
  3. 保持 PR 的原子性：每个 PR 应当仅聚焦并解决一个单一的具体目标。若开发规模扩大，请将其拆分为多个体积更小、逻辑相互独立的子 PR。
  4. 尽量避免引入新的外部依赖：在未事先深入论证前，请勿随意添加任何第三方库或框架。我们的设计目标是保持底层的轻量化，在可行情况下尽量由我们自己手写实现相应功能。
  5. 附带完善的自动化测试：新功能开发应配套对应的自动化测试，并同步更新相应的文档。
  6. 编写清晰的 Commit 信息：使用具描述性的 Commit 信息能极大提升代码审查及历史版本回溯的效率。

3. 改进文档 (Improve Docs)​

您可以帮助我们撰写更通俗易懂的文档、编写详尽的配置实战指南或入门教程。所有的文档项目均托管在 Docs 官方仓库 中。

4. 汉化与多语言本地化 (i18n)​

Open WebUI 的前端国际化翻译文件存放在 src/lib/i18n/locales 目录下，均为 JSON 字典格式。每个语言的子目录均使用规范的 ISO 639 语言代码（例如 en-US、zh-CN、fr-FR）进行命名。

若要为系统添加新语言的界面汉化：

  1. 在 src/lib/i18n/locales 目录下创建一个与目标语言代码相对应的新文件夹；
  2. 将 en-US 目录下的所有原始 JSON 文件拷贝至该新文件夹中；
  3. 在保持 JSON 对象层级结构完好无损的前提下，逐个将字符串值翻译为目标语言；
  4. 在 src/lib/i18n/locales/languages.json 配置文件中注册并启用该新语言。

5. 优化无障碍支持 (Accessibility)​

无障碍支持是优秀产品设计中不可或缺的灵魂。在向我们贡献 UI 修改时，请严格遵守以下标准：

核心原则落地执行规范
语义化 HTML优先使用 <button>、<label>、<nav> 等原生语义化元素，严禁滥用 generic 的 <div> 标签进行层层包裹
纯键盘导航支持确保网页上所有的交互式组件均能在脱离鼠标、仅依靠键盘导航的情况下流畅操作
ARIA 无障碍标签在语义化 HTML 依然无法充分满足无障碍表达的复杂交互组件中，必须补齐 ARIA 角色与标签属性
高对比度色彩使用 WebAIM 对比度检查工具 校验所有前背景色对比度是否达标
图片替代文本为具备明确含义的配图补充详尽描述性的 alt 替代文本属性；对于纯装饰性无实际含义的图片，使用 alt="" 占位符

在提交 UI 修改后，请使用 Lighthouse 或浏览器自带的 Accessibility 无障碍检测工具进行全面自测。

如何规范地提交 Bug 报告​

在发起新的 Issue 之前，请务必先检索 GitHub Issues 列表 确认是否已有重复的问题。在提交时：

  • 严格使用提供的 Issue 模板：未按要求填写模板或缺失关键排障日志信息的 Issue 可能会被直接关闭。
  • 提供详尽的重现步骤：清晰说明您的操作流程、预期输出结果以及实际发生的报错异常。
  • 描述力求精准详实：过于空洞模糊的报告（如“它用不了”、“白屏了”）将无法获得有效的调查。
技术支持与答疑范畴说明

Open WebUI 官方支持标准的 Docker 容器化部署方案，但我们默认您已掌握 Docker 容器的基本操作常识。对于有关反向代理（Reverse Proxy，如 Nginx）、容器虚拟网络配置或宿主机 OS 底层系统调优等技术答疑，均超出了本项目的技术支持范畴。遇到此类问题，请参阅 Docker 官方文档 自行配置。

获取联系方式​

官方频道快速加入链接
Discord 官方社区discord.gg/5rJgQTnV4s
Reddit 社区r/OpenWebUI
GitHub Issuesopen-webui/open-webui/issues
GitHub Discussionsopen-webui/open-webui/discussions
This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.