• 后端
• 音视频
• 前端

Navidrome 是一个开源的 Web 音乐服务器与流媒体服务，允许你随时随地欣赏自己的音乐收藏。本指南以仓库根目录的 CONTRIBUTING.md 为主体，结合仓库内的 Makefile、git 钩子、CI 工作流 等源码级证据，完整讲解如何为 Navidrome 提报 Issue、搭建开发环境、按规范命名分支与编写 Commit，并最终提交一份高质量、可被合入的 Pull Request。

一、贡献概览：哪些途径可以参与

Navidrome 欢迎以多种方式参与贡献，CONTRIBUTING.md 将其归纳为四条主线：

• 提问求助（Asking Support Questions）：使用讨论论坛提问，而非 Issue 跟踪器；
• 遵守行为准则（Code of Conduct）：参与社区互动的前提；
• 提报 Issue（Issues）：报告 bug、提议新功能或与开发者讨论；
• 提交 Pull Request：直接贡献代码、文档或测试，是所有贡献路径的终点。

对应到仓库内部，社区协作基础设施包括根目录的 CODE_OF_CONDUCT.md、README.md 中的功能与安装说明，以及 .github/workflows 下的自动化流水线。下文逐一展开。

二、提问求助：先讨论，再提 Issue

CONTRIBUTING.md 明确规定：请不要使用 Issue 跟踪器提问。Navidrome 维护着一个活跃的讨论论坛，用户与开发者可以在此自由提问、交流使用经验。

这一约定的背后逻辑是：Issue 跟踪器应当保持"可追踪、可行动"的状态，用于承载明确的缺陷报告和特性提案；而开放式的"如何使用""怎么配置"类问题，放在讨论区更利于社区互助与沉淀。如果你不确定某个问题属于"用法咨询"还是"产品缺陷"，可以先在讨论区发布，由维护者引导你转为 Issue。

三、行为准则：社区互动的底线

所有参与者在任何社区空间（包括 Issue、PR、讨论区、社交渠道）都须遵守 CODE_OF_CONDUCT.md。该文件采用 Contributor Covenant 2.0 标准，核心要点包括：

• 承诺营造无骚扰的社区环境，尊重年龄、残障、种族、性别、宗教等各类差异；
• 明确列举不可接受行为：性化语言与图像、人身攻击、公开或私下骚扰、未经许可公布他人隐私等；
• 规定了分级处罚阶梯：纠正（Correction）→ 警告（Warning）→ 临时封禁（Temporary Ban）→ 永久封禁（Permanent Ban），并给出了各类违规对应的社区影响评估标准；
• 违规行为可向navidrome@navidrome.org举报，社区领袖有义务删除/驳回不合规的评论、代码、Wiki 编辑与其他贡献。

对于贡献者来说，最重要的实操含义是：即便你的技术提案完美，不合规的沟通方式也可能导致贡献被驳回。

四、提报 Issue 的规范流程

CONTRIBUTING.md 对 Issue 提报提出两项硬性要求：

1. 先搜索再提报：在提报新 Issue 之前，务必先搜索已有 Issue，确认该问题没有被重复提报；
2. 使用 Issue 模板：通过仓库提供的 Issue 模板（bug 报告、功能请求等分类入口）提交，便于维护者快速理解上下文。

此外，Issue 也是 Pull Request 的前置条件（详见下文第五节），因此提报时建议写清：可复现步骤、期望行为与实际行为、运行环境（操作系统、Navidrome 版本、部署方式）等信息，帮助维护者快速定位。

五、Pull Request 全流程：从分支到合入

CONTRIBUTING.md 规定，提交 PR 前必须依次完成以下步骤：

1. 先开对应 Issue：如果不存在，按第四节规范先创建 Issue，并在 PR 中关联它；
2. 检查重复：确认没有已打开或已关闭的、与你提交内容重复的 PR，避免重复劳动；
3. 搭建开发环境：安装依赖并准备本地开发环境（详见下文第六节）；
4. 新建分支：在 fork 的仓库上创建新分支，并按约定的命名规范命名；
5. 规范提交：Commit 信息遵循特定约定（详见下文第七节）；
6. DCO 签署：所有 Commit 必须通过git commit的--signoff选项提供 DCO 签署；
7. 关联 Issue：在 PR 描述中提供将被关闭的 Issue 链接。

5.1 分支命名规范

分支命名格式为：<Issue 标题>/<Issue 编号>。CONTRIBUTING.md 给出的示例：

git checkout -b adding-docs/834 master

这条命令从master创建名为adding-docs/834的分支，其中adding-docs是对 Issue 标题的简短概括，834是关联的 Issue 编号。这样的命名让分支与 Issue 一一对应，维护者在浏览分支列表时即可快速判断其归属与意图。

5.2 Pull Request 标题与正文

Push 之后从 fork 分支发起 PR。PR 标题可以直接复用type(scope): description - issue_number格式（与 Commit 规范一致，见下文），正文建议按如下模板组织：

Closes <Issue number along with link> Description (What does the pull request do) Changes (What changes were made ) Screenshots or Videos Related Issues and Pull Requests(if any)

其中Closes <Issue>一行会让 GitHub 在 PR 合入时自动关闭对应 Issue，是追踪闭环的关键。

六、搭建开发环境：仓库内的一键化支持

CONTRIBUTING.md 指引开发者前往官方文档查看开发环境搭建说明；在仓库内部，Makefile 提供了完整的自动化支持。以下是核心命令与其对应源码依据：

值得注意的细节：

