1. 项目概述：为什么你的Playwright脚本总被“抓包”？

如果你正在用Playwright做自动化测试或者数据采集，大概率遇到过这个头疼的问题：脚本跑得好好的，突然就被目标网站识别为机器人，然后弹出一个验证码，或者干脆直接拒绝访问。你可能会纳闷，我明明用的是真实的浏览器内核，操作也模拟了人类行为，怎么就被发现了呢？这背后，是一场自动化脚本与网站反爬虫/反机器人系统之间持续不断的“猫鼠游戏”。

网站的反检测技术，远不止是检查你是否用了无头模式那么简单。它们会通过一系列复杂的“指纹”来识别浏览器环境。这些指纹包括但不限于：浏览器暴露的navigator.webdriver属性、用户代理字符串中是否包含“Headless”字样、浏览器支持的插件列表、WebGL渲染器信息、字体列表、屏幕分辨率与色彩深度，甚至是你执行JavaScript时的细微时间差异。一个原生的、未经任何修饰的Playwright浏览器实例，就像是一个穿着标准制服的士兵走进了平民区，特征太明显了，很容易被“哨兵”一眼识破。

playwright-stealth这个库，就是为了解决这个问题而生的。它的目标不是让你变成“隐形人”，而是把你这个“士兵”的制服换掉，抹去那些过于标准的特征，让你看起来更像一个普通的、由真人操作的浏览器。它通过一系列精妙的技术手段，修改浏览器运行时的各种属性和行为，从而有效规避目前市面上大多数常见的检测手段。简单来说，它让你的自动化脚本从“一眼假”变得“以假乱真”。

这篇文章，我将结合自己多年在自动化领域的实战经验，为你拆解playwright-stealth的方方面面。从它的核心工作原理，到一步步的集成配置，再到高级的定制技巧和实战中遇到的“坑”，我都会毫无保留地分享出来。无论你是刚接触Playwright的新手，还是已经饱受检测困扰的老手，这篇文章都能帮你构建起一套更健壮、更隐蔽的自动化方案。

2. Playwright Stealth的核心原理深度剖析

要真正用好一个工具，必须理解它背后的原理。playwright-stealth并非魔法，它是一系列针对性防御措施的集合。它的工作方式，可以理解为在浏览器页面加载之初，就注入一系列脚本，对浏览器的原生环境进行“修补”和“伪装”。

2.1 指纹修改：从“标准兵”到“便衣”

浏览器指纹是检测的核心。playwright-stealth主要修改了以下几类关键指纹：

1. Navigator对象属性：这是最基础的检测点。原生Playwright启动的浏览器，其navigator.webdriver属性会被设置为true，明确告诉网站“我是一个被自动化工具控制的浏览器”。stealth插件会通过执行JavaScript代码，将这个属性删除或设置为undefined。此外，它还会检查并修正navigator.plugins、navigator.languages等属性，确保它们与一个有头、真人使用的浏览器一致，而不是一个空数组或默认值。

2. 用户代理字符串：当Playwright以无头模式启动Chrome或Chromium时，用户代理字符串通常会包含HeadlessChrome。例如：Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/XXX.0.0.0 Safari/537.36。这简直是自报家门。stealth插件会从用户代理中移除HeadlessChrome字样，并将其替换为普通Chrome的标识，同时确保整个字符串的格式看起来是合理的。

3. WebGL与Canvas指纹：高级检测会通过WebGL和Canvas API获取硬件和渲染信息。不同的GPU、驱动甚至操作系统，渲染出的图像会有微妙的差异。自动化浏览器环境下的渲染结果可能与真实环境不同。stealth通过重写WebGLRenderingContext.prototype.getParameter等方法，返回经过处理的、更接近大众化硬件的信息，来干扰这种基于渲染的指纹识别。

4. 音频与字体指纹：浏览器可以通过AudioContext分析音频处理的细微差异，也可以通过document.fonts检查已安装的字体列表。自动化环境下的音频处理可能被简化，字体列表也可能不完整。stealth插件会模拟这些API的返回值，提供一个看起来更“丰富”和“真实”的指纹。

