基于 puppeteer-extra-plugin-stealth 的 `_template` 模板开发自定义反检测插件实战指南

原创2026-10-14 18:33:00598 阅读
文章标签:浏览器控制插件系统开发工具网页爬虫测试

基于 puppeteer-extra-plugin-stealth 的 _template 模板开发自定义反检测插件实战指南

本文以 packages/puppeteer-extra-plugin-stealth/evasions/_template 目录下的官方模板为起点,讲解如何在 puppeteer-extra 体系中从零编写一个可独立运行的"反检测 evasion 插件"。读完本文,你将掌握最小插件骨架的每一行代码、PuppeteerExtraPlugin 基类的生命周期钩子、共享工具库 _utils 的正确用法,并能参照 navigator.webdriver、chrome.app 等真实 evasion 的实现,快速复制模板目录并开发出自己的新反检测方案。

模板的本质:一个最小的反检测插件骨架

_template 是 puppeteer-extra-plugin-stealth 官方提供的最小可运行插件模板,官方对其定位非常直白(见 模板 readme):

Minimal stealth plugin template, not being used. :-) Feel free to copy this folder as the basis for additional detection evasion plugins.

翻译过来就是:这个模板本身并不参与实际反检测("not being used"),它的用途是作为"复制即用"的起点——当你发现一个新的 headless 可探测特征、想为 stealth 插件贡献一条新 evasion 时,直接复制整个 _template 文件夹,改一改类名、插件名和 onPageCreated 里的注入逻辑即可。这也是 stealth 主插件官方建议的贡献路径:主插件 index.js 的注释明确写着 "if you want to add a new evasion technique I suggest you look at the template to kickstart things"。

一个完整的 evasion 插件目录由三部分构成:

文件 作用
index.js 插件本体,继承 PuppeteerExtraPlugin 并实现生命周期钩子
readme.md 由 documentation.js 自动生成的 API 文档(npm run docs 会更新它)
package.json 声明 main: index.js 与 private: true(见 模板 package.json)

目录结构可参照真实的 navigator.plugins evasion(navigator.plugins 目录):除了 index.js,还按需附带 mimeTypes.js、plugins.js、magicArray.js、data.json 等拆分文件与配套测试。

模板源码逐行拆解

模板的完整实现位于 evasions/_template/index.js,全文件仅 28 行,结构如下:

'use strict'

const { PuppeteerExtraPlugin } = require('puppeteer-extra-plugin')

/**
 * Minimal stealth plugin template, not being used. :-)
 *
 * Feel free to copy this folder as the basis for additional detection evasion plugins.
 */
class Plugin extends PuppeteerExtraPlugin {
  constructor(opts = {}) {
    super(opts)
  }

  get name() {
    return 'stealth/evasions/_template'
  }

  async onPageCreated(page) {
    await page.evaluateOnNewDocument(() => {
      console.debug('hello world')
    })
  }
}

module.exports = function(pluginConfig) {
  return new Plugin(pluginConfig)
}

第一行:严格模式

'use strict' 是 stealth 插件家族所有实现(navigator.webdriver、chrome.app、navigator.plugins 等)的统一开头。由于这些代码最终会通过 page.evaluateOnNewDocument 注入浏览器页面上下文,保持严格模式能避免一些隐蔽的静默错误。

类的骨架与 opts 传递

class Plugin extends PuppeteerExtraPlugin {
  constructor(opts = {}) {
    super(opts)
  }

PuppeteerExtraPlugin 来自独立包 puppeteer-extra-plugin(stealth 的依赖声明见 package.json)。它的构造函数会做一件关键的事:把插件定义的 defaults 与用户传入的 opts 做深合并,合并结果保存在 this.opts 中,插件运行期通过 this.opts.xxx 读取配置(见 src/index.ts 的 _opts = merge(this.defaults, opts || {}))。

name:插件的全局唯一标识

get name() {
  return 'stealth/evasions/_template'
}

name 是 PuppeteerExtraPlugin 基类要求每个插件必须覆写的属性(基类默认实现会直接抛错:Plugin must override "name",见 src/index.ts)。它同时承担三个职责:

