ungoogled-chromium 开发实战分支模型、新增开关与 Chromium 版本升级全流程【免费下载链接】ungoogled-chromiumGoogle Chromium, sans integration with Google项目地址: https://gitcode.com/gh_mirrors/un/ungoogled-chromium本文以仓库内的 docs/developing.md 为主线系统讲解 ungoogled-chromium 的开发规范master分支的维护约定、如何为构建新增命令行开关与chrome://flags选项以及升级到新版 Chromium 时的完整工作流——从获取源码、更新剪枝/域名替换列表到用 Quilt 刷新补丁、校验与提交 Pull Request。读完后你能够独立完成一次针对新版 Chromium 源码的补丁集更新并理解 devutils/ 与 utils/ 下各辅助脚本在流程中的具体作用。仓库结构与开发流程的定位在展开具体步骤前先建立对仓库组件的整体认知详见 docs/design.mdungoogled-chromium 由“配置 源文件处理器 补丁 打包”组成而 docs/developing.md 所描述的更新流程正是围绕前三者展开。配置文件chromium_version.txt当前为153.0.8010.52、revision.txt当前为1表示叠加在该版本之上的修订序号、pruning.list约 1.4 万条待剪枝二进制路径、domain_substitution.list约 1.8 万条待域名替换路径、domain_regex.list21 条替换正则、downloads.ini源码压缩包下载地址与校验信息、flags.gnGN 构建参数。源文件处理器二进制剪枝Binary Pruning与域名替换Domain Substitution把 Google 相关域名替换为以qjz9zk结尾的不存在域名作为兜底拦截手段二者处理的文件清单都由devutils/update_lists.py自动生成。补丁全部位于 patches/ 目录遵循 GNU Quilt 默认格式patches/series 共 111 行定义补丁应用顺序其中#开头的行被忽略。补丁按core/涉及后台请求、Google 服务代码、预编译二进制必须随 Chromium 版本持续维护与extra/控制与透明性功能不保证跨版本保留分类再按ungoogled-chromium/、inox-patchset/、iridium-browser/、bromite/、debian/等来源分组另有upstream-fixes/存放上游修复。IMPORTANT所有配置文件必须使用 UTF-8 编码补丁要求为 unified 格式、hunk 头路径在首个斜杠之后对应 GNU patch 的-p1、必须无 fuzz 干净应用。这些格式约束是后续validate_*校验脚本的判定依据。分支模型master 与特性分支docs/developing.md 对分支的约定非常简短但明确开发聚焦于mastermaster上的任何改动都不应破坏构建唯一的例外是 Chromium 版本 rebase升级导致各平台构建暂时中断。大特性与热修复必须走独立分支完成后再向master发起 Pull Request。对拥有写权限的维护者可以直接通过 git 客户端合并分支合并后应当删除。从源码结构看这条约定与仓库的校验体系是一致的devutils/下配有check_all_code.sh、run_devutils_tests.sh、validate_patches.py等自动化检查意味着合入master的代码必须能通过补丁有效性验证这为“master 不随意破坏”提供了工具层面的保障。添加命令行开关与chrome://flags选项docs/developing.md 中这一节的要点新增开关的基本步骤遵循 Chromium 源码树内docs/how_to_add_your_feature_flag.md的说明即定义开关常量、注册到command_line、在 UI/逻辑处消费。注意文档特别指出更新tools/metrics/histograms/enums.xml这一步是不需要的。对 ungoogled-chromium 的新开关需要先在 Chromium 源码树的third_party/ungoogled/ungoogled_switches.cc中新增常量——该文件本身是补丁创建出来的因此实际上是通过修改对应的补丁来实现文档中给出的补丁路径为resources/patches/ungoogled-chromium/add-third-party-ungoogled.patch。之后在步骤中引用这个常量即可。这里需要注意一个版本沿革问题resources/patches/是仓库早期的目录布局当前仓库中补丁已经重组为 patches/core/ 与 patches/extra/ 两级结构并通过 patches/series 统一排序。例如patches/core/ungoogled-chromium/下已有disable-gaia.patch、disable-gcm.patch、toggle-translation-via-switch.patch等成型的开关类补丁可以作为新增开关时参考补丁写法与 series 插入位置的范本。add-third-party-ungoogled补丁在当前 series 中已不单独存在说明其内容已并入现有补丁集新增开关时应直接对照 patches/core/ungoogled-chromium/ 下现有补丁的实际改动面来操作并以devutils/validate_patches.py的干净应用校验为准。升级 Chromium 版本环境与依赖文档说明该流程在Debian 12 (bookworm)上经过验证其他 Linux 或 macOS 系统装好依赖后同样适用。依赖项依赖说明quilt大多数 Linux 发行版与 macOS Homebrew 均有提供。它是整个更新流程的核心工具建议先读 Debian 官方的 Quilt 使用指南文档中引用了 Debian Wiki 的《UsingQuilt》及其链出的使用教程Python 3.10如果选择源码克隆而非源码压缩包方式获取源码还需要httplib2与sixhttplib2v0.30.0 及以上版本另需pysocks获取 Chromium 源码文档提供两条路径二选一。方式一源码压缩包推荐mkdir -p build/download_cache ./utils/downloads.py retrieve -i downloads.ini -c build/download_cache ./utils/downloads.py unpack -i downloads.ini -c build/download_cache build/src这三条命令对应 utils/downloads.py 的retrieve与unpack两个子命令结合 downloads.ini 可以还原其完整行为[chromium] url https://commondatastorage.googleapis.com/chromium-browser-official/chromium-%(_chromium_version)s-lite.tar.xz download_filename chromium-%(_chromium_version)s-lite.tar.xz hash_url chromium|chromium-%(_chromium_version)s-lite.tar.xz.hashes|https://commondatastorage.googleapis.com/chromium-browser-official/chromium-%(_chromium_version)s-lite.tar.xz.hashes output_path ./ strip_leading_dirs chromium-%(_chromium_version)s%(_chromium_version)s这类以下划线开头的变量由utils/_common.py的get_chromium_version()从 chromium_version.txt 注入即下载 URL 与chromium_version.txt中的版本严格绑定——升级版本时改的就是这个文件。retrieve见 utils/downloads.py优先使用系统curl支持-C -断点续传无curl时回落到 Python 的urllib下载完成后会先拉取hash_url指向的官方哈希清单再逐项校验哈希校验失败直接以错误码退出。unpack按extractor选择解包器tar / 7-Zip / WinRARstrip_leading_dirs会把压缩包内chromium-153.0.8010.52/这一顶层目录剥掉因此源码最终落在build/src。方式二源码克隆./utils/clone.py -o build/srcutils/clone.py 是文档依赖表里httplib2/six/pysocks需求的来源其clone()函数见 utils/clone.py实际完成了一整套“对齐官方 tarball”的准备以git clone -b chromium_version --depth2克隆https://chromium.googlesource.com/chromium/src深度为 2 是因为生成LASTCHANGE、gpu_lists_version.h至少需要两个提交。从DEPS文件解析并检出depot_tools与gn的指定 commit并打上仓库自带的 utils/depot_tools.patch 与 utils/gsutil.patch。用内置的 gclient 配置checkout_configuration small、target_os [unix]、target_cpu [x64]见 utils/clone.py执行gclient sync -f -D -R --no-history --nohooks。下载 PGO 优化配置、生成DAWN_VERSION/LASTCHANGE/gpu_lists_version.h/skia_commit_hash.h/last_commit_position.h等 tarball 中本应预生成的文件。可用选项包括-o/--output输出目录默认chromium、-c/--custom-config替换默认 gclient 配置、-p/--pgo选择 PGO 配置linux/mac/mac-arm/win32/win64/win-arm64默认linux、-s/--sysroot为指定 Linux 架构下载 sysroot、--dt-commit手动指定 depot_tools commit。更新剪枝与域名替换列表拿到干净的源码树后第一步是更新文件清单./devutils/update_lists.py -t build/src该工具默认更新本地仓库中的清单文件-h/--help可查看全部选项。从 devutils/update_lists.py 的源码看其判定逻辑为剪枝判定should_prune先匹配PRUNING_INCLUDE_PATTERNS强制剪枝如components/domain_reliability/baked_in_configs/*与 safe_browsing 偏好文件与PRUNING_EXCLUDE_PATTERNS豁免如*.png、*.ttf、third_party/icu/common/icudtl.dat、capture_context_win_arm64.obj等再对候选文件做二进制内容检测基于文本字符集的translate判断见 devutils/update_lists.py。域名替换判定should_domain_substitute先按DOMAIN_EXCLUDE_PREFIXES如components/test/、tools/gn/排除前缀跳过LICENSE*文件再按DOMAIN_INCLUDE_PATTERNS覆盖*.cc、*.h、*.json、*.js、*.gn等源码类型匹配最后用 domain_regex.list 编译出的合并正则在文件内容中实际搜一遍确认确实含相关域名才入列。全程使用multiprocessing.Pool并行遍历--processes可调默认为 CPU 核数并跟踪“未被任何文件命中的 include/exclude 模式”——存在未用模式时默认报错退出--no-error-unused可降级为警告这保证了清单模式不会随版本演进而腐化。输出即覆盖仓库根的 pruning.list 与 domain_substitution.list。文档特别强调运行完此命令后build/src中的源码树既没有被剪枝也没有被域名替换——它是后续 Quilt 刷新补丁所需的“原始”状态。domain_regex.list的条目格式为搜索正则#替换表达式#为分隔符例如google([A-Za-z\-]*?\\*?)\.com(?!mon)#9oo91e\g1.qjz9zk所有替换表达式必须以qjz9zk结尾且搜索/替换双方必须一一对应无两条搜索正则匹配同一字符串无两条替换结果相同——这条约束在 utils/domain_substitution.py 的DomainRegexList中直接体现为按#拆分的regex_pairs。用 Quilt 更新补丁核心步骤IMPORTANT更新补丁前务必确认源码树尚未应用域名替换。整个流程引自 docs/developing.md运行source devutils/set_quilt_vars.shfish 用户用source devutils/set_quilt_vars.fish把 quilt 配置为直接修改仓库内的 patches/ 目录。进入源码树cd build/src刷新全部补丁quilt push -a --refresh若出错进入下一步否则跳到第 5 步。修复损坏的补丁quilt push -f强制应用生成 reject 文件按需要修改损坏的文件新增用quilt edit ...或quilt add ...移除用quilt remove ...。技巧删除大段代码时逐行删除而不要用语言特性注释块、#if 0等隐藏代码。这样 quilt 的refresh按上下文更新行号时块中间新增的“希望保留”的代码不会被意外排除同时也让他人仅凭补丁 diff 就能看清改动。quilt refresh重新生成补丁回到第 3 步直到quilt push -a --refresh全程无错。quilt pop -a弹出所有补丁。回到仓库根cd ../..运行devutils/validate_config.py有告警先处理否则继续。运行devutils/validate_patches.py -l build/src若仍报错回到第 3 步。完成后 git 仓库中会留下未暂存的改动review、add并提交即可。其中几个环节值得展开set_quilt_vars.sh到底设置了什么见 devutils/set_quilt_vars.shalias quiltquilt --quiltrc - export QUILT_PATCHES$REPO_ROOT/patches export QUILT_PUSH_ARGS--colorauto export QUILT_DIFF_OPTS--show-c-function export QUILT_PATCH_OPTS--unified --reject-formatunified export QUILT_DIFF_ARGS-p ab --no-timestamps --no-index --colorauto --sort export QUILT_REFRESH_ARGS-p ab --no-timestamps --no-index --sort --strip-trailing-whitespace export LC_ALLC脚本注释解释了quilt --quiltrc -的由来QUILT_PATCHES/QUILT_SERIES使用绝对路径会导致 quilt 的refresh/diff行为异常而显式指定quiltrc可规避该问题代价是丢失/etc/quilt.quiltrc的默认设置因此脚本在下方重新定义了这些参数。-p ab意味着 diff 使用带a/、b/前缀的路径——这正是 docs/design.md 中“推荐 hunk 路径带a/、b/前缀”的落地方式。validate_config.py检查什么见 devutils/validate_config.py所有补丁文件存在、所有补丁被 series 引用、每个补丁只被引用一次、flags.gn中的 GN 参数已排序且无重复、downloads.ini符合其 schema。退出码 0 表示无问题1 表示存在告警或错误。validate_patches.py -l build/src做什么见 devutils/validate_patches.py验证所有补丁能干净地应用到源码树上-l指向本地源码树本地缺失的文件才会尝试从 Google 的仓库远程获取且对DEPS文件做了语法白名单校验。它与devutils/check_patch_files.py共同构成合入前“补丁必须无 fuzz”这一硬性约束的自动化检查。域名替换已应用后如何修补丁构建失败后回到源码树修补丁时有一个分叉条件如果域名替换尚未应用直接按上一节的流程即可。IMPORTANT如果域名替换已经应用典型场景构建失败发生在替换之后不能直接刷新补丁——否则生成的补丁会依赖替换后的域名脱离替换环境就无法应用。文档给出的处理顺序是借助替换缓存回滚域名替换./utils/domain_substitution.py revert -c CACHE_PATH_HERE build/src按上一节的流程更新补丁。重新应用域名替换./utils/domain_substitution.py apply -r domain_regex.list -f domain_substitution.list -c CACHE_PATH_HERE build/src重新构建必要时重复以上步骤。这个“revert 依赖缓存”的机制在 utils/domain_substitution.py 中实现apply会同时生成一个域名替换缓存内部保存每个被改文件的原始内容与 CRC32 索引revert仅依据该缓存恢复——它会校验源码树文件哈希与索引一致再把原始文件覆盖回去成功后删除缓存缓存中仍有未被使用的文件时会保留缓存并给出警告见 utils/domain_substitution.py。因此CACHE_PATH_HERE必须是当初apply时使用的同一缓存文件。后续步骤补丁集更新完成、校验通过后向 ungoogled-chromium 仓库提交包含这些改动的 Pull Request按分支模型一节应走特性分支。PR 合并后更新你在ungoogled-software组织下维护的各平台打包仓库packaging 仓库使用本仓库代码执行“下载解包 → 剪枝 → 打补丁 → 域名替换 → GN/ninja 构建 → 打包”的完整流程见 docs/design.md 的 Packaging 一节。完整流程速查表步骤命令/操作关键脚本获取源码压缩包./utils/downloads.py retrieve -i downloads.ini -c build/download_cache./utils/downloads.py unpack ... build/srcutils/downloads.py获取源码克隆./utils/clone.py -o build/srcutils/clone.py更新清单./devutils/update_lists.py -t build/srcdevutils/update_lists.py配置 quiltsource devutils/set_quilt_vars.shdevutils/set_quilt_vars.sh刷新补丁cd build/src quilt push -a --refresh出错则push -f→ 编辑 →refresh循环—弹出补丁quilt pop -a cd ../..—校验配置devutils/validate_config.pydevutils/validate_config.py校验补丁devutils/validate_patches.py -l build/srcdevutils/validate_patches.py回滚/重放域名替换./utils/domain_substitution.py revert/apply ...utils/domain_substitution.py提交特性分支 → PR → 更新平台打包仓库—整套流程的设计意图可以概括为用chromium_version.txt锁定版本用两份自动生成的清单声明“哪些文件要动”用 Quilt 管理的补丁集承载所有代码改动用两套 validate 脚本保证补丁永远能干净地重新应用——这使得 ungoogled-chromium 能在 Chromium 高频迭代的背景下以纯补丁集的方式持续跟进上游。【免费下载链接】ungoogled-chromiumGoogle Chromium, sans integration with Google项目地址: https://gitcode.com/gh_mirrors/un/ungoogled-chromium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
