anti-debug

浏览器端防调试 / 降低窥探便利度的轻量工具库（TypeScript）。通过启发式检测「调试器暂停」与「DevTools 可能已打开」，并在命中时回调业务逻辑；可选弱化 console 输出。

重要：前端代码无法做到不可被逆向或不可被阅读。本库仅提高成本，不能替代服务端鉴权、密钥不下发、构建混淆、关闭生产 Source Map 等工程措施。

功能概览

| 能力 | 说明 | | --- | --- | | 定时守护 | startAntiDebugGuard 按间隔执行多项检测，命中时调用 onThreat(reason) | | debugger 耗时 | detectDebuggerTiming：利用 debugger 断点处前后时间差异常 | | 窗口 / 视口 | detectDevToolsByDimensions：outer-inner + 根元素 / visualViewport 差值（不依赖断点） | | console 耗时（可选） | detectDevToolsByConsoleTiming：DevTools 打开时常更慢（默认关，防误报） | | 本机跳过 | skipInDevelopment + isLikelyLocalDevHost，避免本地开发时被频繁打断 | | noop console | installNoopConsole：可选替换常见 console.* 为空实现 | | 快捷键 / 右键 | installDevToolsUiBlock 或 startAntiDebugGuard({ uiBlock: true })：拦 F12、Ctrl+Shift+I/J/C 等；可选拦右键、Ctrl+U |

安装

在 monorepo 中依赖工作区包（示例）：

{
  "dependencies": {
    "anti-debug": "workspace:*"
  }
}

pnpm add anti-debug@workspace:* -F your-app

快速开始

import { startAntiDebugGuard, installNoopConsole } from "anti-debug"

// 可选：弱化控制台（记得在需要调试时注释掉或条件编译）
const restoreConsole = installNoopConsole()

const guard = startAntiDebugGuard({
  intervalMs: 2500,
  // 本地 localhost 不跑守护，正式域名照常检测
  skipInDevelopment: true,
  // 拦 F12、Ctrl+Shift+I/J/C 等；默认不拦整页右键，需则传 { blockContextMenu: true }
  uiBlock: true,
  onThreat(reason) {
    // reason: 'debugger-timing' | 'devtools-dimensions' | 'devtools-console-timing'
    // 自行实现：跳转、清 DOM、上报等（本库不内置网络请求）
    window.location.replace("/")
  },
})

// 单页应用卸载或不再需要时
// guard.stop();
// restoreConsole();

API 说明

startAntiDebugGuard(options?)

• 环境：仅在存在 window 的浏览器中启动 setInterval；Node / 无 window 时返回 { stop: () => {} }，不抛错。
• intervalMs：轮询间隔，默认 2000。
• immediate：是否在挂载后立即执行第一次检测，默认 true。
• skipInDevelopment：为 true 且当前 hostname 为常见本机地址（见下）时，不启动守护。
• checks：可关闭 debuggerTiming / devToolsDimensions；devToolsConsoleTiming 默认关闭，需显式 true。
• devToolsThresholds：微调 widthGap / heightGap / layoutGap / consoleTimingMs（漏报时可略调低前两项）。
• uiBlock：true 或 DevToolsUiBlockOptions 对象；与 skipInDevelopment 同时生效时，本机 hostname 下不安装（与轮询一致）。stop() 时会一并卸载快捷键监听。
• onThreat(reason)：有检测为阳性时调用；未传则仅轮询，不执行任何默认破坏操作。

AntiDebugReason（reason 取值）

| 值 | 含义 | | ------------------------- | -------------------------------------------------------- | | debugger-timing | detectDebuggerTiming 认为执行在断点/调试器下被显著拖慢 | | devtools-dimensions | 视口 / 尺寸启发式认为像已打开 DevTools（dock 场景为主） | | devtools-console-timing | 可选；console 单次调用耗时偏高（与「停用断点」无关） |

detectDebuggerTiming(thresholdMs?)

• 默认 thresholdMs = 120。耗时超过该值返回 true。
• 内含 debugger 语句：若被 ESLint 禁止，需在项目规则中对本库或本行做例外。

detectDevToolsByDimensions(options?) 或 (widthGap, heightGap)

