uBlock Origin 安装与构建完全指南：Chromium/Firefox 手动加载与源码级本地编译

2026-09-03 15:30:03作者：胡易黎Nicole

本文基于仓库中的安装文档 dist/README.md 展开，覆盖 uBlock Origin（下文简称 uBO）在 Chromium 系浏览器和 Firefox 中的手动安装全流程、配置文件的存储位置与备份机制，以及面向开发者的本地构建命令（make chromium / make firefox / make npm）。读完本文，你将能够：在无商店渠道的情况下正确部署并更新 uBO、安全地备份/迁移自己的过滤配置，并从源码仓库编译出与官方发布一致的扩展包。

Chromium：解压、重命名、加载未打包扩展

官方文档给出的 Chromium 侧手动安装流程如下，每一步都对应扩展加载机制的一个硬性要求：

下载并解压 ublock0.chromium.zip（建议取最新 release 版本）。
将解压出的目录重命名为 ublock。
- 手动更新时，用最新版 zip 中的内容替换 ublock 文件夹里的内容，这样才能保留全部扩展设置；
- 只要扩展仍然从最初安装时的同一目录路径加载，设置就会一直保留。
打开 Chromium/Chrome，进入 Extensions（扩展）页面。
开启 Developer mode（开发者模式）。
点击 Load unpacked extension…（加载已解压的扩展）。
在文件选择对话框中选中你创建的 ublock 目录，点击 Open。

完成后扩展即可在 Chromium/Chromium 系浏览器中使用。

为什么必须手动更新，以及这样做的收益

从源码构建流程看（tools/make-chromium.sh），构建脚本在“all”模式下会把扩展目录打成 uBlock0.chromium.zip，这正是文档要求你解压的对象。手动更新方式有两个明确优势（原文档 Note 部分）：

由你自己决定何时更新；
如果新版不满意，可以随时回滚到上一版（保留旧 zip，替换回 ublock 目录内容即可）。

从仓库构建脚本还能确认一个细节：zip 包内目录结构以 manifest.json 位于 ublock 目录根部为前提（copy-common-files.sh 负责拼装 manifest 与页面）。所以“重命名为 ublock”这一步并非随意命名，而是为了让开发者模式下加载的目录名与实际安装目录名一致，避免因路径变化导致 Chromium 判定为“新扩展”而重置存储。

Firefox：稳定版与 Beta 版的两种安装方式

文档声明 Firefox 侧兼容 Firefox 52 及以上版本。

稳定版（Stable Release）

此方法仅在 about:config 中将 xpinstall.signatures.required 设置为 false 时有效（即关闭 Firefox 的强制扩展签名校验）。步骤：

下载 ublock0.firefox.xpi（建议取最新 release 版本）——右键选择“Save As…”保存。
将下载好的 ublock0.firefox.xpi 拖拽到 Firefox 窗口中完成安装。

从 tools/make-firefox.sh 可以印证 ublock0.firefox.xpi 的产生方式：脚本先把通用文件与 platform/firefox/ 下的平台文件复制进 dist/build/uBlock0.firefox，再由 tools/make-firefox-meta.py 生成 Firefox 版 manifest，最后在“all”模式下把整个目录打成 .xpi（本质是 zip 包）。这也解释了为什么该包未经 Mozilla 签名、需要关闭签名校验才能安装。

Beta 版（Beta Version）

直接点击 release 中的 ublock0.firefox.signed.xpi 即可安装。由于该包已经过签名，无需修改 xpinstall.signatures.required。仓库中对应的发布目标见 Makefile 中的 publish-dev-firefox（channel=unlisted 渠道），即 beta/dev 构建走未列名发布通道。

uBO 在 Firefox 中的设置文件位置（Linux）

安装完成后，所有设置在 Linux 上保存于如下 JSON 文件：

~/.mozilla/firefox/[profile name]/browser-extension-data/uBlock0@raymondhill.net/storage.js

注意：卸载扩展时 Firefox 会删除该文件，所有设置随之丢失。如需迁移或备份，请先备份此文件。扩展 ID uBlock0@raymondhill.net 在仓库中可交叉验证——Makefile 的 publish-firefox 目标使用 storeid=uBlock0@raymondhill.net。

Firefox Legacy（Firefox 24–56 / Pale Moon / SeaMonkey）

旧版构建面向 Firefox 24–56 及 Pale Moon、SeaMonkey：

下载 ublock0.firefox-legacy.xpi（建议取最新 release 版本），右键选择“Save Link As…”；
将该 .xpi 拖拽到 Firefox 窗口中安装。

Firefox 43 及以上可能需要先在 about:config 中将 xpinstall.signatures.required 置为 false。

与新版存储机制的关键区别：Legacy 版的设置即使在卸载后也会保留，因为它是旧式扩展，使用独立的 SQLite 数据库存储：

Linux：

~/.mozilla/firefox/[profile name]/extension-data/ublock0.sqlite

Windows：

%APPDATA%\Mozilla\Firefox\Profiles\[profile name]\extension-data\ublock0.sqlite

开发者构建：从源码编译完整插件

文档给出的构建流程为：

克隆仓库：

git clone https://github.com/gorhill/uBlock.git