注意：这里需要明确一个关键点：playwright-stealth并不是“创造”一个全新的指纹，而是“修补”现有指纹中那些过于突出、容易被标记的点。它的目标是让指纹变得普通、常见，从而融入“人群”，而不是变得独一无二。

2.2 行为模拟：不仅仅是静态伪装

除了静态属性，动态行为也是检测的重点。人类操作是有随机性和不完美性的。

1. 鼠标移动与点击：人类的鼠标移动轨迹是曲线，带有随机抖动，且移动速度不均匀。而自动化脚本的page.click()通常是瞬间、直线定位。stealth本身不直接模拟鼠标轨迹，但它为更高级的模拟铺平了道路。在实际应用中，我们通常需要结合page.mouse.move()等方法，自己实现带轨迹的移动。stealth确保的是，当你这么做时，底层环境不会暴露你是一个自动化程序。

2. 定时器与性能API：有些检测会通过performance.now()的精度，或者setTimeout、setInterval的执行偏差来判断环境。原生的浏览器环境和高精度计时器在自动化控制下可能会有可预测的模式。stealth通过修补这些时间相关的API，引入微小的、符合人类预期的随机延迟和精度变化，使得基于时间的检测失效。

3. 插件与MIME类型列表：navigator.plugins和navigator.mimeTypes在无头或自动化环境中常常是空的或只有少数几项。一个真实的浏览器通常安装了PDF查看器、Flash（虽然已淘汰）等插件。stealth会向这些列表中添加常见的、合理的条目，使其看起来像一个普通用户的浏览器配置。

2.3 与Puppeteer Stealth的渊源与差异

playwright-stealth是著名的puppeteer-extra-plugin-stealth的移植版本。两者核心思想和技术手段同源。但由于Playwright和Puppeteer在架构和API上的差异，移植并非简单复制。Playwright支持多浏览器内核，其异步处理模型也与Puppeteer略有不同。因此，playwright-stealth在实现上做了适配，以确保在Playwright的上下文中能正确、稳定地执行所有伪装脚本。

理解这一点很重要：很多针对Puppeteer Stealth的绕过技巧和讨论，同样适用于Playwright Stealth。社区的经验和解决方案在很大程度上是相通的。当你搜索疑难杂症时，不妨把搜索范围扩大到Puppeteer领域，往往能找到灵感。

3. 从零开始：Playwright Stealth的完整集成指南

理论讲完，我们进入实战。假设你现在有一个全新的项目，或者一个正在被检测困扰的现有项目，让我们一步步将playwright-stealth武装起来。

3.1 环境准备与基础安装

首先，确保你的Python环境是3.7或更高版本。创建一个干净的虚拟环境是一个好习惯，可以避免包依赖冲突。

# 创建项目目录并进入 mkdir playwright-stealth-demo && cd playwright-stealth-demo # 创建并激活虚拟环境（以Linux/macOS为例） python -m venv venv source venv/bin/activate # Windows系统使用：venv\Scripts\activate # 安装Playwright核心库 pip install playwright # 安装浏览器二进制文件（推荐安装Chromium，因为它是Stealth主要优化的对象） playwright install chromium

接下来，安装主角playwright-stealth：

pip install playwright-stealth

现在，基础的舞台就搭好了。

3.2 同步与异步API的集成

Playwright支持同步和异步两种编程模式。playwright-stealth也相应地提供了两种函数。选择哪一种，取决于你项目的主体风格。

同步模式集成：如果你的脚本是传统的同步写法，使用sync_playwright，那么导入和使用stealth_sync函数。

from playwright.sync_api import sync_playwright from playwright_stealth import stealth_sync with sync_playwright() as p: browser = p.chromium.launch(headless=True) # 通常无头模式更需要伪装 page = browser.new_page() # 关键一步：在页面执行任何导航操作之前，应用stealth插件 stealth_sync(page) page.goto("https://bot.sannysoft.com/") # 这是一个经典的自动化检测测试页 # ... 你的后续操作 browser.close()

异步模式集成：如果你的项目使用asyncio，例如在FastAPI等异步框架中调用，或者你希望获得更好的并发性能，那么使用异步模式。

