uBlock Origin 源码仓库深度解析：从安装矩阵、默认过滤清单到静态网络过滤引擎与构建体系

本文以 uBlock Origin（uBO）仓库根目录的 README.md 为主体骨架，完整梳理其项目定位、多浏览器安装矩阵、默认过滤清单构成与扩展过滤语法，并结合仓库源码（如 src/js/static-net-filtering.js、src/js/hntrie.js、Makefile）与构建脚本，深入讲解其“CPU 与内存高效”承诺背后的核心引擎实现，以及 MV2/MV3、npm 核心包等多种产物的构建与发布流程，读完后可对 uBO 的整体架构与二次开发方式形成完整认知。

一、项目定位：一个 CPU 与内存高效的宽谱内容拦截器

README.md 对项目的核心定义是：uBlock Origin（uBO）是一个面向 Chromium 与 Firefox 的 CPU 和内存高效的宽谱内容拦截器（wide-spectrum content blocker），默认拦截广告、追踪器、加密货币矿机、弹窗、反拦截干扰脚本、恶意网站等。它使用 EasyList 的过滤语法，并在此基础上扩展该语法以支持自定义规则和过滤项。

README 中同时明确了两点价值立场（详见 MANIFESTO.md）：

• 使用拦截器不是“窃取”内容；
• uBO 的首要目标是帮助用户中和这些侵犯隐私的手段，并且对不愿使用更技术性手段的用户保持友好。

MANIFESTO.md 进一步将这一立场浓缩为一句话：“用户自己决定浏览器中哪些网络内容是可接受的”，并明确 uBO 项目不支持 Adblock Plus 的 “Acceptable Ads” 理念，认为该营销方案背后是营利机构的商业计划。项目采用 GPLv3 许可证（见 LICENSE.txt），完全免费、开源、不寻求任何捐赠。

二、安装渠道与平台兼容性矩阵

README 首页的核心内容是一张浏览器安装矩阵。结合仓库中的 platform/ 目录结构（platform/chromium/、platform/firefox/、platform/thunderbird/、platform/opera/、platform/safari/、platform/mv3/），可以把官方支持的各平台及其状态归纳如下：

浏览器	官方渠道	README 中的状态说明
Firefox	Firefox Add-ons	uBO 在 Firefox 上表现最佳，同时提供桌面版与 Android 版
Microsoft Edge	Edge Add-ons	Edge 正从 MV2 向 MV3 迁移：2026 年 8 月开始消费者端迁移，目标 2026 年底完成，企业端 2027 年初跟进
Opera	Opera Add-ons	常规支持（对应 platform/opera/manifest.json）
Chromium	Chrome Web Store	MV2 扩展将在 2026-08-31 从 Chrome Web Store 移除（见仓库中 platform/mv3/ 的 MV3 替代方案）
Thunderbird	Thunderbird Add-ons	商店版本已停止更新（停留在 1.49.2），后续版本需从 GitHub Releases 手动安装
全部	GitHub Releases	Firefox、Chromium MV2 与 Thunderbird 的稳定版和开发版，需手动安装，Chromium 与 Thunderbird 版本通常不会自动更新

矩阵之外还有一行“Related”：基于 MV3 构建的简化版本 uBlock Origin Lite（uBOL），其源码就位于本仓库的 platform/mv3/ 目录（见下文构建章节）。

2.1 各平台的安装要点

• Firefox：README 指出 uBO “works best” 于 Firefox，提供桌面版和 Android 版，另有开发版构建可用。
• Chromium：Chrome Web Store 版本（MV2）标注了 2026-08-31 的移除时间点；Edge 商店版本在 1.62 版本前由第三方代理发布，1.64 版本起完成所有权转移；Opera 走 Opera Add-ons。uBO 应当兼容任意 Chromium 内核浏览器。
• Thunderbird：README 特别强调：在 Thunderbird 中 uBO 不影响邮件内容，只作用于信息源（feeds）——这是一个容易误解的重要边界。
• 通用约束：README 明确要求不要将 uBO 与其他内容拦截器同时使用。uBO 的性能已达到或优于大多数主流拦截器，而其他拦截器可能妨碍 uBO 的隐私保护和反拦截器（anti-blocker）防御特性正常工作。
• 企业部署：README 单列了 “Enterprise Deployment” 小节指向部署文档（README 中以 wiki 外链形式给出，本仓库内对应的是 src/_locales/ 下的多语言资源与各平台 manifest）。

