企业官网建设流程全解析

• 包管理器
• 操作系统

Chromium 是 Nixpkgs 中最复杂、更新最频繁的桌面浏览器包之一，其维护涉及版本锁定、数百个 Git 依赖的哈希解析、Nix 沙箱适配补丁以及 VM 集成测试等多个环节。本指南以 chromium 包目录 的维护文档（README.md）为骨架，结合仓库内真实的更新脚本、锁文件与构建定义，系统讲解 Chromium 在 Nixpkgs 中的版本更新流程、安全回移（backport）规范、测试策略与大版本升级排障方法。读完本文，你将掌握如何一键升级 Chromium、如何选择性地运行 NixOS VM 测试、如何处理大版本升级导致的编译失败，以及 Chromium 与其他浏览器包（google-chrome、ungoogled-chromium、chromedriver、Electron）之间的依赖关系。

维护者与相关包生态

Chromium 包的维护者页面（见 README.md 的 "Maintainers" 一节）长期欢迎更多贡献者、测试者与审阅者参与，特别点名了以下几类工作：

• 专职维护 NixOS stable 通道的维护者；
• 提交清理、改进、修复类 PR 的贡献者（同时希望尽量降低他人 review 的难度）；
• 处理陈旧 issue / PR 的人员。

在 Nixpkgs 中，Chromium 并非孤立存在，围绕它构建了完整的浏览器生态，且它们共享同一份上游版本信息：

这份共享机制在源码中体现为 default.nix 里的默认参数：

upstream-info ? (lib.importJSON ./info.json).${if !ungoogled then "chromium" else "ungoogled-chromium"},

也就是说，chromium与ungoogled-chromium两个属性都从同一个 info.json 中读取各自的版本与依赖锁定信息；electron-source则通过 common.nix 中的isElectron = packageName == "electron"分支复用同一套构建框架。这意味着一次上游版本更新，会同时影响这一整条浏览器生态链。

上游信息与版本数据源

维护文档的 "Upstream links" 一节列出了跟踪 Chromium 上游动态所需的核心资源：

• 源码仓库：Chromium 官方源码站（source.chromium.org）；
• Bug 追踪：Chromium 官方 Bug 列表（bugs.chromium.org）；
• 发布更新：Chrome 版本发布博客（chromereleases.googleblog.com），支持 Atom / RSS 订阅，建议过滤 "Stable Channel Update for Desktop" 关键词；
• 版本历史 API：Chrome 版本历史查询接口（developer.chrome.com的 Version History 指南）；
• 发布计划：Chromium 版本发布排期表（chromiumdash.appspot.com/schedule）。

这些资源的具体 URL 均记录在 README.md 的 "Upstream links" 小节中，是确认新版本号、评估发布节奏的第一手来源。

在 Nixpkgs 仓库内部，真正的"版本事实"由 info.json 承载。以当前锁文件为例，chromium条目记录了：

• version：如154.0.8037.97，对应上游稳定版；
• chromedriver：单独记录version及 macOS 两个平台的二进制哈希（hash_darwin、hash_darwin_aarch64）；
• deps：depot_tools、gn（含version/rev/hash）以及npmHash；
• DEPS：Chromium 的全部 Git 依赖清单，每个条目包含url、rev、hash，src主源码还带有recompress: true标记。

ungoogled-chromium条目额外携带deps.ungoogled-patches（rev与hash），用于锁定补丁集版本。这些数据随后被 common.nix 中的chromiumDeps批量转换为fetchFromGitiles固定输出派生（FOD），再通过unpackPhaseSnippet在解包阶段逐一铺入构建树。

一键更新：update.mjs 的工作机制

维护文档给出的更新命令极其简洁：

./pkgs/applications/networking/browsers/chromium/update.py

在当前仓库中，这个更新入口已经演进为 update.mjs（以 zx 脚本形式实现，文档描述的历史 Python 脚本update.py即其前身）。它读取锁文件 info.json，逐个属性（chromium、ungoogled-chromium）执行以下流程：