  • 调试命名空间:this.debug() 的日志会以 puppeteer-extra-plugin:${name} 为前缀输出,可用 DEBUG=puppeteer-extra-plugin:<插件名> 环境变量开关(见 src/index.ts);
  • 依赖解析:stealth 主插件通过 dependencies getter 把启用列表映射为 stealth/evasions/<名字> 形式的依赖名(见 stealth index.js),puppeteer-extra 会自动 require() 缺失的依赖(见 src/index.ts);
  • 事件绑定去重:基类用 _hasChildClassMember 检查子类是否真的实现了某个钩子,再决定是否注册对应的事件监听(见 src/index.ts)。

命名惯例上,真实 evasion 采用 stealth/evasions/<目录名> 格式,例如 stealth/evasions/navigator.webdriver、stealth/evasions/chrome.app。复制模板后第一件事就是把这里改成你的新 evasion 名称。

onPageCreated:反检测逻辑的注入点

async onPageCreated(page) {
  await page.evaluateOnNewDocument(() => {
    console.debug('hello world')
  })
}

这是模板的灵魂所在。onPageCreated 是基类提供的生命周期钩子之一:当浏览器创建新页面(包括 window.open、browser.newPage、隐身上下文中的页面)时被调用,且已由基类预先过滤为 page 类型 target(见 src/index.ts)。基类通过监听 puppeteer 的 targetcreated 事件触发它。

page.evaluateOnNewDocument 保证注入脚本在页面任何脚本执行之前运行——这正是 stealth 反检测"先下手为强"的关键:在页面自身的检测代码运行前,先把 navigator.webdriver、window.chrome 等特征改写掉。真实插件对这一点利用得淋漓尽致,例如:

模块导出:工厂函数模式

module.exports = function(pluginConfig) {
  return new Plugin(pluginConfig)
}

模板采用工厂函数而不是直接导出类实例,这是 stealth 插件家族的统一约定(所有 evasion 的 index.js 末尾都是这个模式)。这样做的原因在于 opts 的延迟注入:调用方写成 require('...')({ userAgent: '...' }),参数在实例化时才传入并参与 defaults 合并。默认参数 opts = {} 在构造函数签名中已给出(文档中标注 "opts (optional, default {})"),确保无参调用也能工作。

生命周期钩子:一个 evasion 能用到哪些时机

PuppeteerExtraPlugin 基类为插件提供了完整的一套钩子,覆盖浏览器从启动到关闭的全过程(全部为可选实现,见 src/index.ts):

钩子 触发时机 典型用途
beforeLaunch(options) 新浏览器启动前 修改 puppeteer 启动参数(如追加 --disable-blink-features=AutomationControlled)
afterLaunch(browser, opts) 浏览器启动后 获取浏览器实例引用
beforeConnect(options) puppeteer.connect() 前 修改连接参数
afterConnect(browser, opts) 连接建立后 处理已连接浏览器
onBrowser(browser, opts) launch/connect 任一方式拿到浏览器时 统一处理两种来源
onTargetCreated(target) 新 target 创建 处理任意类型 target
onPageCreated(page) 新页面创建 注入反检测脚本(模板核心)
onTargetChanged(target) / onTargetDestroyed(target) target 变化/销毁 状态清理
onDisconnected() 与浏览器断开 清理资源
onPluginRegistered() puppeteer.use() 注册后 初始化

配套还有三个配置类 getter(见 src/index.ts):

  • defaults:插件默认配置,与用户 opts 深合并;
  • requirements:声明 launch(不支持 connect)、headful(不支持 headless)、dataFromPlugins、runLast 等需求,供基类向用户告警或调整执行顺序;
  • dependencies:声明依赖的其他插件,缺失时由 puppeteer-extra 自动加载。

模板只用了 onPageCreated 这一个钩子,但真实 evasion 常常组合多个。最典型的例子是 user-agent-override/index.js:它同时实现了 onPageCreated(通过 CDP 的 Network.setUserAgentOverride 设置 UA 与平台)、beforeLaunch(记录是否 headless)、beforeConnect(把 connect 方式视为 headless)以及 data(向 user-preferences 插件提供语言偏好数据),还声明了 dependencies: new Set(['user-preferences'])。

使用共享工具库 _utils:让 mock 不留痕迹

模板为了保持"最小",直接用了裸 page.evaluateOnNewDocument。但 stealth 家族约 16 个 evasion(完整清单见 stealth/index.js 的 availableEvasions)中,大部分改写在技术上有一个共性痛点:直接 Object.defineProperty 或 new Proxy 会留下可被反检测的蛛丝马迹,例如:

