uBlock Origin MV3 移植版

这是 uBlock Origin 的 Manifest V3 实验性移植版本，通过特殊方式在 MV3 框架下使用 webRequestBlocking 权限。

⚠️ 重要说明

这是一个实验性项目，需要特殊配置才能运行。如果您只是想要一个能正常工作的广告拦截器，建议使用：

• uBlock Origin Lite - 官方 MV3 版本，无需特殊配置
• Firefox + uBlock Origin - Firefox 长期支持 MV2

📋 目录

• 为什么需要特殊配置
• 编译扩展
• 安装方法
  • 方法 1：企业策略安装（推荐）
  • 方法 2：命令行启动
• 技术原理
• 已知问题

---

为什么需要特殊配置？

MV3 限制

Chrome 的 Manifest V3 禁止普通扩展使用 webRequestBlocking 权限，这个权限对于强大的广告拦截至关重要。

解决方案

Chrome 为企业环境保留了一个例外：通过以下方式安装的扩展仍可使用 webRequestBlocking：

1. ✅ 企业策略强制安装 - 通过 Windows 注册表配置
2. ✅ 命令行白名单 - 启动 Chrome 时添加参数

本项目提供了这两种方式的自动化脚本。

---

编译扩展

Windows 环境

前置要求

• Git（包含 Git Bash）
• Python 3.x
• Node.js（可选，用于 linting）

编译步骤

# 1. 克隆仓库
git clone https://github.com/r58Playz/uBlock-mv3.git
cd uBlock-mv3

# 2. 下载过滤列表资源
bash tools/pull-assets.sh

# 3. 编译扩展
bash tools/make-chromium.sh

注意：如果遇到 Python 编码错误，已在 tools/make-chromium-meta.py 中修复（添加了 UTF-8 编码支持）。

编译输出

扩展将被编译到：

dist/build/uBlock0.chromium/

---

安装方法

方法 1：企业策略安装（推荐）

优点：

• ✅ 一次配置，永久有效
• ✅ 正常启动 Chrome，无需命令行参数
• ✅ 扩展自动加载

缺点：

• ⚠️ 需要管理员权限（仅安装时）
• ⚠️ 配置稍复杂

快速安装（3 步）

# 1. 进入策略脚本目录
cd enterprise_policy

# 2. 右键 install_policy.bat → 以管理员身份运行
# （按提示操作，输入 Y 确认）

# 3. 完全关闭 Chrome，然后正常启动

验证安装

# 运行验证脚本
verify_policy.bat

# 或访问 Chrome 策略页面
chrome://policy/

卸载

# 右键 uninstall_policy.bat → 以管理员身份运行
uninstall_policy.bat

详细文档

• 企业策略安装指南
• 跨机器部署指南

---

方法 2：命令行启动

优点：

• ✅ 配置简单
• ✅ 不需要管理员权限

缺点：

• ⚠️ 每次启动 Chrome 都需要使用命令行或脚本

获取扩展 ID

1. 打开 Chrome，访问 chrome://extensions/
2. 启用"开发者模式"
3. 点击"加载已解压的扩展程序"
4. 选择 dist/build/uBlock0.chromium 目录
5. 复制扩展 ID（例如：innoimmidddcjceeookeadecifbibjmo）

使用启动脚本

编辑 launch_chrome.bat，填入扩展 ID，然后双击运行：

# 脚本会自动：
# 1. 检测 Chrome 安装路径
# 2. 使用正确的命令行参数启动
# 3. 显示详细的状态信息

手动命令行启动

PowerShell：

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --allowlisted-extension-id=你的扩展ID

命令提示符：

"C:\Program Files\Google\Chrome\Application\chrome.exe" --allowlisted-extension-id=你的扩展ID

创建桌面快捷方式

1. 右键桌面 → 新建 → 快捷方式
2. 位置：

   "C:\Program Files\Google\Chrome\Application\chrome.exe" --allowlisted-extension-id=你的扩展ID
   

