PT 助手 Plus 跨浏览器兼容指南：让一个 Web Extension 在 Chrome / Edge / Firefox 行为一致-平芜编程栈

PT 助手 Plus 跨浏览器兼容指南：让一个 Web Extension 在 Chrome / Edge / Firefox 行为一致

【免费下载链接】PT-Plugin-PlusPT 助手 Plus，为 Microsoft Edge、Google Chrome、Firefox 浏览器插件（Web Extensions），主要用于辅助下载 PT 站的种子。项目地址: https://gitcode.com/GitHub_Trending/pt/PT-Plugin-Plus

PT 助手 Plus（PT-Plugin-Plus）是一个同时上架 Microsoft Edge、Google Chrome 和 Firefox 的 Web Extension 插件，用来辅助下载 PT 站的种子。对这类插件而言，浏览器插件跨浏览器兼容不是一个"锦上添花"的议题：同一份代码在 Chrome 里能加载的内容脚本，换一个打包配置到 Firefox 里可能因编码问题直接失效；Chrome 后台页热重载之后，内容脚本到后台页的消息通道会瞬间断开。这篇文章从项目里真实踩过的坑讲起，拆解 PT-Plugin-Plus 是如何用分层架构、统一的 Manifest 契约和工程化手段，抹平三大浏览器之间的差异的。

从两个线上"翻车现场"说起

现场一：Chrome 拒绝加载内容脚本。压缩混淆后的脚本里混入了非 ASCII 字符，Chrome 直接报错"该文件采用的不是 UTF-8 编码"。修复手段藏在 webpack/common.js 里：TerserPlugin 强制ascii_only: true，让所有非 ASCII 字符以\uXXXX转义输出。

// webpack/common.js：防止编码问题导致 Chrome 无法加载插件 minimizer: [ new TerserPlugin({ terserOptions: { output: { ascii_only: true } } }) ]

现场二：插件重载后页面"失联"。扩展被更新或开发者重载后，已打开的页面里chrome.runtime.sendMessage会抛出 "Could not establish connection" 或 "Extension context invalidated"。项目在 src/service/extension.ts 的sendRequest里对这些错误做了模式匹配分类：属于"通道断开"类的，弹通知提示用户刷新页面，而不是让 Promise 静默 reject 掉业务逻辑。

这两个案例代表了两类典型差异：一类是构建产物层面的（编码、体积、模块格式），一类是运行时 API 行为层面的（错误模型、生命周期）。后面的做法都是围绕这两类差异展开的。

把差异摊开：三个浏览器各自的地雷在哪里

与其在代码里散落着打补丁，不如先把差异固化成一份可对照的清单。结合 public/manifest.json 和源码，PT 助手 Plus 需要处理的差异点大致是：

Manifest 方言：Chrome 侧用minimum_chrome_version: "64.0.3242"卡下限；Firefox 侧靠browser_specific_settings.gecko.update_url指定独立更新地址。同一份 Manifest 要同时说两种"方言"。
后台形态：Chrome/Edge 正向 Manifest V3 的 Service Worker 迁移，Firefox 仍长期支持持久化 background 页。项目当前是"manifest_version": 2，后台页逻辑（src/background/service.ts 中的PTPlugin类）假设了一个常驻环境——定时器、内存里的配置缓存都依赖这一点。
权限模型：downloads、cookies被放进optional_permissions而非permissions，装完插件不立即索取，由用户按需授权（Firefox 对可选权限的弹窗行为与 Chrome 略有不同，见后文）。
存储限额：chrome.storage.sync单条有 8KB 上限，大数组必须拆分（src/background/syncStorage.ts）。
URL 匹配范围：站点的静态资源常走 CDN 域名，上下文菜单的documentUrlPatterns/targetUrlPatterns必须把主域和 CDN 一起圈进来（src/background/contextMenus.ts 的getSiteDocumentUrlPatterns）。
国际化：名称、描述、站点列表都走__MSG_*__占位符，消息体放在public/_locales/zh_CN/messages.json与public/_locales/en/messages.json。