  • Proxy 会出现在错误堆栈里(at Reflect.get、at Object.get 等行);
  • 被替换函数的 toString() 结果不再是 function xxx() { [native code] };
  • 新增属性会出现在 Object.getOwnPropertyNames 枚举中。

puppeteer-extra-plugin-stealth/evasions/_utils 目录正是为消除这些痕迹而生的共享工具箱:

  • _utils/index.js:核心工具函数集合,包括 stripProxyFromErrors(剥离 Proxy 错误堆栈)、replaceProperty(基于原有 descriptor 安全替换属性)、patchToString / redirectToString(伪造原生 toString 结果)、replaceWithProxy / replaceGetterWithProxy / replaceGetterSetter / mockWithProxy / createProxy(带反检测的 Proxy 包装)、preloadCache / makeNativeString(缓存原生 toString 字符串以防被二次嗅探)、stringifyFns / materializeFns(函数在 Node 与浏览器上下文间传递)、memoize 等;
  • _utils/withUtils.js:对 page 的轻量封装,提供 page.evaluate 和 page.evaluateOnNewDocument 的"带工具版",把 _utils 里的函数序列化后注入页面上下文,页面内通过 utils 参数直接调用。

一个使用 withUtils 的典型实现是 chrome.app/index.js:

async onPageCreated(page) {
  await withUtils(page).evaluateOnNewDocument(utils => {
    // headless 下 window.chrome 不存在,按 headful 的真实 descriptor 定义
    Object.defineProperty(window, 'chrome', {
      writable: true,
      enumerable: true,
      configurable: false,
      value: {}
    })
    // ... 构造 chrome.app 的静态数据与方法 mock
    utils.patchToStringNested(window.chrome.app) // 让所有 mock 函数看起来是原生代码
  })
}

navigator.plugins evasion(navigator.plugins/index.js)则展示了"函数与数据分离"的进阶写法:把 generateMimeTypeArray、generatePluginArray 等生成函数用 utils.stringifyFns 序列化后随 data(来自 data.json)一起作为 evaluateOnNewDocument 的参数传入,页面内再用 utils.materializeFns 还原——既保持了代码结构清晰,又绕过了 page.evaluate 无法直接传函数的序列化限制。

开发建议:如果你的新 evasion 需要改写原生 API(而不是像模板那样仅仅打印日志),请务必复制 _template 后改用 withUtils(page).evaluateOnNewDocument(...) 模式,并复用 _utils 中已有的工具,避免"能用但会被检测出来"的半成品实现。

实战:如何把模板变成你自己的 evasion

参照官方在 evasions/readme.md 中给出的指引("If you want to add a new evasion technique I suggest you look at the template to kickstart things"),完整开发流程如下:

第 1 步:复制模板目录

把 _template 整个复制为 evasions/<你的新名字>,并同步修改 package.json 与 readme.md。

第 2 步:改写插件名

get name() {
  return 'stealth/evasions/<你的新名字>'
}

第 3 步:实现反检测逻辑

在 onPageCreated 中实现你的检测点修复。逻辑分两种形态:

  • 直接修补类(适合简单场景),如 navigator.webdriver/index.js:
    async onPageCreated(page) {
      await page.evaluateOnNewDocument(() => {
        if (navigator.webdriver === false) {
          // Post Chrome 89.0.4339.0 and already good
        } else if (navigator.webdriver === undefined) {
          // Pre Chrome 89.0.4339.0 and already good
        } else {
          // Pre Chrome 88.0.4291.0 and needs patching
          delete Object.getPrototypeOf(navigator).webdriver
        }
      })
    }
    