1. 探测上游最新版本：通过 Chrome 版本历史 API 查询 Linux 平台稳定通道的最新版本（见 update.mjs），并过滤fraction >= 0.5以确保是全面放量的版本；ungoogled-chromium则先拉取其 GitHub tags，再与 Chromium 稳定版本做交集匹配（update.mjs）；
2. 版本比较：使用version_greater_than做数值化比较，仅当上游版本更新时才继续（update.mjs）；
3. 解析依赖：通过 depot_tools.py 调用 depot_tools 的gclient_eval递归求值 Chromium 的DEPS文件，输出完整的依赖图（url / rev 对）；
4. 哈希预取（FOD prefetch）：对每个依赖执行nix-build并从 stderr 中正则提取got: sha256-...哈希（见 update.mjs）；已有哈希的依赖会跨属性复用缓存（update.mjs），避免重复下载；
5. 同步锁定：将结果写回 info.json（通过 Proxy 实现属性赋值即落盘），同时更新npmHash、gn、depot_tools等构建工具锁定。

更新脚本支持按属性定向更新，例如只更新ungoogled-chromium：

./pkgs/applications/networking/browsers/chromium/update.mjs --ungoogled-chromium

也可以显式指定 ungoogled 补丁集的 revision：--ungoogled-chromium-rev <rev>。由于chromedriver必须与 Chromium 主版本一致，脚本在更新chromium时会同步获取chromedriver的 macOS 二进制哈希（update.mjs），保证两个包版本永远配对。

更新后必做的验证

文档强调，运行更新脚本之后至少需要验证：

• nixosTests.chromium（或进行基本的手动测试）；
• google-chrome（它复用upstream-info数据，必须确认没有因版本漂移而损坏）。

另外有一个时间敏感点：Chromium 的源码 tarball 往往在发布公告几小时后才可用，因此 CI 可能短暂处于失败状态。README 记录了可跟踪 tarball 发布状态的 Chromium 官方 CI 构建器页面（publish_tarball与publish_tarball_dispatcher），这些信息用于判断"上游还没放包"而非"我们的补丁坏了"。

跑通全部 VM 集成测试

README 提供了两种测试粒度。全部自动化 NixOS VM 测试（覆盖 Chromium、ungoogled-chromium 与 Google Chrome 三个浏览器，文档明确提示"不推荐，目前是 6 个测试"）：

nix-build nixos/tests/chromium.nix

单个测试（例如只测ungoogled-chromium）：

nix-build nixos/tests/chromium.nix -A ungoogled

其中-A对应的属性名来自 nixos/tests/chromium.nix 中的channelMap，读者可以查阅该文件获取当前可用的全部测试属性。两个注意事项：

1. 测试 Google Chrome 需要先执行export NIXPKGS_ALLOW_UNFREE=1，因为其包含专有组件；
2. 对于自定义构建，可以对channelMap进行 override，以适配自己的测试矩阵。

安全更新与 Backports 规范

Chromium 的每一次更新都被视为安全关键，因此文档对稳定通道的移植有明确的硬性要求：

• 所有更新应尽快移植到 stable 通道；
• 当新的稳定版发布后，旧版本仍会接受大约一个月的安全更新窗口；
• 一个月窗口结束后，必须将旧版 Chromium 标记为 insecure（文档以提交69e4ae56c4b为参考范例）；
• 标记 insecure 时必须同时覆盖所有使用upstream-info的浏览器（google-chrome、ungoogled-chromium等），并确保标记后的测试 job 依然能够成功。

这一规范与 Nixpkgs 的meta.knownVulnerabilities机制配合使用，是保障 NixOS 用户及时获得安全修复的最后一道防线。

大版本升级的已知问题与对策

Chromium 在主版本号升级时"经常性"编译失败（文档原话为 "regularly breaks on major updates"），原因集中在两类：

1. Nix 构建沙箱差异：沙箱内无法通过网络抓取依赖，也不使用标准的 FHS 路径，很多上游假设因此失效；
2. 缺失的上游修复：需要从其他发行版 backport 补丁。

README 明确列出了三个可靠的补丁与排障信息来源（Arch Linux 的 Chromium trunk、Gentoo 的www-client/chromium、Fedora 的 chromium rpm 仓库），这些都是社区维护 Chromium 构建的一线资料。此外还有一个非常实用的经验法则：