{ "manifest_version": 2, "minimum_chrome_version": "64.0.3242", "optional_permissions": ["downloads", "cookies"], "browser_specific_settings": { "gecko": { "update_url": "https://pt-plugins.github.io/PT-Plugin-Plus/update/firefox.json" } } }

清单化之后，"兼容性"就变成了一张可以逐项验收的表，而不是每次升级浏览器才暴露一次问题的黑盒。

一套核心逻辑，三个入口：分层怎么切

项目没有为 Chrome 和 Firefox 各写一份代码，而是把差异压在一层薄薄的适配层里，其余代码只面对内部接口：

关键约定有两条：

命名空间统一走chrome.*。Firefox 对绝大多数 WebExtension API 提供了chrome.*兼容，所以项目不引入browser.*分支，而是把"API 是否存在"做成运行时检测，而不是"浏览器是谁"的判断。浏览器身份的识别只在统计展示这类弱依赖场景使用（src/service/public.ts 用ua-parser-js解析 UA 记录浏览器名）。
能力检测前置。以权限模块为例（src/service/public.ts）：

public checkPermissions(permissions: string[]): Promise<any> { return new Promise<any>((resolve, reject) => { if (chrome && chrome.permissions) { chrome.permissions.contains({ permissions }, result => { result ? resolve(true) : reject({ success: false }); }); } else { // 不支持 permissions API 的环境直接走降级 reject({ success: false }); } }); }

chrome && chrome.permissions这种写法看起来笨拙，但它把"这个环境有没有这个能力"和"是哪个浏览器"解耦了——将来某个浏览器的 API 行为变化，改的只是这一处守卫，而不是全库的 UA 判断。

消息总线：把回调地狱和平台错误翻译成 Promise

内容脚本、options 页、popup 与后台页之间的所有通信都收敛到 src/service/extension.ts 的一个sendRequest方法。它的核心价值不在于"发一条消息"，而在于统一处理了 Web Extensions 回调式 API 的三类失败：

// 统一消息总线：把 chrome.runtime.lastError 语义收敛为 Promise 结果 public sendRequest(action: EAction, callback?: any, data?: any): Promise<any> { return new Promise((resolve, reject) => { chrome.runtime.sendMessage({ action, data }, (result: any) => { if (chrome.runtime.lastError) { const msg = chrome.runtime.lastError.message || ""; if (/Could not establish connection/.test(msg)) { APP.showNotifications({ message: "插件状态未知，当前操作可能失败，请刷新页面后再试" }); reject(chrome.runtime.lastError); return; } if (!/The message port closed before a response was received/.test(msg)) { reject(chrome.runtime.lastError); return; } } result?.reject ? reject(result.reject) : resolve(result.resolve); }); }); }

这里体现的是跨浏览器兼容里一个容易被忽视的原则：不同浏览器把"失败"报告出来的时机和措辞不同（连接建立失败、端口提前关闭、上下文失效），如果让每个调用方自己判断lastError，行为就会分叉。收敛之后，上层业务拿到的只有两种结果：resolve 携带{ resolve }，或 reject 携带明确原因。

同一文件还留了一条调试后门：localMode下不走runtime.sendMessage，而是动态import("@/background/service")直接实例化后台服务调用——这让开发者不必加载整个浏览器扩展环境就能跑通前台逻辑。

Manifest 即契约：多版本配置如何写进同一份文件

前面清单里的"Manifest 方言"，落地方式比想象中简单——不需要为每个浏览器生成一份 Manifest，因为三家都支持"公共字段 + 私有命名空间"的合并语义：

public/manifest.json的完整结构里有几个值得注意的点：

后台按多脚本顺序加载：libs/types.expand.js → jquery → Base64 → js/background/libs.js → js/background/background.js，第三方库先于业务代码注入，避免打包环境差异带来的模块顺序问题（webpack/common.js 里splitChunks把node_modules单独打成libs，就是这个顺序的前提）。
content_scripts.matches覆盖http://*/*和https://*/*，同时用exclude_matches排除https://fonts.google.com/*——内容脚本按域名粒度做排除，是对"全局注入"成本的克制。
web_accessible_resources显式列出可被页面访问的资源，Firefox 对未声明资源拦截得更严，提前声明能避免跨浏览器行为不一致。

关于Manifest V3 适配，这是后续维护的主要成本项：background.scripts数组会被替换为单一 service worker 入口，而PTPlugin目前的定时器与内存缓存假设后台常驻。迁移路径基本是"worker 化 + storage 化状态"，本文不展开，但它决定了现在每一处新增后台逻辑都要先问一句"这能不能活在一个随时会被杀掉的 worker 里"。

权限按需索取：optional_permissions 与用户手势

种子下载需要downloads，Cookie 备份需要cookies，但绝大多数用户装完插件只想搜索。项目把这两项放进optional_permissions，配合 src/options/components/Permissions.vue 提供一个授权面板：

实现上有两个约束值得抄走：

// 权限必须在用户操作下请求，例如按钮单击的事件处理函数 chrome.permissions.request(options, granted => { this.$emit("update", granted); });

以 Manifest 为准做可见性过滤：面板created钩子里用chrome.runtime.getManifest()读取optional_permissions，不在清单里的权限项直接隐藏，避免代码与 Manifest 漂移。
请求动作必须发生在用户手势的调用栈里。requestPermissions被包成 Promise 之后很容易在异步链路上丢掉手势上下文，导致某些浏览器静默失败。所以封装层（src/service/public.ts 的usePermissions）把"检查 → 可选确认 → 请求"串起来，但发起点始终留在按钮回调中。

工程化落地：打包、本地调试与存储拆分

兼容性问题有一半出在"开发机上一切正常"。项目给出的工程化答案是：

按产物拆分构建。package.json 的脚本把一次发布拆成三个互不干扰的产物：

yarn build:index # vue-cli-service 构建 options 页面 yarn build:background # webpack/prod-background.js 构建后台页 yarn build:content # webpack/prod-content.js 构建内容脚本

后台、内容脚本走同一份 webpack/common.js 共享配置（编码、拆包、ts-loader 规则一致），出问题时定位范围小得多。

本地调试不依赖浏览器扩展环境。localMode模式下sendRequest直接调用后台服务实例，配合debug/目录下的独立 Node 工程（yarn dev-s），可以在没有加载扩展的情况下验证业务链路。

存储限额用拆分而非回避。chrome.storage.sync单条 8KB 的上限下，src/background/syncStorage.ts 把大数组拆成key_0 … key_n加一个key__count，读取时按 count 重组。这类"浏览器限额适配"没有捷径，只能显式处理。

发版前过一遍这份清单

把前文的做法压缩成一份可执行的 checklist，适合放进每次升级目标浏览器版本前的验收流程：

只依赖三家共有的标准 API；遇到browser.*/chrome.*差异，先改成能力检测（chrome && chrome.permissions风格），而不是 UA 分支。
chrome.runtime.lastError与连接断开类错误必须在消息层统一收敛，禁止业务代码各自处理。
压缩产物强制 ASCII 输出（ascii_only: true），在 Chrome 和 Firefox 各加载一次内容脚本验证。
Manifest 公共字段与browser_specific_settings分开评审：minimum_chrome_version与 gecko 更新地址是否都指向当前版本。
可选权限项逐一核对：是否在optional_permissions中、授权入口是否处于用户手势内、拒绝授权后功能是否有降级提示。
大对象存储路径过一遍拆分逻辑，尤其是有数组、备份数据参与的字段。
两个浏览器各跑一遍冒烟用例：安装 → 搜索 → 下载 → 重载扩展 → 已打开页面刷新重试，重点覆盖"扩展重载后旧页面"这一条。
记录每处平台特判（如getSiteDocumentUrlPatterns对 CDN 域名的展开），让"为什么这里要特殊处理"在代码里可查。