    该插件还在 beforeLaunch 中向启动参数追加 --disable-blink-features=AutomationControlled(navigator.webdriver/index.js),并注释了 Linux 下去掉 Chrome 警告 infobar 的 Chrome 策略配置方法。
  • 工具库辅助类(适合 Proxy mock 场景),如 media.codecs/index.js:用 utils.replaceWithProxy(HTMLMediaElement.prototype, 'canPlayType', canPlayType) 拦截 canPlayType 调用,对 Chromium 缺失的 video/mp4; codecs="avc1.42E01E"、audio/x-m4a、audio/aac 返回 'probably' / 'maybe'。

第 4 步:编写测试(强烈建议)

stealth 插件的测试体系由 ava 驱动(测试脚本见 package.json),并提供了一组指纹采集工具 test/util.js:getVanillaFingerPrint 用原生 puppeteer 采集指纹、getStealthFingerPrint 用 addExtra(vanillaPuppeteer).use(Plugin()) 采集加了你的 evasion 之后的指纹,两者对比即可验证效果。典型写法可参考 navigator.webdriver/index.test.js:先断言 vanilla 下 navigator.webdriver === true,再断言 stealth 下等于 false(Chrome ≥ 89.0.4339.0)或 undefined(更早版本),并附带回归测试确认不会误伤其他 navigator 方法。

第 5 步:独立使用或并入 stealth 主插件

新 evasion 本身就是一个标准的 puppeteer-extra 插件,可以独立使用:

const puppeteer = require('puppeteer-extra')
puppeteer.use(require('puppeteer-extra-plugin-stealth/evasions/<你的新名字>')())

如果想并入 stealth 全家桶,则需要两步(见 stealth/index.js):把新名字加入 defaults 中的 availableEvasions Set(第 82-99 行),enabledEvasions 默认复制全部可用项(第 103 行),这样 dependencies 就会自动生成对应的依赖名并由 puppeteer-extra 动态加载(第 112-116 行)。

常见问题与注意事项

  1. 不要用 page.setUserAgent() 与 stealth 的 UA 处理混用:user-agent-override 插件注释明确警告,常规的 page.setUserAgent() 会重置插件设置的语言与平台值(见 user-agent-override/index.js)。同理,开发新 evasion 时要意识到 stealth 各插件之间是协同关系,避免互相覆盖。
  2. evaluateOnNewDocument 里不能直接用 Node 侧闭包变量:需要通过 withUtils 的参数机制或 stringifyFns 序列化传递,这是 _utils 存在的重要原因。
  3. 保持模块化与最小依赖:stealth 主插件的设计哲学是"只加载启用的 evasion"(见 stealth/index.js 的 Modularity 说明)。你的新插件应尽量自包含,必要时才声明 dependencies。
  4. documentation.js 注释驱动文档:readme.md 由 npm run docs(内部执行 documentation readme --shallow,见 package.json)从 index.js 的 JSDoc 注释自动生成。给类和方法写规范的 JSDoc,readme.md 的 API 段才会完整。
  5. 版本与场景边界:本仓库 puppeteer-extra-plugin-stealth 版本为 2.11.2,引擎要求 Node >= 8(见 package.json);各 evasion 的实现细节(如 navigator.webdriver 对不同 Chrome 版本的分支处理)以源码注释为准,实际效果随 Chrome 版本演进可能变化。

总结

_template 虽只有 28 行代码,却完整定义了 stealth evasion 插件的标准形态:继承 PuppeteerExtraPlugin、覆写 name、在 onPageCreated 中通过 evaluateOnNewDocument 抢先注入补丁、以工厂函数导出。从它出发,你可以对照 _utils 工具箱与 navigator.webdriver、chrome.app、navigator.plugins、media.codecs 等真实实现,快速产出一个既模块化、又经得起指纹检测对比测试的新反检测插件——这正是 puppeteer-extra 社区持续扩展 stealth 能力的标准路径。

登录后查看全文
puppeteer-extra