HeaderEditor 第三方规则库:社区共享规则的安全导入、校验与使用指南
HeaderEditor 第三方规则库:社区共享规则的安全导入、校验与使用指南
导读
HeaderEditor 作为一款浏览器请求管理扩展,支持修改请求/响应头、重定向与取消请求等能力,而"规则"是这一切的核心载体。除了自行创建规则,官方还维护了一个由社区第三方维护的规则列表页面,让用户可以直接下载他人分享的规则文件(JSON 格式)并一键导入。本文基于官方文档 third-party-rules.md(含简体中文版 third-party-rules.md),系统讲解第三方规则的使用前提、当前官方收录的规则清单、从导入到校验的完整流程,以及如何将自己的规则提交到官方列表,帮助你安全、高效地复用社区规则。
一、什么是第三方规则
HeaderEditor 的规则以 JSON 文件为载体,描述"匹配什么请求、执行什么动作"。官方维护的第三方规则列表,指的是由社区第三方作者维护、但被官方文档收录展示的规则文件。它们与用户自建规则在格式上完全一致,可以直接通过扩展的"导入"功能进入本地规则库。
在使用前请务必明确边界:这些规则由第三方维护,Header Editor 官方不保证规则的时效性和安全性,若出现问题,需要联系规则维护者而不是扩展作者。这一定位意味着,导入第三方规则本质上与导入任意 JSON 规则文件没有区别,关键在于导入前自行评估其可信度。
二、官方文档收录的第三方规则清单
官方文档列表在英文版(docs/docs/en-US/guide/third-party-rules.md)与简体中文版(docs/docs/zh-CN/guide/third-party-rules.md)中略有差异,合并整理如下(下载地址均由各作者在其仓库或站点维护,请从官方文档列表页点击跳转下载):
| 规则文件 | 作者 | 简介 | 收录语言 |
|---|---|---|---|
| CingList.json | dupontjoy | 部分中文站点重定向、防盗链规则 | 中文版 |
| HE-GoogleRedirect.json | azurezeng | Google 资源、reCaptcha 重定向 | 中文版 |
| Amazon.Smile.zip | vertigo220 | Amazon 自动跳转 Amazon Smile | 英文版 |
| Willie169-HE.json | Willie169 | Willie169 个人规则,如禁用 AI 搜索等 | 中英文版 |
从列表可以看出,第三方规则覆盖了重定向(Redirect)、防盗链(Referer 等请求头处理)等典型场景,而这些恰好对应 HeaderEditor 的核心能力。例如 RULE_TYPE 中定义的 redirect、modifySendHeader、modifyReceiveHeader、cancel 等类型,正是这类规则最常用的动作类型。
三、导入第三方规则:从下载到入库的完整流程
下载到的第三方规则文件(.json 或压缩包解压后的 .json)可以直接导入 HeaderEditor。整个导入链路在源码中清晰可循。
3.1 入口:本地文件导入
在扩展的"选项页 → 导入与导出"中,本地文件区提供"导出 / 导入"两个按钮(见 local-file.tsx)。点击"导入"后,扩展读取 .json 文件内容并 JSON.parse,解析失败会通过 Toast 提示错误;导出时则调用 createExport 将全部规则以 \t 缩进格式化后落盘。
3.2 解析与兼容升级:fromJson 与 upgradeRuleFormat
导入的 JSON 会交给 fromJson 处理:它遍历 request、sendHeader、receiveHeader、receiveBody 四张规则表(对应 TABLE_NAMES),并对每条规则调用 upgradeRuleFormat 做兼容性升级——例如:
- 将旧版
type字段映射为matchType; - 将旧版
action对象转换为新的headers键值对并统一转为小写; - 将
matchType(all / domain / prefix / regexp / url)转换为新的condition结构,如condition.all、condition.domain、condition.urlPrefix、condition.regex、condition.url; - 响应头匹配项(
responseHeaders、excludeResponseHeaders)的 header 字段统一小写化。
这意味着第三方规则即使基于旧版 HeaderEditor 格式编写,导入时也会被自动升级到当前格式,保证兼容性。
3.3 导入预览:去重、分组与冲突处理
解析完成后,导入抽屉(import-drawer.tsx)会弹出预览界面,逐条规则执行:
- 重名检测:按规则名查询本地是否已存在同名规则,已存在则标记为"更新"(
importAction = 2,导入时复用原规则 id 覆盖),否则标记为"新增"(importAction = 1),也支持跳过不导入(importAction = 3); - 分组归属:默认沿用规则自带的
group,也可在预览时统一指定目标分组; - 启用状态:未显式声明的
enable字段默认置为true。
确认后规则写入本地存储并生效。第三方规则通过这条链路入库后,与自建规则没有任何区别,同样受全局开关、分组管理等机制约束。
3.4 规则格式速览
了解第三方规则文件的基本结构,有助于导入前判断其质量。一条 HeaderEditor 规则(BasicRule)的核心字段包括:
enable:是否启用;name:规则名称(导入时作为去重依据);ruleType:动作类型,如redirect、cancel、modifySendHeader、modifyReceiveHeader、modifyReceiveBody(RULE_TYPE);condition:匹配条件,支持all、url、urlPrefix、domain、method、regex、urlFilter、resourceTypes、响应头匹配等(types.ts);headers:修改请求/响应头时使用的键值对;isFunction/code:是否使用自定义函数及函数代码;group:所属分组。
匹配条件最终会被 initRule 编译为正则等内部结构,由后台页面在每次请求时执行判断(参见 isMatchUrl)。
四、使用第三方规则的安全建议
官方文档明确声明不保证第三方规则的时效性与安全性,结合导入流程源码,建议遵循以下实践:
- 核对来源:只从官方文档列表页跳转的链接下载,警惕同名伪造文件;优先选择作者主页明确、说明详尽的规则;
- 预览后再导入:利用导入抽屉的分组与跳过机制,先导入到独立分组、观察规则匹配与动作是否合理;
- 注意规则类型:涉及
redirect、cancel的规则会改变请求走向,涉及响应体的规则(modifyReceiveBody)需要先在偏好中开启对应功能(defaultPrefValue 中modify-body默认关闭); - 保持可追溯:规则出现异常时,先检查规则本身,必要时联系对应作者,而非整体禁用扩展。
五、如何将自己的规则提交到官方列表
如果你维护了一套希望分享给社区使用的规则,可以按照官方文档的指引提交:
- 在仓库的 Issue 页面发起新 Issue,选择"规则提交"模板(英文模板见 .github/ISSUE_TEMPLATE/rule-submit.md,中文模板见 .github/ISSUE_TEMPLATE/rule-submit-cn.md);
- 按模板填写规则信息(作者、规则内容的简单说明,如"某作者-某某资源重定向")与规则 URL 或规则内容(提供可下载地址,或直接上传导出的 JSON 文件);
- 官方审核收录后,规则会出现在文档的第三方规则列表中。
注意:列表仅收录第三方维护的规则,官方不负责维护其时效与安全;提交前请确保规则文件本身可正常导入、描述真实准确,并留下稳定的维护渠道。
六、小结
第三方规则列表是 HeaderEditor 生态中"规则复用"的重要入口:它把社区维护的重定向、防盗链等实用规则以统一格式呈现给用户。理解"第三方维护、官方不担责"的边界,掌握从下载、导入、预览到入库的完整链路(本地文件导入 → fromJson 兼容升级 → 重名检测与分组归并),以及基于 Issue 模板的规则提交规范,就能在享受社区成果的同时把风险控制在可预期的范围内。