跳至主内容
非官方测试版翻译

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

如何为Jellyfin贡献代码

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

应该参与哪些项目？​

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

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

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

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

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

主要问题类型​

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

若没有现成问题？​

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

如何进行修改？​

确定要改进的内容后，下一步是在代码中实施修改、测试验证，最后在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 文件夹的完整路径。

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

修改代码库​

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

  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)