3. 命名：Chrome (uBlock MV3)

启用用户脚本权限

重要：首次使用后，需要启用此权限：

1. 访问 chrome://extensions/
2. 找到 uBlock Origin，点击"详细信息"
3. 启用"允许使用用户脚本"（Allow User Scripts）
4. 重启 Chrome

---

技术原理

工作机制

Chrome 启动
    ↓
检测企业策略/命令行参数
    ↓
识别扩展为"受信任"
    ↓
授予 webRequestBlocking 权限
    ↓
扩展正常工作

MV3 适配

• Service Worker：使用 MV3 的 Service Worker 替代 MV2 的后台页面
• API Polyfill：
  • chrome.tabs.executeScript → chrome.scripting.executeScript
  • chrome.tabs.insertCSS → chrome.scripting.insertCSS
• User Scripts：使用 chrome.userScripts API 注入脚本
• DOM Polyfill：为 Service Worker 提供必要的 DOM API

为什么 MV3 限制 webRequestBlocking？

Chrome 认为 webRequestBlocking 存在以下问题：

1. 性能：同步拦截所有请求，可能导致浏览器卡顿
2. 隐私：扩展可以访问所有网络流量，包括敏感数据
3. 安全：恶意扩展可以窃取或修改任意数据

MV3 推荐使用 declarativeNetRequest（静态规则），但功能受限。

---

已知问题

1. 偶尔注入到不存在的 frame

现象：控制台偶尔报错 Frame with ID XX was removed

原因：这是 Chrome 的 bug，uBlock Origin Lite 也有同样问题

影响：不影响正常使用

2. 部分 MV2 API 未完全 polyfill

现象：某些功能可能不稳定

状态：大部分功能正常工作，持续改进中

3. chrome:// URL 访问错误

现象：Cannot access a chrome:// URL

原因：MV3 限制，无法访问 Chrome 内部页面

影响：不影响广告拦截功能

---

文件结构

uBlock-mv3/
├── dist/build/uBlock0.chromium/    # 编译后的扩展
├── enterprise_policy/              # 企业策略安装脚本
│   ├── install_policy.bat         # 安装脚本
│   ├── uninstall_policy.bat       # 卸载脚本
│   ├── verify_policy.bat          # 验证脚本
│   ├── README.md                  # 详细使用说明
│   └── DEPLOYMENT.md              # 部署指南
├── launch_chrome.bat              # 命令行启动脚本
├── tools/                         # 编译工具
├── src/                           # 源代码
└── README.md                      # 本文件

---

常见问题

Q: 为什么不直接使用 uBlock Origin Lite？

A: uBlock Origin Lite 是官方 MV3 版本，功能受限但无需配置。本项目是实验性的，目标是在 MV3 下保留完整功能。

Q: 哪种安装方式更好？

A:

• 长期使用：企业策略安装（一次配置，永久有效）
• 临时测试：命令行启动（简单快速）
• 日常使用：建议使用官方 uBlock Origin Lite

Q: 可以在其他浏览器使用吗？

A:

• Edge：可以，使用相同方法
• Firefox：不需要，Firefox 继续支持 MV2
• 其他 Chromium 浏览器：理论上可以，需要测试

Q: 扩展会自动更新吗？

A: 不会。这是本地编译版本，需要手动重新编译和部署。

Q: 安全吗？

A:

• ✅ 开源代码，可审计
• ✅ 基于官方 uBlock Origin
• ⚠️ 企业策略需要管理员权限
• ⚠️ 命令行参数绕过了 Chrome 的安全限制

---

贡献

本项目是 uBlock Origin 的 MV3 移植版本。

• 原项目：gorhill/uBlock
• MV3 移植：r58Playz/uBlock-mv3

---

许可证

GPLv3 - 详见 LICENSE.txt

---

相关链接

• uBlock Origin 官方文档
• Chrome 扩展开发文档
• Manifest V3 迁移指南