非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

如何为Jellyfin贡献代码

本文详细说明Jellyfin的代码仓库组织结构、如何开始编辑代码并创建首个拉取请求，以及关于Jellyfin拉取请求的通用流程。

应该参与哪些项目？

您可以通过浏览组织内的众多项目寻找贡献机会。这里重点介绍两个核心项目，分别适合后端和前端开发者：

• Jellyfin服务端：使用.NET 9和C#构建的服务核心

• Jellyfin Web：主要浏览器客户端应用，也被其他封装型客户端使用

注意：各仓库通常在其README文档中提供专属的入门指南。您也可查阅组织源码结构了解大型项目的组织方式。

开始实际开发的最佳方式是：在相关仓库的问题列表中寻找感兴趣的任务，然后直接动手！管理团队会定期对问题进行分类，并通过标签帮助您匹配技能范围。开始处理某个问题时，请在评论区声明工作意向，避免重复劳动。

功能提案

新增功能或对现有行为有重大影响且涉及多个子项目的修改，应首先通过Jellyfin元讨论区发起提案。

主要问题类型

完整问题类型清单请参见问题指南章节。

若没有现成问题？

如您要修改的内容暂无对应问题，请先创建问题进行跟踪，并确保后续拉取请求关联该问题。这对作者自行发现并修复的缺陷尤其重要，便于完整记录原始问题和修复过程。

如何进行修改？

确定要改进的内容后，下一步是在代码中实施修改、测试验证，最后在GitHub提交拉取请求（PR）。

为简化说明，所有示例均假设开发者使用Linux系统并通过SSH访问GitHub，但核心流程同样适用于HTTP协议访问方式，并可迁移至Windows或MacOS环境。

若您不熟悉Git，建议阅读官方文档了解版本控制系统原理及使用方法。

设置本地仓库

第一步是建立目标项目的Git仓库副本。Jellyfin采用“fork→功能分支→PR”的贡献模型：

1. 在GitHub目标仓库点击"Fork"按钮，将其复制到您的个人账户

2. 将fork克隆至本地并进入目录：

   git clone git@github.com:yourusername/projectname.git
   cd projectname/

3. 添加"upstream"远程仓库，便于同步主项目变更：

   git remote add upstream git@github.com:jellyfin/projectname.git

4. 要让 Jellyfin.Server 项目成功运行，需要同时检出服务器和网页客户端项目。

5. 使用 NPM 构建 Jellyfin Web 项目，并记录生成的 dist 文件夹位置。

6. 在您的 Jellyfin.Server 项目中添加名为 JELLYFIN_WEB_DIR 的环境变量，其值设置为 dist 文件夹的完整路径。可通过修改 Jellyfin.Server/Properties/launchSettings.json 文件中的 environmentVariables 配置实现：

   "environmentVariables": {
      "ASPNETCORE_ENVIRONMENT": "Development",
      "JELLYFIN_WEB_DIR": "/path/to/your/jellyfin-web/dist"
   }

现在您已准备好开始构建或修改项目。

修改代码库

准备好代码库后，即可开始工作。

1. 将本地分支基于上游 master 进行变基，确保使用最新变更：

   git fetch --all
   git rebase upstream/master

2. 从 master 创建本地功能分支进行修改：

   git checkout -b my-feature master

3. 在该功能分支上进行修改并提交。

4. 完成工作后，再次对功能分支执行步骤1，确保与起始后的其他变更无冲突。

5. 将本地功能分支推送到您的 GitHub 复刻库：

   git push --set-upstream origin my-feature

6. 在 GitHub 上创建指向上游 master 分支的 PR（请参照下文建议）。

7. PR 合并后，保持本地分支更新：

   git fetch --all
   git checkout master
   git rebase upstream/master
   git push -u origin master

8. 不再需要时可删除本地功能分支：

   git branch -d my-feature

CONTRIBUTORS.md 文件

首次向某代码库贡献代码时，请将您的名字添加到 CONTRIBUTORS.md 文件末尾的 Jellyfin Contributors 部分。虽然 GitHub 会追踪贡献者，但书面文档能确保代码离开 GitHub 时仍可追溯，也便于所有人快速查看项目参与者（用于版权声明或致谢）。

官方分支规范

功能分支

大型项目可能需要多人协作和多个 PR。此时应基于 master 创建专属功能分支。这既能避免长期破坏 master 分支，也能让参与者按自身节奏推进，无需赶在发布前紧急修复。创建功能分支需与核心团队成员沟通协调。

功能开发完成后，可一次性合并至 master 并删除该分支。对于超长周期功能，可将稳定版本快照按需合并至 master。

Master 主分支

