快速开始#

环境要求#

• Node.js >= 22（推荐使用 mise 管理，仓库已提供 mise.toml）
• pnpm 9

安装依赖#

mise exec -- pnpm install

本地开发#

# 启动插件开发模式（自动打开带插件的 Chrome）
mise exec -- pnpm dev

# 启动文档站
mise exec -- pnpm dev:docs

构建#

# 构建全部（插件 + 文档站）
mise exec -- pnpm build

插件产物位于 apps/extension/.output/chrome-mv3/，可在 chrome://extensions 开启开发者模式后「加载已解压的扩展程序」。

创建第一条规则#

1. 点击浏览器工具栏中的插件图标，打开 popup
2. 点击「管理规则」进入规则管理页
3. 点击「+ 返回值 Mock」创建示例规则，按需修改匹配模式后勾选启用

撤销与重做规则修改#

规则管理页顶栏提供撤销与重做按钮。新建、编辑、删除、启停、排序、导入以及 popup 中的快速启停都会进入同一条配置历史。

• macOS：⌘Z 撤销，⌘⇧Z 重做
• Windows / Linux：Ctrl+Z 撤销，Ctrl+Shift+Z 或 Ctrl+Y 重做

规则编辑弹窗尚未保存时，输入框和代码编辑器保留各自的文本撤销历史；点击「保存」后才产生一条配置级历史。历史保存在当前浏览器会话中，最多保留最近 50 份配置快照，浏览器会话结束后自动清除。

查看规则命中#

规则动作执行后，扩展图标徽标会立即点亮一个小圆点，表示当前标签页有规则生效。全局停用时，所有标签页的徽标改为 OFF。徽标只表达状态，不显示数字。

打开 popup 可以看到细节：

• 顶部显示本页命中过的规则条数（按规则去重，同一规则触发多次只算一条）。已删除的规则不计入，删除后这个数字会相应减少。
• 命中过的规则会带一层很淡的主色底，并在右侧显示一个主色定位图标；未命中的规则不作任何标记。
• 点击任意规则名即可进入规则管理页并自动定位、高亮该规则。
• 「清空」按钮会重置当前标签页的命中日志、规则标记与图标徽标。
• popup 打开期间会随页面的新请求自动刷新（约 1 秒一次），不需要关掉重开。
• 同一位置若出现黄色禁止图标，表示该规则匹配上了但没能应用：不透明响应（no-cors）读不到响应体、同步 XHR 容不下异步处理，这两种情况下扩展一律原样放行。悬停可看到具体原因。这类记录不计入命中，也不会点亮图标徽标。
• 同一位置若出现红色警告图标，表示该规则未被浏览器接受：DNR 规则由浏览器校验，不合法的会被拒绝、当前完全不生效。鼠标悬停可看到浏览器给出的原始报错；在规则管理页里，具体是哪个动作被拒绝会直接标在动作标签上。这类规则不会产生命中，看到「没命中」时先确认有没有这个警告。

想知道具体是哪个请求触发了规则，点规则管理页顶部的「命中记录」统计卡片进入请求日志：那里逐条列出时间、方法、请求 URL、命中规则与执行结果，详见请求日志。

命中日志在顶层导航开始时自动清空，Hash 与 SPA 同文档跳转不会重置；主文档被规则重定向属于同一次导航，命中会保留到跳转后的页面。

iframe 内部的请求只有 DNR 通道的规则会命中并计入；页面补丁通道（Mock、网络限速、改请求体、脚本注入）只作用于顶层文档，在子框架内不生效，因此也不会产生命中，详见已知限制。

单个标签页最多保留最近 1000 条命中；超出后会丢弃最早的记录并在 popup 中提示。

同时最多保留 30 个标签页的命中日志，超出后整份丢弃最久未更新的那个标签页 —— 被丢弃的标签页统计归零，但不会出现某个标签页只剩半截数据的情况。