import asyncio from playwright.async_api import async_playwright from playwright_stealth import stealth_async async def main(): async with async_playwright() as p: browser = await p.chromium.launch(headless=True) page = await browser.new_page() # 应用异步版本的stealth插件 await stealth_async(page) await page.goto("https://bot.sannysoft.com/") # ... 你的后续操作 await browser.close() asyncio.run(main())

实操心得：我强烈建议，无论你是否使用无头模式，都启用stealth插件。因为有头模式下的浏览器，依然会暴露navigator.webdriver等属性。启用它只有好处，没有坏处（除了极微小的性能开销）。另外，务必在page.goto()导航到目标网站之前调用stealth函数。因为伪装需要在页面环境初始化时就生效，如果先访问网站，检测脚本可能已经运行并记录了原始指纹。

3.3 验证伪装效果：使用测试页面

如何知道我们的伪装是否有效？不要直接上生产环境试错，先用专门的测试页面验证。

1. 基础测试页：https://arh.antoinevastel.com/bots/areyouheadless这个页面非常简单，只检测你是否为无头Chrome。未使用Stealth时，它会显示“You are Chrome headless”；使用后，应显示“You are not Chrome headless”。这是最基础的入门测试。

2. 综合测试页：https://bot.sannysoft.com/这是更全面、更严格的测试页面。它会同时检测数十个指标，包括WebDriver属性、用户代理、插件、语言、WebGL、字体等等，并以一个简单的表格形式给出结果。

   • 未使用Stealth：你会看到大片红色的“FAILED”和“DETECTED”。
   • 成功使用Stealth后：绝大多数，甚至全部项目都应该变成绿色的“PASSED”和“NOT DETECTED”。

将你的脚本指向这个测试页，运行并截图或打印页面内容，这是检验Stealth插件是否正常工作的黄金标准。

# 在应用stealth并导航到 bot.sannysoft.com 后，可以截图保存结果 await page.screenshot(path='stealth_test_result.png', full_page=True) # 或者获取页面文本内容进行判断 content = await page.content() if "FAILED" not in content: print("Stealth 伪装成功！") else: print("仍有部分特征被检测到，需要进一步调优。")

4. 高级配置与定制化伪装策略

默认的stealth配置已经能应对大多数中等强度的检测。但对于一些拥有顶尖风控系统的网站（例如大型电商、社交媒体平台），可能需要更精细的调整，或者需要解决一些特定问题。

4.1 自定义用户代理与视口

虽然stealth会处理用户代理，但有时你可能需要伪装成特定的浏览器版本或设备。最好在应用stealth之后，再设置这些属性，以避免冲突。

await stealth_async(page) # 设置一个常见的、非无头的用户代理 await page.set_extra_http_headers({ 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' }) # 设置一个常见的桌面端视口大小 await page.set_viewport_size({"width": 1920, "height": 1080})

注意事项：用户代理字符串的格式必须正确，且最好与你的浏览器内核（Chromium）版本大致匹配。使用一个过于老旧或未来版本的UA字符串，本身就可能成为一个可疑点。

4.2 启用浏览器上下文与更真实的启动参数

直接browser.new_page()创建的页面，其上下文相对“干净”。使用browser.new_context()可以创建一个浏览器上下文，它拥有独立的缓存、Cookie存储，更像一次独立的浏览器会话。结合一些启动参数，可以进一步增强隐蔽性。

async with async_playwright() as p: # 启动浏览器时添加一些参数 browser = await p.chromium.launch( headless=True, args=[ '--disable-blink-features=AutomationControlled', # 禁用自动化控制特征（部分版本Chrome有效） '--disable-dev-shm-usage', # 解决在Docker等环境下的资源问题 '--no-sandbox', # 沙盒模式，根据部署环境决定是否禁用 '--disable-web-security', # 禁用同源策略，仅用于特定测试，非必要勿用 '--start-maximized' # 启动时最大化（对有头模式更有意义） ] ) # 创建一个上下文，可以模拟特定设备 context = await browser.new_context( viewport={'width': 1366, 'height': 768}, user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...', locale='zh-CN', # 设置语言环境 timezone_id='Asia/Shanghai', # 设置时区 ) page = await context.new_page() await stealth_async(page) # 对从这个上下文创建的页面应用stealth # ... 后续操作