进入目录：
```
cd uBlock
```
官方版本位于 master 分支：
```
git checkout master
```
按目标构建：
- Chromium：make chromium
- Firefox：make firefox
- NPM 包：make npm
将构建产物加载到浏览器：
- Chromium：打开 chrome://extensions/ → 勾选 Developer mode → Load unpacked → 选择 dist/build/uBlock0.chromium/ 目录；
- Firefox：打开 about:debugging#/runtime/this-firefox → Load Temporary Add-on… → 选择 dist/build/uBlock0.firefox/ 目录（注意 Firefox 临时加载只对当前会话有效）。

构建依赖与环境前提

结合 Makefile 的实际定义，上述三条命令的真实依赖关系是：

make chromium 依赖 dist/build/uBlock0.chromium 目标，其先决条件包括 tools/make-chromium.sh、dist/version、assets/ 与 src/ 下所有源文件，以及 platform/*/* 下的平台文件（Makefile#L26-L30）；
make firefox 同样先决于 tools/make-firefox.sh，并额外要求 make-firefox.sh all 以同时产出 .xpi（Makefile#L38-L42）；
make npm 走 tools/make-npm.sh，最终通过 npm pack 产出 uBlock0.npm.tgz 源码包，并在非 CI 环境下执行 npm install。

过滤列表依赖：sources 中显式包含了 $(shell find ./assets -type f)，且 dist/build/uAssets 目标由 tools/pull-assets.sh 生成（Makefile#L93-L94）。也就是说首次构建时 Make 会自动拉取 uBO 官方过滤列表仓库到 dist/build/uAssets，再经 tools/copy-common-files.sh 打入各平台包内——这就是为什么构建过程需要联网。

Node.js 版本要求：根 package.json 声明了 "engines": { "node": ">=22", "npm": ">=11" }。构建脚本本身是纯 bash + python3（生成 manifest 用 tools/make-chromium-meta.py、tools/make-firefox-meta.py），但 make npm 需要满足上述 Node 22 / npm 11 环境。

版本来源：构建版本号来自 dist/version 文件（当前为 1.74.0）。make-chromium.sh / make-firefox.sh 支持带版本参数调用，例如产出 uBlock0_<version>.chromium.zip、uBlock0_<version>.firefox.xpi 这类带版本后缀的包，方便手动更新用户对比安装。

仓库中其他可用的构建目标

Makefile 还声明了若干与安装部署相关的目标，可作为上文三步构建的自然延伸：

目标	作用	产物
`make all`	等价于依次构建 chromium、firefox、npm 三个目标（Makefile#L24）	三类包全部产出
`make opera`	构建 Opera 版扩展	`dist/build/uBlock0.opera/`
`make mv3-chromium` / `mv3-firefox` 等	构建 Manifest V3 的轻量变体	`dist/build/uBOLite.<平台>/`
`make clean`	清空 `dist/build`、`tmp/node_modules`、`node_modules`	无
`make lint`	对 `src/js`、`platform/**` 及 JSON 文件跑 ESLint	无

另外 Makefile 中的 publish-chromium / publish-firefox / upload-firefox 等目标是发布流水线使用的（含 storeid、channel=listed/unlisted 等参数），普通用户部署时无需关心。

npm 包（@gorhill/ubo-core）的构建与用途

make npm 产出的不仅是发布物，也是理解 uBO 核心架构的入口。构建脚本 tools/make-npm.sh 依次：调用 make-nodejs.sh 与 make-assets.sh 组装 dist/build/uBlock0.npm → 复制 platform/npm/ 下的包元数据与测试 → 在包内执行 npm run build 与 npm pack。

该 npm 包即 platform/npm/README.md 所描述的 uBlock Origin Core（@gorhill/ubo-core），无外部依赖，核心是静态网络过滤引擎（SNFE，实现见 src/js/static-net-filtering.js），可用于在 Node.js 中独立解析并执行 EasyList 等过滤列表，例如：

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 })),
]);

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());
}

此外包还暴露了 HNTrieContainer（压缩 Trie 主机名容器，见 src/js/hntrie.js）等底层 API，可按 name@ 语义做高效主机名匹配，这些也是 uBO 扩展内部复用的同一套引擎。

关键结论与注意事项汇总

Chromium 手动安装的核心是“路径不变”：目录名固定为 ublock，更新时只替换内容、不移动目录，设置才能保留；扩展必须从相同路径加载（dist/README.md 第 6–8 行）。
Firefox 稳定版 xpi 未签名：必须先关闭 xpinstall.signatures.required 才能安装；Beta 版使用已签名的 ublock0.firefox.signed.xpi 可直接点击安装。
设置存储位置不同：新版 Firefox 存于 browser-extension-data/uBlock0@raymondhill.net/storage.js（卸载即删）；Legacy 版存于 extension-data/ublock0.sqlite（卸载后保留）。
构建入口是 Makefile：make chromium、make firefox、make npm 三个目标覆盖文档要求的全部产物；首次构建会自动拉取过滤列表，且 npm 构建要求 Node ≥ 22。
构建产物位置固定：dist/build/uBlock0.chromium/、dist/build/uBlock0.firefox/、dist/build/uBlock0.npm.tgz，与文档第 5 步的加载路径完全一致。