如果构建因未知编译器 flag 立即失败，通常意味着需要升级到新的 LLVM 大版本。

这条规则在 common.nix 中得到充分印证——其中按版本区间与 LLVM 版本双重条件挂载了大量补丁，例如chromium-147-llvm-22.patch、chromium-149-llvm-22.patch、chromium-152-dawn-llvm-22.patch、chromium-153-llvm-22.patch（见 patches 目录），条件均为chromiumVersionAtLeast "xxx" && lib.versionOlder llvmVersion "23"。也就是说，当仓库内的 LLVM 低于 Chromium 要求的版本时，通过回退（revert）上游新引入的编译 flag 来维持构建。类似地，针对 Rust 工具链的演进也有对应补丁（如chromium-142-bytemuck-rust-1.95.patch、chromium-141-rust.patch、chromium-150-rust.patch），说明大版本升级通常要同时协调 C++（LLVM/Clang）与 Rust 两条工具链的版本节奏。

Nix 沙箱适配的构建细节

除补丁外，common.nix 的postPatch阶段还展示了 Chromium 在 Nix 环境下的一整套适配手段，可作为理解"为什么大版本会坏"的参考：

• 用仓库提供的 gclient_args.gni 覆盖build/config/gclient_args.gni，并关闭checkout_mutter、checkout_glic_e2e_tests、checkout_clusterfuzz_data等非必要 checkout；
• 手工生成LASTCHANGE、GPU_LISTS_VERSION、SKIA_COMMIT_HASH、DAWN_VERSION等版本头文件，替代上游依赖 git 元数据的lastchange.py；
• 用符号链接把 Nixpkgs 的node、java、gperf、rustc、cargo、rustfmt、clang-format、esbuild、crubit等工具"塞回" Chromium 期望的third_party/...路径，模拟上游的预装工具布局；
• 通过replace_gn_files.py --system-libraries让 Chromium 链接系统库（如 flac、libjpeg、libxml、libxslt，见 common.nix）；
• 修改 sandbox 相关源码，使CHROME_DEVEL_SANDBOX环境变量指向 Nix store 中的沙箱二进制（common.nix），并在 default.nix 的 wrapper 脚本中动态设置该变量。

这些细节解释了 README 中"大版本升级需要各种补丁"的直接原因，也让读者在遇到新的大版本失败时知道该往哪些方向排查。

Beta 与 Dev 通道的定位

README 对 Beta / Dev 通道的使用边界有明确说明：

• 这些通道只用于提前测试和修复构建；
• 它们可能随时处于损坏状态（"may be broken at times"）；
• 绝不允许因为 Beta / Dev 的问题而推迟 stable 通道的更新。

也就是说，维护者可以将预发布版本作为"预警雷达"提前发现构建问题，但发布节奏必须以 stable 为准绳。这一策略在锁文件层面也得到了体现：info.json 只维护chromium与ungoogled-chromium两个稳定属性，并无 Beta/Dev 条目。

升级后的手工验收清单

自动化测试之外，README 提供了一套实用的手工测试清单，覆盖浏览器各关键子系统：

这套清单与 browser.nix 中requiredSystemFeatures = [ "big-parallel" ]、timeout = 172800（48 小时构建超时）等元数据配合，说明了 Chromium 包在 Nixpkgs 中属于重量级、长时间构建的包，任何升级都值得认真对待。

总结

Nixpkgs 的 Chromium 维护可以概括为三条主线：单一数据源（info.json 驱动 Chromium / ungoogled-chromium / chromedriver / google-chrome / Electron 的联动）、可重复的升级流程（update.mjs 完成版本探测、依赖解析与哈希锁定）、多层次的验证体系（VM 集成测试 + 手工验收清单 + stable 通道安全回移）。掌握这些机制后，无论是提交一个 Chromium 升级 PR，还是排查大版本编译失败，你都能沿着本文给出的文件路径快速定位到对应逻辑——这正是这一维护文档沉淀下来的核心工程经验。

• 包管理器
• 操作系统