4.3 处理WebSocket与CDP（Chrome DevTools Protocol）泄露

这是一个高级话题。有些检测手段会监控浏览器与DevTools之间的WebSocket连接，或者检查是否存在CDP会话。Playwright底层是通过CDP控制浏览器的，这本身会留下痕迹。

playwright-stealth的最新版本已经包含了一些针对CDP痕迹的清理。但为了更彻底，你可以尝试在创建浏览器上下文时，避免使用某些可能暴露的API，或者使用playwright.chromium.launch_persistent_context来启动一个带有持久化用户数据目录的浏览器，这更像一个长期使用的真实浏览器。

# 使用持久化上下文示例 import os user_data_dir = "./chrome_user_data" if not os.path.exists(user_data_dir): os.makedirs(user_data_dir) browser = await p.chromium.launch_persistent_context( user_data_dir, headless=False, # 持久化上下文与无头模式有时兼容性不佳，可尝试有头 args=['--disable-blink-features=AutomationControlled'], viewport=None, # 使用默认大小 ignore_default_args=['--enable-automation'] # 忽略“自动化”相关默认参数 ) page = await browser.new_page() await stealth_async(page)

这种方法相当于你有一个“常驻”的浏览器配置文件，里面会保存历史记录、Cookie、本地存储等，指纹的稳定性更高，但也带来了状态管理的问题（需要清理Cookie等）。

5. 实战避坑：常见问题与排查技巧实录

即便装备了stealth，在实际战场上依然可能“中枪”。以下是我在长期实践中总结的常见问题和排查思路。

5.1 问题一：Stealth插件应用后，部分功能异常

现象：应用stealth后，页面上的某些JavaScript功能失效，或者点击、输入等操作没有反应。

原因与排查：stealth通过重写原生API来实现伪装。极少数情况下，这可能会与页面自身的脚本发生冲突，尤其是那些也重度依赖或检测这些API的页面。

1. 最小化复现：首先，在一个不使用stealth的脚本中测试同样的操作，确认功能本身是正常的。
2. 隔离测试：如果功能异常，尝试注释掉stealth调用，看是否恢复正常。如果恢复，则基本确定是stealth引起。
3. 检查控制台错误：在启动浏览器时添加devtools=True参数，打开开发者工具，查看Console面板是否有JavaScript报错。

   browser = await p.chromium.launch(headless=False, devtools=True)

4. 选择性禁用：playwright-stealth是由多个“规避模块”组成的。理论上可以禁用其中某个模块，但这需要你修改库的源代码，对新手不友好。更实用的方法是，考虑是否必须对这个网站使用stealth？如果该网站检测不严，或许可以不用。

5.2 问题二：特定网站仍然能检测到自动化

现象：通过了bot.sannysoft.com测试，但访问目标网站（如某电商平台）时，仍然很快被屏蔽或弹出验证码。

原因与排查：这说明目标网站使用了stealth尚未覆盖，或已绕过stealth的检测技术。风控技术在不断进化。

1. 行为检测：这是当前最主流的检测方式。你的脚本操作太快、太规律了。例如，页面加载后瞬间点击，滚动速度恒定，输入速度像打字机一样均匀。

   • 解决方案：引入随机延迟和人类化操作。

     import random import asyncio async def human_type(page, selector, text): """模拟人类打字，随机延迟""" await page.click(selector) for char in text: await page.keyboard.type(char) await asyncio.sleep(random.uniform(0.05, 0.2)) # 每个字符间随机延迟50-200毫秒 async def human_scroll(page, pixels): """模拟人类滚动，非匀速""" total = 0 while total < pixels: step = random.randint(50, 200) await page.mouse.wheel(0, step) total += step await asyncio.sleep(random.uniform(0.1, 0.5))

2. 网络请求指纹：检测请求头、TLS指纹、TCP窗口大小等底层网络特征。Playwright发起的请求，其Header顺序、默认携带的字段可能与普通浏览器有差异。

   • 解决方案：使用page.set_extra_http_headers精心设置请求头，模拟常见浏览器的Header顺序（这需要抓包分析）。更高级的方案是使用playwright的route和fetchAPI，完全接管请求过程，但这非常复杂。