• 环境版本要求：check_go_env/check_node_env会校验本机 Go 版本不低于 go.mod 中声明的版本（当前为go 1.27），Node 版本不低于 .nvmrc 中的版本（当前为v24）；
• 开发模式：make dev同时拉起 Vite 前端（ui目录）与带-race竞态检测的后端，其中后端由go tool reflex监听.go、.cpp、.h、navidrome.toml等文件变化自动重编译（见 reflex.conf）；
• 代码生成：make gen会运行go generate并调用 ndpgen 生成插件 PDK 代码；make wire重新生成依赖注入代码（见 server/wire_gen.go 相关生成文件）；
• 前端质量：ui侧通过 ui/package.json 提供npm run lint（eslint）、npm run prettier、npm run check-formatting、npm run test（vitest）等脚本，make lintall会串联执行。

七、Commit 规范：仓库合入的硬性约定

CONTRIBUTING.md 的核心技术内容即 Commit 信息规范。每条 Commit 必须遵循：

<type>(scope): <description> [optional body]

7.1 type：提交类型

type必须是以下 11 种之一：

若 PR 包含破坏性变更（breaking change），必须在可选的 body 部分添加BREAKING CHANGE标记，以便发布时识别并提示用户迁移。

7.2 scope、description 与 body

• scope：改动涉及的文件或目录。如果一次改动涉及多个位置，任选其一标注即可；
• description：对改动内容的简短描述；
• body（可选）：可包含对改动的简短说明，以及BREAKING CHANGE标记。

7.3 理想 Commit 示例

CONTRIBUTING.md 给出的完美示例：

git commit --signoff -m "feat(themes): New-theme - #834"

分解来看：feat表示新功能，themes是改动范围，New-theme是描述，- #834标注了关联 Issue；--signoff则满足 DCO 签署要求。这一条 Commit 同时承载了类型、范围、描述与追踪信息，正是社区希望的"自解释提交"。

八、仓库内的质量门禁：源码与 CI 佐证

CONTRIBUTING.md 约定之外，仓库通过自动化工具将上述规范落到了执行层面，可作为提交前自检清单的参考：

8.1 Git Hooks（提交前拦截）

make setup会通过setup-git目标将 git/ 下的钩子软链到.git/hooks（见 Makefile）：

• pre-commit：对暂存的.go文件执行goimports格式检查（排除_gen.go与.pb.go生成文件），未格式化即拦截提交并提示修复命令；
• pre-push：直接执行make pre-push，即lintall + testall全量质量检查，未通过则拒绝推送。

这意味着提交与推送两个环节都有自动化兜底，任何不符合格式规范或破坏测试的改动都会在进入远端前被拦截。

8.2 CI 流水线

.github/workflows 下提供了完整的持续集成与维护任务：

• pipeline.yml：主流水线，负责构建、测试与发布；
• coverage-on-pr.yml：PR 覆盖率检查；
• stale.yml：自动标记长期无活动的 Issue/PR；
• push-translations.yml 与 update-translations.yml：翻译文件同步与校验（Navidrome 使用 POEditor 进行多语言维护，详见 README.md）。

8.3 OpenAPI 规范一致性

Navidrome 的 API v1 采用规范优先的开发方式，api/openapi 存放多文件 OpenAPI 规范，Makefile 提供一组工具链：

• make api-lint：用 vacuum 校验规范语法与质量；
• make api-bundle：将多文件规范打包为 api/bundled/openapi.yaml 与 openapi.json；
• make api-gen：由打包后的规范生成服务端代码（输出到 server/apiv1）；
• make api-diff：对origin/master基线做破坏性变更检查（oasdiff breaking），防止 API 兼容性回退。

对涉及 API 的贡献者，这条链路意味着：修改 OpenAPI 规范后需运行make api-gen重新生成代码，并确保api-diff不报告破坏性变更。

九、测试与代码生成：改动前的自查清单

结合 Makefile 与 ui/package.json，一份完整的提交前自检清单如下：

1. Go 侧：make test（或指定包make test PKG=./server）、make test-race（竞态检测）；需要时用make watch让 ginkgo 监听代码变化持续跑测试；
2. 前端侧：cd ui && npm run lint && npm run type-check && npm run test；
3. 格式化：make format（前端 prettier + goimports +go mod tidy）；
4. 代码生成：改动接口/规范/插件定义后运行make gen、make wire，并提交生成产物；
5. 快照测试：改动 Subsonic API 响应时，用make snapshots更新 GoLand 快照测试；
6. 数据库迁移：新增迁移文件使用make migration-sql name=...或make migration-go name=...（基于 goose，迁移目录为 db/migrations）；
7. 最终门禁：make pre-push（等价于lintall + testall）通过后再推送。

十、收尾：从合并到持续参与

Push 分支后按 5.2 节的模板创建 PR，等待维护者 review。如果 PR 需要修改，直接在同一分支上追加 Commit 并推送即可，review 过程会持续更新。合入后，关联 Issue 会被自动关闭，你的贡献正式进入 Navidrome 代码库。

总结一下，向 Navidrome 提交一份合格贡献的完整链路是：搜索/提报 Issue → fork 并克隆 →make setup搭建环境 → 按<Issue 标题>/<编号>命名分支 → 按type(scope): description规范提交（记得--signoff）→ 通过本地 lint/test 与make pre-push→ 发起带Closes #编号的 PR。遵循这套流程，既能保证提交被快速合入，也是对维护者与其他贡献者的尊重。

• 后端
• 音视频
• 前端