2.2 文档模式：Basic Mode 与 Advanced Mode

README 的 Documentation 小节将用户界面划分为两种模式：

• Basic Mode（基础模式）：简洁的弹窗用户界面，属于“装完即忘”（install-it-and-forget-it）型安装，默认配置即为最优；
• Advanced Mode（高级模式）：高级弹窗用户界面，包含一个可按站点配置的点选式防火墙（point-and-click firewall），可对每个站点逐类开关请求类别。

这个“按站点防火墙”在源码中有直接对应：src/js/ublock.js 实现了基于会话/持久化两级存储的防火墙开关（sessionSwitches/permanentSwitches、sessionFirewall/permanentFirewall，来自 src/js/filtering-engines.js），并通过 matchDirective() 将白名单指令（纯主机名、通配符、正则）逐级匹配到父级域名——例如 www.example.org 会依次尝试 example.org 等父域，这正是高级模式“per-site 配置”的底层机制。

三、默认过滤清单与过滤数据体系

README 说明 uBO 默认使用以下过滤清单：EasyList、EasyPrivacy、Peter Lowe's Blocklist、Online Malicious URL Blocklist，以及 uBO 自有的 uBO filters；此外还支持其他清单与 Hosts 文件，并且用户可以随时取消勾选任何预选项（README 还对比了 Adblock Plus 默认只启用 EasyList + ABP filters + Acceptable Ads）。

仓库内 assets/assets.json（共 970 行）就是这套过滤清单的声明式配置源，它精确回答了“uBO 到底从哪些源、以何种策略拉取过滤数据”。从中可以确认：

