ResourceOverride 扩展实用故障排查指南：从现象分析到解决方案

一、请求拦截失效问题：从配置到网络的全链路诊断

现象描述

当配置资源替换规则后，浏览器仍加载原始资源，开发工具 Network 面板中无拦截记录，控制台无任何错误提示。此问题在 Chrome 90+ 版本及 Edge 基于 Chromium 内核的浏览器中较为常见。

诊断流程

1. 检查 manifest.json 文件中的权限声明，确认包含 "webRequest"、"webRequestBlocking" 及目标域名权限
2. 通过 chrome://extensions/ 页面查看扩展是否处于启用状态，尝试切换开关重新激活
3. 在开发者工具的 Background Page 中检查 background.js 的运行日志，过滤关键词 onBeforeRequest
4. 使用 src/background/requestIdTracker.js 提供的请求跟踪工具，生成请求流水日志

实施步骤

初级方案：基础配置检查

1. 验证规则匹配模式是否正确，确保 URL 模式包含通配符（如 *://*.example.com/*）
2. 检查规则启用状态，确认开关处于 "ON" 位置（对应 src/ui/onOffSwitch.js 组件状态）
3. 清除浏览器缓存（Ctrl+Shift+Delete）并重启扩展

进阶方案：深度调试

1. 在 src/background/match.js 中添加调试日志：

   console.log('[Match Check]', {url, pattern, result: matchUrl(url, pattern)});
   

2. 使用 src/ui/devtools.js 打开专用调试面板，监控规则匹配过程
3. 检查 src/background/requestHandling.js 中的优先级逻辑，确认自定义规则未被默认规则覆盖

专家方案：底层拦截机制修复

1. 检查 manifest.json 中的 manifest_version 是否为 3，V3 版本需使用 declarativeNetRequest API
2. 对于复杂匹配场景，实现 src/background/match.js 中的高级匹配算法扩展
3. 使用 chrome.webRequest.onBeforeSendHeaders 事件代替 onBeforeRequest 提升拦截优先级

验证方法

1. 访问测试页面，观察开发者工具 Network 面板中资源的 initiator 列是否显示 ResourceOverride
2. 使用 src/ui/headers.js 提供的响应头查看工具，确认 X-Resource-Override: modified 标记存在
3. 对比修改前后的资源内容，可通过 src/ui/editor.js 内置的差异对比功能实现

[!WARNING] 常见误区

• 混淆匹配模式中的 * 与 ** 用法，** 仅在 manifest v3 的 declarative_net_request 中支持
• 未考虑 HTTPS 站点的混合内容限制，需在规则中同时包含 http 和 https 协议
• 过度使用通配符导致规则冲突，建议使用 src/util.js 中的 ruleValidator 工具检测规则有效性

预防措施

1. 定期使用 src/ui/importExport.js 导出规则备份，避免配置丢失
2. 在 src/background/init.js 中添加启动自检逻辑，验证关键 API 可用性
3. 关注 maintenance_notice.md 中的兼容性公告，及时了解浏览器版本适配信息

二、编辑器功能异常：从界面到核心逻辑的修复方案

现象描述

规则编辑界面加载失败，表现为 Ace 编辑器区域空白或显示 "Loading..." 状态，控制台提示 Uncaught ReferenceError: ace is not defined 错误。此问题多发生在首次安装或版本升级后。

诊断流程

1. 检查 lib/ace/ 目录下核心文件完整性，确认 ace.js 及对应语言模式文件存在
2. 通过浏览器开发者工具的 Network 面板，过滤 ace 关键词，检查资源加载状态
3. 查看 src/ui/editor.js 中的初始化代码，确认 DOM 元素加载顺序是否正确

实施步骤

初级方案：资源加载修复

1. 清除浏览器扩展缓存：chrome://settings/clearBrowserData → 勾选 "扩展程序数据"
2. 验证 lib/ace/ 目录结构完整性，必要时从项目仓库重新获取相关文件
3. 在 src/ui/editor.js 中添加资源加载超时处理：

   setTimeout(() => {
     if (typeof ace === 'undefined') {
       console.error('Ace editor failed to load');
       document.getElementById('editor-container').innerHTML = '编辑器加载失败，请刷新页面重试';
     }
   }, 3000);
   

进阶方案：依赖管理优化

1. 修改 src/ui/devtools.html 中的脚本加载顺序，确保 jquery-3.4.1.min.js 在 ace.js 之前加载
2. 实现 src/ui/init.js 中的动态加载逻辑，使用 Promise 确保依赖加载完成：

   loadScript('lib/ace/ace.js').then(() => {
     loadScript('lib/ace/mode-css.js').then(initEditor);
   });
   

3. 在 manifest.json 中配置 web_accessible_resources，确保 Ace 资源可被扩展访问

专家方案：编辑器核心替换

1. 评估替换为轻量级编辑器（如 CodeMirror）的可行性，修改 src/ui/editor.js 适配新编辑器 API
2. 实现编辑器资源的按需加载机制，仅在需要时加载对应语言模式文件
3. 添加离线使用支持，将 Ace 核心资源打包为 src/ui/offline-resources.js