master 是项目的主要开发分支。除紧急热修复外，所有 PR 都应指向 master。原则上 PR 不应破坏主分支，合并前必须测试验证。虽然人为失误难免发生，但通常可直接基于 master 构建获取 Jellyfin 的最新版本。

测试 Pull Request

要测试他人的 PR，需将变更导入本地代码库。

1. 获取拉取请求中的变更并将其关联到新的本地分支：

   git fetch upstream pull/<PR_ID>/head:my-testing-branch

   :::注意

   <PR_ID> 指 GitHub 上的拉取请求编号。

   :::

2. 切换到新建的本地分支：

   git checkout my-testing-branch

3. 执行必要的测试或构建操作，完成后返回主分支并删除该分支：

   git checkout master
   git branch -D my-testing-branch

拉取请求准则

提交新 PR 时请确保遵守以下事项。若尚未了解，建议阅读《如何编写 Git 提交信息》，这是撰写有效提交信息的绝佳参考。

• 提交 PR 前，请压缩"琐碎"提交以保持历史记录整洁。单个提交应包含一项实质性变更：避免将所有变更压缩在一起（尤其是涉及多文件的大型 PR），但也不要保留"修复此问题"、"修正拼写"这类提交，这会给项目历史带来不必要的冗余。

• 编写简洁明了的标题，快速描述变更内容。例如"为 Jellyfin 添加 LDAP 支持"。如《如何编写 Git 提交信息》所述，标题应使用祈使语气并保持简短达意。标题最终会成为更新日志条目，请采用规范的大小写格式且不加标点；请注意核心团队可能在合并前调整标题以符合此标准。

• 除可通过简短标题完全描述的琐碎变更外，请遵循 PR 模板并撰写 PR 正文详细说明：

  1. 变更的原因。尽可能使用关键词（fixes/closes/addresses 等）关联具体议题。

  2. 解决问题的思路（如适用）并简述变更，这对大型 PR 尤为重要。

• 若拉取请求尚未完成，请在创建时标记为"草案"。此标签存在期间，PR 不会被合并，审阅意见应仅以评论形式存在。完成最终修改后请移除此标签；忘记操作可能导致 PR 因"开发中"状态被忽略！长期未更新的 WIP 可能收到团队的状态询问，若无响应将被关闭。

• 尽量避免对大型或复杂 PR 进行变基和强制推送（尤其审阅后），这会导致不必要的重复验证。

• 做好接受审阅和讨论的准备。若无法通过清晰描述和审阅论证变更合理性，请重新评估变更必要性。所有向 dev 分支的 PR 至少需要一名管理团队成员批准，但我们欢迎并鼓励所有贡献者参与审阅（特别是您熟悉的领域），多视角审查总是有益的。

• 所有 PR 需经至少两名团队成员审阅方可合并至 master（但欢迎所有贡献者审阅！）。第二位团队成员审阅通过后，可立即合并或根据需要征询其他贡献者意见。

在 Docker 容器内构建与测试

需先在容器内安装所有开发依赖项并拉取代码，才能进行编译和运行。

:::注意

请逐行执行命令。我们将使用的测试容器名为 jftest。在 Docker 内部，当入口点可执行文件终止时会话会重启，因此重新进入容器即可继续操作。这也是我们显式终止它以重新加载新版本的原因。

:::

主分支流程

docker exec -ti jftest bash
apt-get update && apt-get install -y git gnupg curl autoconf g++ make libpng-dev gifsicle automake libtool gcc musl-dev nasm ca-certificates
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -LO https://packages.microsoft.com/config/debian/12/prod.list && mv prod.list /etc/apt/sources.list.d/microsoft-prod.list
apt-get update && apt-get install -y dotnet-sdk-8.0
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
apt-get update && apt-get install -y nodejs
cd /opt && git clone https://github.com/jellyfin/jellyfin.git && git clone https://github.com/jellyfin/jellyfin-web.git
cd jellyfin/ && DOTNET_CLI_TELEMETRY_OPTOUT=1 && DOTNET_CLI_HOME="/tmp/" dotnet publish Jellyfin.Server --configuration Debug --output="/jellyfin" --self-contained --runtime linux-x64
cd /opt/jellyfin-web && npm install && npm run build:development && cp -r /opt/jellyfin-web/dist /jellyfin/jellyfin-web
apt-get remove -y gnupg curl && apt-get clean -y autoclean && apt-get autoremove -y
kill -15 $(pidof jellyfin)

拉取请求流程

首先完成上述步骤，配置容器以构建主分支。

备注

<PR_ID> 是 GitHub 上的拉取请求（Pull Request）编号。

docker exec -ti jftest bash
cd /opt/jellyfin
git fetch origin pull/<PR_ID>/head:my-testing-branch
git merge my-testing-branch
dotnet build
kill -15 $(pidof jellyfin)