1. 清单条目结构：每个清单条目包含 content（内容类型，如 filters/internal）、group/parent/title/tags（用于界面分组展示）、contentURL（按优先级排列的原始拉取地址列表）、cdnURLs（多个 CDN 镜像源，含 GitHub Pages、Cloudflare Pages、jsDelivr 三个 CDN）、patchURLs（增量补丁目录，支持差量更新）等字段。
2. uBO 自有清单分组：ublock-filters（Ads，group: "default"，即默认勾选）、ublock-badware（Badware risks，标签 malware security）、ublock-privacy（Privacy）等，均挂在 parent: "uBlock filters" 之下——这与界面里“uBlock filters”这一父组展开出 Ads/Privacy/Badware 等子项的呈现方式一致。
3. 内置数据与更新周期：assets.json 自身 updateAfter: 13（天），public_suffix_list.dat（公共后缀列表，用于正确解析域名层级）updateAfter: 19，ublock-badlists updateAfter: 29。contentURL 数组的第二个元素是 assets/ublock/*.txt 形式的仓库本地兜底路径（如 assets/ublock/filters.min.txt），意味着清单在远程不可达时仍有本地静态副本。
4. 构建期预拉取：Makefile 中的 dist/build/uAssets 目标由 tools/pull-assets.sh 实现，构建时预下载过滤清单；开发态的 assets/assets.dev.json 则是开发环境的对应配置。

3.1 扩展过滤语法在源码中的形态

README 提到 uBO “使用 EasyList 过滤语法并扩展它”。扩展能力的实现集中在 src/js/static-filtering-parser.js，从其中的类结构可以看到解析器的完整抽象：preparser（预处理，展开 ##% 前置条件如 env_brave 等环境 token）、AstFilterParser（过滤规则 AST 解析）、ExtSelectorCompiler（扩展 CSS 选择器编译）、DomainListIterator（域名列表迭代）。而 src/js/static-net-filtering.js 中上百个 Filter* 类（FilterHostnameDict、FilterBucket、FilterRegex、FilterOnHeaders、FilterMessage、FilterCompiler 等）正是各类过滤项编译后的运行时形态——静态网络过滤引擎会依据规则特征为每条过滤规则选择成本最低的匹配器类型（纯主机名用字典/Trie、精确 URL 用哈希桶、正则用单独桶），这是其“高效匹配”承诺的关键。

仓库中还保留了针对静态过滤解析器的测试页面 docs/tests/static-filtering-parser-checklist.txt 与 docs/tests/hntrie-test.html、docs/tests/hnset-benchmark.html 等基准测试页面，可用来验证解析器与主机名 Trie 的正确性和性能表现。

四、核心过滤引擎的源码结构

从 src/js/ 目录的模块划分（结合 src/js/ 顶层定义清单）可以勾勒出 uBO 的引擎分层：

• 静态网络过滤（SNFE）：src/js/static-net-filtering.js + src/js/static-net-filtering-parser 对应逻辑，负责解析并执行过滤清单；src/js/static-filtering-io.js 中的 CompiledListWriter/CompiledListReader 实现编译后清单的序列化读写，src/js/static-ext-filtering-db.js 中的 StaticExtFilteringHostnameDB 提供扩展存储中的主机名数据库。
• 主机名 Trie：src/js/hntrie.js（HNTrieContainer）与 src/js/hnswitches.js（DynamicSwitchRuleFiltering）。这是 uBO 的标志性数据结构：一种为纯主机名集合高度优化的压缩 Trie，标签从右向左匹配（www.example.org 能命中 example.org，而 anotherexample.org 不会），在 CPU 与内存效率上是核心关切，也是 uBO 相比逐条正则扫描式方案的性能基础。
• 动态网络过滤：src/js/dynamic-net-filtering.js（DynamicHostRuleFiltering、DynamicURLRuleFiltering），实现高级模式下的点选防火墙与“拒绝/放行某类请求”的动态规则。
• 外观过滤（Cosmetic filtering）：src/js/cosmetic-filtering.js 与 src/js/contentscript-extra.js 中大量的 PSelector*Task 类，支撑 uBO 自有的过程式选择器（procedural selector）语法（如 xpath、text、upward 等操作符），对应测试页面 docs/tests/procedural-cosmetic-filters.html 与 docs/tests/css-selector-based-cosmetic-filters.html。
• 脚本注入（Scriptlets）：src/js/scriptlet-filtering-core.js 与 src/js/scriptlets/ 目录（17 个脚本let实现，如 prevent-xhr、json-edit、cookie、set-constant 等），配合重定向引擎 src/js/redirect-engine.js 将匹配请求替换为 src/web_accessible_resources/ 中的 noop/shim 资源（noop.js、googletagmanager_gtm.js 等）——这是 README 中“defusing anti-blockers”（反拦截器拆解）特性的直接实现。
• 防火墙开关与白名单：如前所述，位于 src/js/ublock.js（703 行，含 matchDirective/matchBucket 等核心函数）与 src/js/whitelist.js。

src/js/wasm/ 目录则包含部分热点路径的 WASM 实现（如主机名匹配相关的 .wasm/.wat 文件），src/lib/ 中内置了 lz4 压缩、punycode、csstree、公共后缀列表等第三方库，保证扩展无运行时外部依赖。

五、构建与发布体系：Makefile 驱动的多平台产物

仓库的 Makefile 是理解整个交付链路的钥匙。其主要目标与对应脚本如下：

Make 目标	产物	实现脚本
chromium	dist/build/uBlock0.chromium	tools/make-chromium.sh
firefox	dist/build/uBlock0.firefox	tools/make-firefox.sh
opera	dist/build/uBlock0.opera	tools/make-opera.sh
npm	dist/build/uBlock0.npm（即 @gorhill/ubo-core 包）	tools/make-npm.sh
mv3-chromium / mv3-firefox / mv3-edge / mv3-safari	dist/build/uBOLite.[platform]	tools/make-mv3.sh
lint	ESLint 检查	npm run lint（eslint.config.mjs）
clean / cleanassets	清理构建产物 / 缓存的过滤清单	—

以 tools/make-chromium.sh 为例，Chromium 包的标准构建流程为：

1. 清空并创建 dist/build/uBlock0.chromium；
2. 执行 tools/copy-common-files.sh 复制公共文件（src/ 下的 JS/CSS/HTML 与本地化资源）；
3. 复制 platform/chromium/ 下的平台专属 JS/HTML/JSON（如 platform/chromium/manifest.json、platform/chromium/webext.js）；
4. 将 nb 语言目录复制为 no（Chrome 商店要求 Norwegian 代码为 no）；
5. 运行 tools/make-chromium-meta.py 生成元数据（版本、权限描述等）；
6. 按需打包为 uBlock0.chromium.zip（无参数）或 uBlock0_<version>.chromium.zip（带版本号）。

5.1 MV3 版本（uBlock Origin Lite）的构建

platform/mv3/README.md 给出了 MV3 版本的完整构建说明（面向 Linux 环境）：

1. git clone 仓库后执行 git submodule init 与 git submodule update；
2. 运行 make mv3-[platform]，其中 [platform] 为 chromium、edge、firefox 或 safari；
3. 构建过程中会自动从远程服务器下载过滤清单；
4. 产物位于 dist/build/uBOLite.chromium、dist/build/uBOLite.edge、dist/build/uBOLite.firefox、dist/build/uBOLite.safari；
5. dist/build/mv3-data 缓存远程数据以避免重复拉取，可用 make cleanassets 清除缓存后以最新清单重新构建；
6. 构建日志写入 dist/build/uBOLite.[platform]/log.txt。

值得注意的是，tools/make-mv3.sh 会调用一个 Node.js 脚本把过滤清单转换为 MV3 声明式规则集（rulesets），所有规则集最终打包进 dist/build/uBOLite.[platform]/rulesets——这是 uBOL 与 uBO 在过滤机制上的根本差异：MV3 的 declarativeNetRequest 无法在运行时解析完整过滤语法，因此需要预编译。MV3 扩展的清单见 platform/mv3/chromium/manifest.json，规则集定义在 platform/mv3/rulesets.json。

5.2 发布流程

Makefile 中还有完整的发布目标（均要求传入 version= 参数）：publish-chromium、publish-edge、publish-firefox、publish-dev-chromium、publish-dev-firefox、upload-firefox 等，分别调用 publish-extension/ 下的 publish-chromium.js、publish-edge.js、publish-firefox.js、upload-firefox.js，并携带商店 ID（如 Chrome 商店 ID cjpalhdlnbpafiamejdnhcphjbkeiagm、Edge 商店 ID odfafepnkmbhccpbejgmiehpchacaeak、AMO 扩展 ID [e-mail]）。Chromium 正式发布还涉及 CRX 更新源（crxupdatepath=dist/chromium/update.xml），对应 README 中“GitHub Releases 版本通常不会自动更新”的说明。

六、npm 核心包：@gorhill/ubo-core

README 徽章与 platform/npm/ 目录共同指向一个事实：uBO 的核心过滤引擎已抽取为独立 npm 包 @gorhill/ubo-core（当前版本 0.1.30，要求 Node >= 18），描述为“用于创建 uBlock Origin 静态网络过滤引擎（SNFE）工作实例”，且无外部依赖。platform/npm/README.md 给出了完整的 API 用法，这里完整保留其关键代码示例：

创建引擎实例并注入过滤清单（useLists() 接受 { name, raw } 对象数组）：

import { StaticNetFilteringEngine } from '@gorhill/ubo-core';

const snfe = await StaticNetFilteringEngine.create();

await snfe.useLists([
    fetch('easylist').then(r => r.text()).then(raw => ({ name: 'easylist', raw })),
    fetch('easyprivacy').then(r => r.text()).then(raw => ({ name: 'easyprivacy', raw })),
]);

匹配网络请求（返回非 0 即被拦截）：

// Blocked
if ( snfe.matchRequest({
    originURL: 'https://www.bloomberg.com/',
    url: 'https://securepubads.g.doubleclick.net/tag/js/gpt.js',
    type: 'script'
}) !== 0 ) {
    console.log(snfe.toLogData());
}

序列化与快速反序列化（跳过解析与编译阶段）：

const serializedData = await snfe.serialize();
// ...
const snfe = await StaticNetFilteringEngine.create();
await snfe.deserialize(serializedData);

该包还支持直接馈送纯域名列表或 hosts 文件格式的清单（Block List Project、Steven Black's HOSTS 等）。此外 platform/npm/README.md 单独介绍了底层组件 HNTrieContainer（对应 src/js/hntrie.js）：

import HNTrieContainer from '@gorhill/ubo-core/js/hntrie.js';

const trieContainer = new HNTrieContainer();
const aTrie = trieContainer.createOne();
trieContainer.add(aTrie, 'example.org');
trieContainer.add(aTrie, 'example.com');

// 从右向左按标签匹配：
// 'www.example.org' -> 返回 4（命中）
// 'www.foo.invalid' -> 返回 -1（未命中）
console.log(trieContainer.matches(aTrie, 'www.example.org'));

注意事项：matches() 返回匹配起始位置或 -1；reset() 会移除容器中所有 trie，之后旧的 trie 引用不再有效。仓库内 platform/npm/demo.js 与 platform/npm/tests/（含 wasm.js、leaks.js、snfe.js 等测试）可用于验证上述 API 行为。

七、开发环境、代码质量与本地化

• 开发依赖：根 package.json（"name": "uBlock"，type: module）要求 Node >= 22、npm >= 11，唯一的开发依赖是 ESLint 9（含 @eslint/json 用于校验 JSON 文件）。npm run lint 会检查 ./src/js/、./**/*.json 与 ./platform/**/*.js，并忽略 lib/ 与 npm/ 子目录（规则见 eslint.config.mjs）。仓库未配置独立单测目标（test 脚本仅为占位），质量保障主要依赖 lint 与 docs/tests/ 下的浏览器端测试页面。
• 多语言：src/_locales/ 下包含 71 种语言的 messages.json（en、zh_CN、zh_TW、ja、ru、fr 等），README 的 “Translations” 小节引导通过 Crowdin 参与翻译；tools/import-crowdin.sh 负责将翻译导入仓库。
• 版本记录：发布历史在 CHANGELOG.md（当前仓库记录覆盖 1.71.0–1.73.x 等近期版本，例如 1.73.0 改进了 proxy-apply、abort-current-script 等 scriptlet 并新增 piano-analytics.js shim），与 README “Release History” 小节呼应。