• 对象形式：可传 widthGapThreshold、heightGapThreshold、layoutGapThreshold（默认 160 / 300 / 100），并包含对 innerWidth - clientWidth、visualViewport 与内视口的辅助判断。
• 两数字形式：与旧版兼容，等价于仅调整 outer-inner 阈值。
• 「停用断点」：不会执行 debugger，故 debugger-timing 会漏报；可依赖本项与可选的 detectDevToolsByConsoleTiming。
• DevTools 独立窗口 undock 时主页面尺寸往往不变 → 纯前端无法可靠检测，只能依赖服务端或其它手段。

detectDevToolsByConsoleTiming(thresholdMs?)

• 默认 5 ms；仅建议在 checks: { devToolsConsoleTiming: true } 时由守护调用；单独使用亦可。
• 可能有误报，请结合业务与 devToolsThresholds.consoleTimingMs 调整。

isLikelyLocalDevHost()

在 location 存在时，匹配：localhost、127.0.0.1、[::1]、0.0.0.0，以及以 .local 结尾的主机名。

installNoopConsole(options?)

• 默认替换常见输出类方法；返回卸载函数，务必在测试或需要控制台时调用恢复。

installDevToolsUiBlock(options?)

• 在 window 上注册捕获阶段 keydown，默认拦截：F12；Ctrl+Shift+I/J/C/K/E（Windows/Linux）；Cmd+Option+I/J/C、Cmd+Shift+C（Mac 常见）。
• 可选：blockContextMenu: true 拦截整页右键；blockViewSource: true 拦截 Ctrl+U 查看源代码。
• 无法拦截：浏览器菜单「更多工具 → 开发者工具」、扩展、远程调试、从书签/其它页已打开的 DevTools 等。
• 返回卸载函数；也可通过 startAntiDebugGuard({ uiBlock: true }) 自动安装并在 stop() 时卸载。

局限与误报

1. 「Deactivate breakpoints / 停用断点」与「Resume」：debugger 不暂停时，debugger-timing 必然漏报——这是浏览器行为，不是库 bug。请依赖 devtools-dimensions，并视情况开启 devToolsConsoleTiming 或调低 devToolsThresholds.widthGap / heightGap。
2. DevTools 独立窗口：主页面 outer/inner 可能不变 → 尺寸类检测常漏报；纯前端无完美对策。
3. 尺寸 / console 检测：分屏、缩放、扩展、省电模式等 → 误报或漏报均可能存在。
4. 性能：轮询与 debugger / console 检测占用主线程，间隔不宜过小。
5. 合规与体验：过度惩罚可能伤害正常用户；请谨慎设计 onThreat。
6. 快捷键拦截：仅挡常见快捷键；无障碍与高级用户仍可通过菜单或其它方式打开 DevTools，勿当作安全边界。

构建

pnpm --filter anti-debug build
pnpm --filter anti-debug check-types

产物目录 dist/ 仅两个文件（单文件分发）：

• index.js：单入口 rolldown 打成一个 chunk，再经 javascript-obfuscator 处理；
• index.d.ts：dts-bundle-generator 自 src/index.ts 合并生成的单文件类型声明（与 package.json 的 types / exports 对齐）。

构建开始时会清空 dist/，避免历史构建遗留的多份 .d.ts。

若根目录 .gitignore 忽略了 dist/，则构建产物不入库；克隆后需先执行 pnpm --filter anti-debug build，依赖方才能解析类型与运行时代码。

压缩与混淆说明

1. Rolldown（Oxc Minifier）：minify 开启完整压缩与名称混淆；必须设置 compress.dropDebugger: false，否则默认会删除源码中的 debugger，detectDebuggerTiming 会失效。
2. javascript-obfuscator：对打包结果做字符串阵列、Base64 编码等增强混淆；未开启控制流平坦化/自防御等，以降低体积与误伤风险。

若只需 Rolldown 压缩、不要第二层混淆，可将 package.json 中 build 改为仅 rolldown -c。

与其他措施的关系

| 措施 | 说明 | | ---- | ---------------------------------------- | | 本库 | 运行时启发式，可组合埋点与温和响应 | | 构建 | 压缩、混淆、关闭生产 Source Map | | 架构 | 敏感逻辑与密钥放在服务端；前端仅展示结果 | | 合规 | 遵循当地法律与用户协议，勿用于恶意目的 |

许可证

ISC（与 package.json 保持一致）。