如何为 uBOLite 将过滤列表转换为声明式 ruleset？-开发者社区

如何为 uBOLite 将过滤列表转换为声明式 ruleset？

【免费下载链接】uBlockuBlock Origin - An efficient blocker for Chromium and Firefox. Fast and lean.项目地址: https://gitcode.com/GitHub_Trending/ub/uBlock

uBlock Origin 仓库中包含一个 MV3 分支产品 uBOLite：它不再在运行时动态解析过滤规则，而是把文本形式的过滤列表预先转换成浏览器的 declarative ruleset。要完成这条转换链，你在 Linux 环境下按仓库的构建流程跑一次构建即可——tools/make-mv3.sh会调用 Node.js 脚本 make-rulesets.js，逐个拉取并转换 rulesets.json 中声明的过滤列表，最终产出rulesets/目录下的 DNR 规则文件和打过补丁的manifest.json。本文基于 platform/mv3/README.md 和构建脚本正文，说明这条路径的前提、执行方式和如何核对产物。

前提条件

构建说明明确要求 Linux 环境，且对 Node.js 版本有下限要求：

platform/mv3/README.md 写明该 Nodejs 脚本要求 Node 版本为17.5.0 或以上；platform/mv3/package.json 中的engines.node同样声明"node": ">=17.5.0"。
构建会从远程服务器下载过滤列表，需要网络访问。
仓库包含子模块，README 给出的准备步骤是：

git submodule init git submodule update

哪些过滤列表参与转换

转换的输入清单是 platform/mv3/rulesets.json，每个条目描述一个列表集，字段包括id、name、group、enabled、urls（列表下载地址）、homeURL，以及可选的lang、tags、trusted、parent和excludedPlatforms。例如默认启用的条目有ublock-filters（指向 uAssets 仓库的quick-fixes.min.txt、unbreak.min.txt、filters.min.txt、privacy.min.txt、ubol-filters.txt五个文件）、easylist、easyprivacy、pgl、ublock-badware、urlhaus-full。

脚本主循环中的过滤逻辑值得注意：

for ( const ruleset of rulesets ) { if ( ruleset.excludedPlatforms?.includes(platform) ) { continue; } await rulesetFromURLs(ruleset); }

即条目excludedPlatforms中包含当前构建平台时会被整体跳过。rulesets.json中pgl、ublock-badware、urlhaus-full、adguard-spyware-url、pol-3均声明了"excludedPlatforms": [ "safari" ]，所以make mv3-safari不会为这些列表生成 ruleset。

执行转换

在仓库根目录执行（[platform]取chromium、edge、firefox或safari）：

make mv3-chromium

其他平台对应make mv3-edge、make mv3-firefox、make mv3-safari。Makefile 中这些目标依赖ubol-codemirror（先构建 codemirror-ubol 打包产物）和dist/build/mv3-data，然后实际执行的是tools/make-mv3.sh <platform>。

make mv3-*属于增量重建目标：脚本开头会rm -rf掉已有的dist/build/uBOLite.$PLATFORM目录再重建，所以重复执行会删除并覆盖上一次的扩展产物。它内部做三件事（见 tools/make-mv3.sh）：

把 uBlock 主分支与 MV3 目录的文件复制到dist/build/uBOLite.$PLATFORM组装扩展骨架；
搭建一个临时构建目录，运行：

node --no-warnings make-rulesets.js output="$UBOL_DIR" platform="$PLATFORM"

按平台收尾：edge会把rulesets/main/*移到包根目录（注释说明 “For Edge, declared rulesets must be at package root”）并运行platform/mv3/edge/patch-extension.js；safari运行platform/mv3/safari/patch-extension.js做合规修补。

在转换脚本内部，每个列表集的文本（本地缓存缺失时从urls远程拉取，成功后写入缓存目录${output}/../mv3-data，即dist/build/mv3-data）经dnrRulesetFromRawLists解析为 DNR 规则，再按类型拆分落盘；同时生成一个 16 位十六进制secret（存于mv3-data/secret.txt，首次生成后复用），用于给内置过滤片段插入!#trusted on <secret>签名。

核对产物

构建完成后，按 README 的说明逐项检查：

扩展包位置：dist/build/uBOLite.chromium（或.edge/.firefox/.safari）。
ruleset 文件：全部位于dist/build/uBOLite.[platform]/rulesets下，脚本写出的文件包括：
- main/<id>.json——每个列表集一个静态规则集，其中每条规则带递增的id，例如main/ublock-filters.json；
- regex/<id>.json——仅当该列表集存在正则规则时才生成；
- strictblock/<id>.json、urlskip/<id>.json、scripting/下的 cosmetic/scriptlet 产物——均为条件生成，非空才写出；
- ruleset-details.json（每个列表集的过滤/规则统计）、scriptlet-details.json、generic-details.json。
manifest 已打补丁：脚本会写回manifest.json，新增declarative_net_request.rule_resources（每个列表集一项，path形如/rulesets/main/<id>.json，携带id与enabled），并追加重定向资源所需的web_accessible_resources条目，同时把version更新为本次构建的时间戳版本号。
构建日志：dist/build/uBOLite.[platform]/log.txt记录构建过程中发生了什么，README 明确将其作为排查构建过程的依据；每个列表集的处理中会记录输入过滤条数、接受/拒绝条数和输出规则条数。

可选分支与限制

强制刷新过滤列表：dist/build/mv3-data缓存了从远程拉取的数据，重复构建不会重复下载。需要最新列表时执行make cleanassets，其 Makefile 定义为rm -rf dist/build/mv3-data dist/build/uAssets，即删除全部本地缓存的过滤列表，下次构建会重新拉取。
本地调试构建：不带版本号参数的构建（即上面make mv3-*走的路径）会向manifest.json增加declarativeNetRequestFeedback权限（脚本注释标明用于 DNR 规则调试）；Firefox 平台还会把扩展 ID 改为uBOLite.dev@raymondhill.net以区别于正式版。
发布构建：直接向脚本传full或形如x.y.z的版本号（如tools/make-mv3.sh full）会打包出uBOLite_<TAGNAME>.<platform>.zip（Firefox 为.xpi）并放到dist/build/；同时会删除rulesets/debug目录。
缩小更新差异：tools/make-mv3.sh支持before=<dir>参数，构建后调用 salvage-ruleids.mjs，对比 before/after 两包中main、modify-headers、redirect、regex、removeparam各子目录的规则文件，保留未变化规则的id以缩小 diff 尺寸。
平台差异：excludedPlatforms决定某些列表只在部分平台生成 ruleset（见前文）；Edge 的声明式 ruleset 必须位于包根目录，Safari 需要额外的合规修补步骤，两者由构建脚本自动处理。