八、关键仓库路径速查

内容	路径
项目说明（本文主体文档）	README.md
项目宣言（用户主权与隐私立场）	MANIFESTO.md
GPLv3 许可证	LICENSE.txt
过滤清单声明式配置	assets/assets.json
静态网络过滤引擎	src/js/static-net-filtering.js
过滤语法解析器	src/js/static-filtering-parser.js
主机名压缩 Trie	src/js/hntrie.js
防火墙开关/白名单匹配	src/js/ublock.js
过程式外观过滤选择器	src/js/contentscript-extra.js
Scriptlet 集合	src/js/scriptlets/
构建入口	Makefile、tools/
MV3（uBOL）构建说明	platform/mv3/README.md
npm 核心包	platform/npm/README.md、platform/npm/package.json
版本记录	CHANGELOG.md
解析器/Trie 测试页面	docs/tests/

小结：README 所描述的“高效宽谱拦截器”在仓库中逐层落地——assets.json 声明式管理过滤数据源与 CDN 冗余，hntrie + static-net-filtering 提供面向主机名大集合的最低成本匹配，动态防火墙与 scriptlet/shim 体系覆盖运行时干预，而 Makefile 则以单一代码树产出 Firefox/Chromium/Opera MV2 扩展、四个平台的 uBOL MV3 扩展以及 @gorhill/ubo-core npm 包五类产物。