3. Canvas/WebGL高级指纹：虽然stealth做了处理，但有些网站使用自研的、更复杂的Canvas指纹算法。

   • 解决方案：目前社区没有完美的通用方案。可以尝试禁用WebGL（但可能影响页面功能），或者寻找专门对抗特定算法的补丁脚本。

5.3 问题三：性能下降与超时

现象：使用stealth后，脚本执行速度明显变慢，甚至出现超时错误。

原因与排查：伪装是有成本的。注入和运行大量的JavaScript补丁代码，以及模拟人类行为引入的延迟，都会增加耗时。

1. 量化影响：对比使用stealth前后，完成相同操作所需的时间。如果只是增加20%-50%，这在可接受范围内。
2. 优化策略：
   • 仅对必要页面使用：如果自动化流程中只有部分页面（如登录页、关键数据页）检测严格，可以只在这些页面应用stealth，在其他页面使用普通模式。
   • 调整超时设置：适当增加page.goto()和page.wait_for_selector()等操作的超时时间。

     await page.goto(url, timeout=60000) # 超时设为60秒 await page.wait_for_selector('#some-element', state='visible', timeout=30000)

   • 硬件升级：在资源充足的服务器上运行。

5.4 问题排查速查表

当你遇到检测问题时，可以按照以下清单逐步排查：

6. 超越Stealth：构建企业级抗检测自动化方案

playwright-stealth是一个强大的工具，但它不是银弹。在高度对抗的环境中，需要一套组合拳。一个健壮的、接近“生产级”的自动化方案，应该考虑以下层面：

1. 基础设施层：IP与代理管理这是最核心的一环。再好的浏览器指纹伪装，如果来自一个已知的数据中心IP段或一个被标记为滥用的IP，也会立刻失败。

• 代理类型选择：优先使用住宅代理，其次是高质量的ISP代理，尽量避免使用公开的数据中心代理。
• 代理池与轮换：实现IP自动轮换，每个任务或每次会话使用不同的IP。避免在短时间内从同一个IP发起过多请求。
• 会话隔离：确保不同的浏览器上下文（Context）使用不同的代理IP，避免Cookie和本地存储信息交叉污染。

2. 浏览器环境层：指纹多样化不要所有脚本都用同一套伪装参数。

• 多样化配置：随机化用户代理（从一个包含常见UA的列表中随机选取）、视口大小、时区、语言、屏幕色彩深度等。
• 使用真实浏览器配置文件：如前所述，launch_persistent_context可以加载真实的Chrome用户数据，这提供了最丰富的、真实的指纹信息。
• 考虑Playwright的其它引擎：除了Chromium，可以偶尔使用Firefox或WebKit。不同浏览器的指纹特征不同，可以打乱检测方的模型。

3. 行为层：模拟真人交互模式这是最难，但也是最有效的部分。

• 随机化操作路径：不要总是以相同的顺序点击链接或填写表单。可以设计多个“操作剧本”随机选择。
• 模拟浏览与等待：在关键操作前，让页面“停留”一段时间，随机滚动，模拟阅读行为。
• 处理弹窗与验证码：对于简单的弹窗，要有预期的处理逻辑。对于复杂验证码，需要集成第三方打码服务。

4. 监控与自适应层

• 健康检查：定期用bot.sannysoft.com等测试页验证你的浏览器环境是否仍然有效。
• 失败重试与降级：当操作失败（如被重定向到验证码页）时，应有重试机制。重试时，可以更换浏览器上下文、代理IP，甚至整个浏览器实例。
• 日志与审计：详细记录每次任务的IP、User-Agent、执行结果、遇到的挑战（如验证码）。这些数据是优化策略的宝贵依据。

将playwright-stealth作为这个庞大防御体系中的一环，它负责解决“静态指纹”的问题。而动态行为、网络层、资源管理则需要你根据业务场景，设计和实现更上层的逻辑。记住，对抗检测是一个持续的过程，没有一劳永逸的方案，唯有不断观察、分析和调整。