验证方法

1. 新建规则并切换不同语言模式（CSS/HTML/JavaScript），确认语法高亮正常工作
2. 使用 src/ui/beautify.min.js 提供的格式化功能，测试代码美化效果
3. 检查编辑器工具栏按钮（保存/撤销/格式化）功能是否正常响应

[!WARNING] 常见误区

• 直接修改 lib/ace/ 目录下的源码文件，导致版本升级时冲突
• 未处理编辑器容器的 CSS 样式冲突，导致编辑器尺寸异常
• 忽略 lib/ace/worker-*.js 文件的加载，导致语法检查功能失效

预防措施

1. 在 test/ 目录下添加编辑器加载测试用例，使用 matchTest.js 框架验证核心功能
2. 定期检查 lib/ 目录下第三方库的版本更新，在 todo.txt 中记录更新计划
3. 实现 src/ui/util.js 中的资源完整性校验函数，启动时自动检查关键文件

三、规则同步异常：存储与同步机制的深度修复

现象描述

自定义规则在浏览器重启后丢失，或在不同设备间同步时出现规则不完整现象。控制台可能出现 QuotaExceededError 或 SyncError 相关错误信息。

诊断流程

1. 检查 src/background/mainStorage.js 中的存储策略，确认使用 chrome.storage.sync 还是 local
2. 通过 chrome://sync-internals/ 页面检查扩展数据同步状态
3. 查看 src/background/keyvalDB.js 中的数据读写日志，定位异常发生的操作点

实施步骤

初级方案：存储方式切换

1. 在 src/background/init.js 中修改存储初始化逻辑：

   // 从 sync 切换到 local 存储
   const storage = chrome.storage.local;
   

2. 使用 src/ui/importExport.js 功能导出当前规则，清除存储后重新导入
3. 检查 manifest.json 中的 permissions 是否包含 "storage" 权限声明

进阶方案：存储优化

1. 实现 src/background/mainStorage.js 中的数据压缩功能，减少存储占用：

   function compressRules(rules) {
     return JSON.stringify(rules).replace(/\s+/g, '');
   }
   

2. 拆分大型规则集，使用 src/background/util.js 中的 chunkArray 函数分批存储
3. 添加存储容量监控，在 src/ui/options.js 中显示剩余存储空间

专家方案：高级同步策略

1. 实现基于 src/background/tabUrlTracker.js 的上下文感知同步，仅同步当前域名相关规则
2. 开发增量同步机制，通过 src/background/keyvalDB.js 记录规则版本号
3. 集成 IndexedDB 存储方案，在 src/background/mainStorage.js 中实现多级存储策略

验证方法

1. 保存规则后重启浏览器，检查规则列表是否完整
2. 使用不同设备登录同一 Chrome 账户，验证规则同步情况
3. 在 src/ui/importExport.js 中导出规则文件，检查文件内容与数量是否匹配

[!WARNING] 常见误区

• 过度依赖 chrome.storage.sync 的容量限制（默认 100KB），未考虑规则数量增长
• 在 src/background/keyvalDB.js 中使用同步 API 导致主线程阻塞
• 未处理存储操作的异步特性，导致数据读写顺序混乱

预防措施

1. 在 src/background/mainStorage.js 中添加自动备份功能，定期导出规则到本地
2. 实现存储错误监控，在 src/ui/options.js 中显示同步状态指示器
3. 在 README.md 中添加存储策略选择指南，根据规则数量推荐合适的存储方式

问题排查决策树

1. 问题类型判断

   • 资源未被替换 → 进入 "请求拦截失效" 流程
   • 编辑器功能异常 → 进入 "编辑器功能异常" 流程
   • 规则丢失或同步问题 → 进入 "规则同步异常" 流程

2. 环境检查

   • 浏览器版本是否支持（Chrome ≥ 88，Edge ≥ 88）
   • 扩展是否拥有必要权限（通过 chrome://extensions/ 检查）
   • 其他扩展是否冲突（尝试禁用其他网络相关扩展）

3. 快速修复尝试

   • 重启浏览器扩展
   • 清除扩展数据
   • 重新安装扩展

4. 深度排查

   • 查看背景页日志（chrome://extensions/ → 点击 "背景页" 链接）
   • 检查网络请求（开发者工具 Network 面板，过滤 ResourceOverride）
   • 验证规则配置（使用 src/ui/util.js 中的 validateRule 函数）

扩展资源与支持

问题反馈渠道

• 项目 Issue 提交：使用项目根目录中的 ISSUE_TEMPLATE 模板
• 社区讨论：通过项目讨论区交流使用经验和问题解决方案

学习资源

• 基础使用教程：参考项目 README.md
• 高级规则编写：查看 src/examples/ 目录下的规则示例
• API 文档：src/docs/api.md（如存在）

开发资源

• 扩展调试指南：src/debugging-guide.md（如存在）
• 贡献代码：参考 CONTRIBUTING.md（如存在）
• 测试用例：test/ 目录下的自动化测试脚本