企业官网建设流程全解析

• 开发工具
• 网络

Header Editor（仓库项目名header-editor，当前版本 5.1.0，见 package.json）是一个 100% 免费、无广告、不收集数据的浏览器扩展，核心能力是接管浏览器的网络请求：修改请求头、修改响应头、修改响应体、重定向请求、取消请求。本文基于仓库根目录的 README 完整展开：先讲清楚完整版（Full）与精简版（Lite）在浏览器与 Manifest 维度上的版本矩阵，再逐项对照源码解释每个权限为什么存在、底层如何实现，最后给出从源码构建、本地调试到测试验证的完整可操作流程。

一、项目定位：五大请求操纵能力

README 对项目的一句话定义是：“An extension which can modify the request, include request headers, response headers, response body, redirect requests, and cancel requests”。这五类能力在源码中是一等公民。规则类型定义 用RULE_TYPE枚举固化了五种动作：

export enum RULE_TYPE { CANCEL = 'cancel', // 取消请求 REDIRECT = 'redirect', // 重定向请求 REDIRECT_AT_RESPONSE = 'redirectAtResponse', // 收到响应后重定向 MODIFY_SEND_HEADER = 'modifySendHeader', // 修改请求头 MODIFY_RECV_HEADER = 'modifyReceiveHeader', // 修改响应头 MODIFY_RECV_BODY = 'modifyReceiveBody', // 修改响应体 }

规则数据按功能分表存储，表名同样由 TABLE_NAMES 定义：request（取消/重定向）、sendHeader、receiveHeader、receiveBody。值得注意的是官方文档 规则指南 强调：HE 本身不具备任何功能，它只是提供管理和编写规则的能力，规则的执行顺序也是不确定的，不应依赖执行顺序来设计功能。此外还有两个约定标记字符串（constant.ts）：

• 把请求头/响应头内容设为_header_editor_remove_会删除该头（自 3.0.5 起有效）；
• 重定向规则中使用自定义函数并返回_header_editor_cancel_会阻止该请求（自 4.0.3 起有效）。

二、版本矩阵：Full 与 Lite，v2 与 v3

README 给出了一张按浏览器划分的“Lite / Full”安装矩阵，并约定：官方下载与 Mozilla Add-ons 内容完全一致，但商店审核通常要一周以上；HeaderEditor-xxx-v2是完整版，HeaderEditor-xxx-v3是精简版。这里的 v2/v3 指 Manifest 版本，而文件名中的版本号由构建工具拼接：get-path.js 的getOutputFile会生成HeaderEditor-${version}-${MANIFEST_VER}.${ext}，例如HeaderEditor-5.1.0-v2.crx。

这套矩阵在构建侧由 browser.config.json 精确落地，四个目标各自声明了四个特性开关：

{ "firefox_v2": { "MANIFEST_VER": "v2", "ENABLE_DNR": true, "ENABLE_WEB_REQUEST": true, "ENABLE_EVAL": true, "IS_LITE_VER": false }, "firefox_v3": { "MANIFEST_VER": "v3", "ENABLE_DNR": true, "ENABLE_WEB_REQUEST": true, "ENABLE_EVAL": false, "IS_LITE_VER": true }, "chrome_v2": { "MANIFEST_VER": "v2", "ENABLE_DNR": false, "ENABLE_WEB_REQUEST": true, "ENABLE_EVAL": true, "IS_LITE_VER": false }, "chrome_v3": { "MANIFEST_VER": "v3", "ENABLE_DNR": true, "ENABLE_WEB_REQUEST": false, "ENABLE_EVAL": false, "IS_LITE_VER": true } }

可以推断出两个关键差异：

• Chrome 精简版（chrome_v3）关闭了webRequest，完全依赖 declarativeNetRequest（DNR），因此不支持“排除-正则表达式”和自定义函数（依赖运行时求值的规则无法声明式化）；
• Firefox 两个版本都同时启用 DNR 与 Web Request，且 v2 额外允许eval，因此 Firefox 完整功能面最宽。

官方中文文档 安装指南 中有对应的功能比较表（如 Chrome 完整版支持 DNR 运行模式 ❌ 而精简版 ✅，因为 v2 版 Chrome 尚未普及 DNR 而 v3 必须使用 DNR），并备注：若某规则依赖当前构建不支持的功能，整条规则不会生效但会被保留，可等待支持或通过“导入和导出”迁移到其他浏览器。

三、权限清单：README 声明与源码实现的逐项对照

README 的 Permissions 一节声明了扩展所需权限及其用途。对照 get-manifest.js 中 manifest 的生成逻辑，每一项都能在源码中找到对应的请求处理器：

补充两点源码细节：

• v3 构建中，主机权限走host_permissions（*://*/*、ws://*/*、wss://*/*、file:///*），v2 构建则合并进permissions，见 get-manifest.js；
• 响应体修改在 Chrome 中依赖debugger协议（README 明确debugger权限的用途），而 Firefox 走webRequest流式过滤器；web-request-handler.ts 中还定义了MAX_BODY_SIZE = 8 * 1024 * 1024，即最大修改 8MB 的 Body。

四、双引擎架构：规则如何被分发到 DNR 或 Web Request

background 的入口是 src/pages/background/index.ts：init()依次执行doUpgrade()（版本升级迁移）、initRules()（加载规则库），然后按编译期开关挂载三套处理器：

createApiHandler(); if (ENABLE_WEB_REQUEST) { createWebRequestHandler(); } if (ENABLE_DNR) { createDNRHandler(); } if (IS_CHROME) { createChromeResponseModifier(); }

ENABLE_WEB_REQUEST、ENABLE_DNR等不是运行时判断，而是构建期注入的全局变量——rsbuild.config.ts 的getGlobalVars()会把browser.config.json中当前TARGET_BROWSER的配置整体define进代码，因此每个构建产物只包含自己需要的引擎分支。v3 目标还会额外注册browser.runtime.onStartup监听器（Service Worker 唤醒后重新初始化，见 index.ts）。

单条规则走哪个引擎，由 detectRunner 决策，优先级如下（源码注释与分支顺序一致）：

1. 规则显式指定forceRunner且对应引擎可用；
2. 含自定义函数（isFunction）→web_request；
3. 含排除条件（exclude）→web_request；
4. 含excludeRegex→web_request；
5. 修改响应体（MODIFY_RECV_BODY）→web_request；
6. 需要响应头匹配而当前环境不支持声明式响应头匹配（isSupportHeaderMatch()：Firefox 一律不支持，Chrome 需 ≥128，见 rule-utils.ts）且 Web Request 可用 →web_request；
7. 其余情况 →dnr（DNR 模式性能更好，适合高频匹配的纯声明式规则）。

initRule（rule-utils.ts）随后为web_request引擎的规则预编译资源：把自定义函数编成new Function(...)、把regex/excludeRegex/urlFilter编译为RegExp、把响应头条件交给header-matcher的compileCondition。DNR 引擎一侧，createDNR 把 HE 规则翻译成 declarativeNetRequest 规则对象：domain→requestDomains，前缀匹配 →urlFilter: pattern*，正则 →regexFilter，请求方法/资源类型注意 DNR API 的互斥约束（如excludedRequestMethods与requestMethods只能二选一），并对新浏览器追加imageset资源类型。

Web Request 引擎的钩子在 initHook 中挂载三个事件：onBeforeRequest（blocking+requestBody）、onBeforeSendHeaders（blocking+requestHeaders，Chrome 下追加extraHeaders）、onHeadersReceived（blocking+responseHeaders），全部监听<all_urls>。它还会响应偏好变化：disable-all开关会直接移除/恢复三个监听器（setDisableAll），实现“一键停用”而不影响已保存的规则。

五、如何从源码构建（Build）

以下内容完整继承自 README 的 “How to build” 一节，并结合构建脚本补充了原理。

环境要求

• 安装 Node.js 24.x 和 pnpm 11.x（README 推荐版本；package.json 的engines底线为node >= 20、pnpm >= 10）；
• Clone 本仓库，或下载源码并解压。

构建步骤

# 1. 安装依赖（锁定 lockfile，保证构建可复现） pnpm i --frozen-lockfile # 2. 按目标执行构建，四选一： npm run build:chrome_v2 # Chrome 完整版（Manifest v2） npm run build:chrome_v3 # Chrome 精简版（Manifest v3） npm run build:firefox_v2 # Firefox 完整版（Manifest v2） npm run build:firefox_v3 # Firefox 精简版（Manifest v3）

每个命令的实际形态是cross-env TARGET_BROWSER=<目标> rsbuild build（见 package.json scripts）。构建完成后产物位于/dist_*目录，目录名由 get-path.js 的getDistDir决定，即dist_${TARGET_BROWSER}（例如dist_chrome_v2）。

几个值得了解的构建细节：

• 两个 rsbuild environment：rsbuild.config.ts 把构建拆成background（入口src/pages/background/index.ts与content-cloud-drive，单文件、无 HTML、无异步 chunk，输出到scripts/）和web（options.html与popup.html两个页面，启用 React + Less + emotion 插件）。
• manifest.json 由插件生成：manifest.plugin.ts 在编译结束后调用 get-manifest.js 按目标浏览器生成 manifest 并写入产物根目录。版本号取自package.json（5.1.0），但支持三种覆盖：temp/version.txt强制版本、CI 中 tag 触发的GITHUB_REF_NAME、CI 输入INPUT_VERSION（manifest.plugin.ts）。开发模式还会为 v2 manifest 注入宽松 CSP，并注入 extension.json 中的key以固定扩展 ID。
• 发布包 ID 体系：extension.json 登记了各商店/打包方式的浏览器映射与扩展 ID（如 Chrome v3 对应cws的eningockdidmgiojffjmkdblpjocbhgh，Firefox 的xpi/amo均要求min_version: 113.0），用于打包.crx、.xpi及商店发布流程。

本地开发调试（Development）

1. 修改start脚本的TARGET_BROWSER（当前默认chrome_v3，见 package.json）为你要调试的版本，然后运行npm run start；
2. 开发服务器启用了writeToDisk: true且关闭 HMR（rsbuild.config.ts），会把产物实时写到/dist_*磁盘目录；
3. 在浏览器中通过“加载已解压的扩展程序”指向/dist_*目录或/dist_*/manifest.json即可热更调试。

六、测试体系：单元与 E2E 如何验证规则引擎

仓库内置了完整的自动化测试，可作为理解规则引擎的“活文档”：

• 单元测试：npm run test:unit（mocha +--experimental-vm-modules），位于 tests/unit，重点覆盖规则匹配核心：url-filter.spec.mjs（URL 过滤语法）、is-match-url.spec.mjs（匹配判定，对应 constant.ts 的IS_MATCH三态：MATCH/MATCH_BUT_EXCLUDE/NOT_MATCH）、header-matcher.spec.mjs（响应头条件编译与匹配）。
• E2E 测试：npm run test:e2e使用 puppeteer 驱动真实浏览器加载扩展产物，配合 PHP 静态服务器npm run run-test-server（php -S 0.0.0.0:8899 -t tests/simple-server）提供回显端点。tests/simple-server 下有一组用途明确的探针脚本：mock-header.php（回显请求头）、match-response-header.php、get-query.php、csp.php、js-src.php等；测试用例 request.spec.mjs 与 response.spec.mjs 分别验证请求侧与响应侧的修改行为。

如果你修改了规则匹配或 DNR 转换逻辑，这套测试提供了最小可运行的回归验证手段。

七、国际化与贡献

README 的 Contribution 一节说明：

• 英文文案：直接向locale/original/messages.json提 issue 或 PR；
• 其他语言：在 Transifex 平台翻译（仓库中 transifex.yml 配置了同步规则：源文件original/messages.json（CHROME 格式，source_language 为 en），翻译落盘到output/<lang>/messages.json）；
• 注意部分语言（如 zh-Hans）不走 Transifex，因为浏览器 i18n 不支持该 BCP-47 标签；最终产物直接打包进 public/_locales 目录（当前含de、en、es、fr、it、ja、ko、pl、pt_BR、ru_RU、sv、zh_CN、zh_TW共 13 个语言包），由 rsbuild 的backgroundenvironment 整体拷贝./public到产物根目录（rsbuild.config.ts）。

辅助脚本方面，sort-origin.js 用于对源文案键排序，create-pr.js 用于生成翻译合并请求，locales.js 负责合并output/下各语言的翻译。代码风格统一由 biome.json 约束，提交前通过lint-staged自动执行biome check --write（见 package.json）。

八、许可证与适用前提

• 本项目采用GNU GPL v2.0 or later许可（package.json 声明为GPL-2.0，LICENSE 为全文）；README 明确声明：禁止将该项目内容用于人工智能领域的训练、模仿、学习、生成或相关活动。
• 构建产物面向不同浏览器的最低版本要求由 extension.json 约束（Firefox 系min_version: 113.0、android_min_version: 120.0，Chrome crx 打包min_version: 90.0.0），调试或二次开发时应以当前仓库内容为准，并注意 README 所述new Function自定义函数执行位置“可能在未来变化”。

九、延伸阅读路径

理解完本文后，建议按以下仓库路径继续深入（均为可直接查看的文档与源码）：

总结来说，Header Editor 的工程价值在于：用一套规则模型同时驱动 DNR（声明式、高性能）与 Web Request（阻塞式、全功能）两套浏览器网络拦截引擎，通过构建期开关为不同浏览器/Manifest 版本裁剪能力面，再用单一 rsbuild 流水线输出四个目标产物。掌握了本文的权限映射、detectRunner决策链与构建流程，即可独立完成扩展的构建、调试与二次理解。

• 开发工具
• 网络