1. 项目概述：为什么我们需要Playwright Stealth？

如果你用过Playwright做自动化测试或者数据抓取，大概率遇到过这个场景：脚本跑得好好的，突然页面弹出一个验证码，或者直接返回一个“访问被拒绝”的提示。那一刻的感觉，就像你正开着车在高速上飞驰，突然被交警拦下查酒驾一样，既无奈又有点懵。这背后，就是现代网站普遍部署的“反机器人检测”技术在起作用。

Playwright作为微软出品的浏览器自动化工具，功能强大，API设计优雅，已经成为Web自动化领域的明星。但它的“原生”状态，在那些专门盯着自动化流量的网站面前，就像一个穿着校服、背着书包走进酒吧的学生，一眼就被看穿了。网站会检测浏览器指纹、HTTP请求头、JavaScript环境变量等一系列特征，来判断访问者是不是一个真实的“人”。而Playwright驱动的浏览器，尤其是无头模式，会暴露出一些自动化特有的“马脚”，比如navigator.webdriver属性为true，用户代理字符串里包含“Headless”字样等。

这就是“Playwright Stealth”插件诞生的背景。它不是一个独立的新框架，而是一个专门为Playwright设计的“隐身衣”。它的核心目标很简单：通过一系列技术手段，抹去或修改那些容易被检测到的自动化痕迹，让你的Playwright脚本驱动的浏览器，在目标网站看来，更像是一个由真人操作的普通浏览器。

我最初接触它，是因为一个电商价格监控项目。脚本运行几小时后，账号就被风控了。在排查了IP、请求频率、操作模式后，最终锁定问题就出在浏览器指纹上。手动去修改每一个指纹特征不仅繁琐，而且网站的反制策略也在不断升级。Playwright Stealth的出现，相当于把这场“猫鼠游戏”中防御方的常用武器库，打包成了一个开箱即用的工具。它移植自Puppeteer生态中久经考验的puppeteer-extra-plugin-stealth，专门为Playwright做了适配，让我们的自动化脚本能够更持久、更稳定地运行。

2. 核心原理：Stealth插件如何“欺骗”检测系统？

要理解Stealth插件做了什么，我们得先知道网站是怎么发现我们的。反机器人检测不是单一技术，而是一个多层次的防御体系。Stealth插件的工作，就是针对这些层次逐一进行伪装和对抗。

2.1 浏览器指纹的“化妆术”

浏览器指纹是网站识别用户身份的核心技术之一。它通过收集浏览器暴露给JavaScript环境的大量只读属性，组合成一个近乎唯一的标识符。Playwright Stealth主要处理以下几类指纹：

1. WebDriver属性：这是最明显的标志。当浏览器被Selenium、Playwright等工具控制时，navigator.webdriver属性会返回true。Stealth插件会直接删除或重写这个属性，使其返回undefined或false。
2. 用户代理与插件列表：无头浏览器的用户代理字符串通常包含“HeadlessChrome”。Stealth会将其替换为普通Chrome的完整用户代理字符串。同时，它会注入一个合理的插件列表（navigator.plugins），因为无头浏览器通常没有插件，这是一个明显的差异点。
3. 屏幕与视口属性：无头浏览器的屏幕分辨率、颜色深度、可用高度/宽度可能与常规浏览器不同。Stealth会确保screen.width,screen.height,window.innerWidth等属性返回符合真人用户习惯的值。
4. 语言与时区：自动化脚本可能忽略这些细节。Stealth会设置合理的navigator.language和Intl.DateTimeFormat().resolvedOptions().timeZone。

注意：指纹修改需要在页面加载任何脚本之前完成。这就是为什么Stealth插件必须在page.goto()导航到目标页面之前被应用。如果顺序错了，网站脚本可能已经读取并缓存了原始的指纹信息。

2.2 HTTP请求头的“精装修”

除了JavaScript环境，HTTP请求头也是检测的重点。Playwright在发送请求时，会携带一些特有的头部信息。Stealth插件会拦截和修改这些请求头：

• Sec-Ch-Ua等客户端提示头：这些头会暴露浏览器版本和自动化状态。Stealth会将其值修改为与普通Chrome一致。
• Accept-Language、Accept-Encoding：确保这些头部的值与一个真实浏览器的预期值匹配，避免因格式异常而被标记。

2.3 行为模式的“模仿秀”

高级检测系统还会分析用户的行为模式，比如鼠标移动轨迹、点击精度、页面停留时间、滚动速度等。纯粹的Stealth插件在行为模拟上能力有限，它主要解决的是静态环境暴露问题。但对于基础的检测，消除静态指纹已经能解决80%的问题。更复杂的行为模拟，通常需要结合Playwright自身的API（如page.mouse.move()模拟人类移动轨迹）或其他专门的行为伪装库来实现。

一个关键认知：Stealth插件提供的是一种“基础隐身”，它让浏览器环境看起来正常。但它不能保证100%不被检测，因为反检测技术也在不断进化。它的价值在于大幅提高了自动化脚本的生存门槛，将你从“轻易被识别”的阵营，拉入到“需要更复杂技术才能识别”的阵营中。对于大多数非顶尖风控的网站，这已经足够了。

3. 环境搭建与基础集成

理论讲完了，我们动手把它用起来。整个过程非常清晰，分为项目初始化、安装插件、集成调用三个步骤。这里我会以Python异步API为例进行说明，这是目前Playwright最推荐的使用方式。

3.1 创建并初始化Playwright项目

首先，确保你的工作环境是干净的。我习惯为每个项目创建独立的虚拟环境，避免包依赖冲突。

# 1. 创建项目目录并进入 mkdir playwright-stealth-demo cd playwright-stealth-demo # 2. 创建并激活Python虚拟环境（Windows） python -m venv venv venv\Scripts\activate # 如果是Mac/Linux系统，使用： # source venv/bin/activate # 3. 安装Playwright核心库 pip install playwright # 4. 安装Playwright所需的浏览器二进制文件（Chromium, Firefox, WebKit） playwright install chromium

playwright install这一步会下载浏览器，时间取决于你的网络。我建议至少安装Chromium，因为它是生态最完善、Stealth插件支持最好的。

安装完成后，创建一个测试脚本test_basic.py，验证环境是否正常：

import asyncio from playwright.async_api import async_playwright async def main(): async with async_playwright() as p: # 启动浏览器，headless=False表示显示界面，方便调试 browser = await p.chromium.launch(headless=False) page = await browser.new_page() await page.goto('https://httpbin.org/user-agent') # 打印页面标题和内容，确认浏览器能正常工作 print(await page.title()) content = await page.text_content('body') print(content[:500]) # 打印前500个字符 await browser.close() asyncio.run(main())

运行python test_basic.py，如果能看到一个浏览器窗口打开并访问页面，同时在控制台打印出页面信息，说明Playwright基础环境搭建成功。

3.2 安装Playwright Stealth插件

接下来安装主角。插件的PyPI包名就是playwright-stealth。

pip install playwright-stealth

这个包体积很小，安装很快。它内部主要包含了一系列用于修改浏览器环境的JavaScript注入脚本。

3.3 将Stealth集成到你的脚本中

集成方式简单到令人发指。你只需要在创建页面对象后、导航到目标页面前，调用一下插件函数即可。

修改之前的test_basic.py，我们用它来挑战一个著名的“无头浏览器检测”测试页：

import asyncio from playwright.async_api import async_playwright from playwright_stealth import stealth_async # 导入异步版本的stealth函数 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://arh.antoinevastel.com/bots/areyouheadless') # 获取检测结果 result_element = page.locator('#res') result_text = await result_element.text_content() print(f'检测结果: {result_text}') # 为了更直观，我们截图保存 await page.screenshot(path='detection_result.png') print('截图已保存为 detection_result.png') await browser.close() asyncio.run(main())

运行这个脚本。在没有Stealth的情况下，这个页面通常会显示“You are Chrome headless”。应用Stealth之后，你应该会看到输出变为“You are not Chrome headless”，并且截图中的页面也会显示同样的信息。

这个简单的测试直观地证明了Stealth插件的作用：它成功欺骗了这个基础的检测脚本，让无头浏览器“伪装”成了普通浏览器。

实操心得：stealth_async函数必须在page.goto()之前调用。因为它的原理是向页面注入脚本，修改初始环境。如果先导航，页面上的检测代码可能已经执行完毕并得出了结论，你再注入就为时已晚了。这是一个常见的顺序错误。

4. 深入配置与高级用法

基础集成只是开始。在实际项目中，我们可能会遇到更复杂的情况，需要对Stealth进行更精细的控制，或者结合其他技巧。

4.1 同步API与异步API的选择

上面的例子用的是异步API (async/await)。如果你的项目使用的是Playwright的同步API，Stealth也提供了对应的函数。

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://arh.antoinevastel.com/bots/areyouheadless') result = page.locator('#res').text_content() print(f'检测结果: {result}') browser.close()

选择异步还是同步，取决于你的项目架构和个人偏好。异步模式在IO密集型操作（如同时控制多个页面）时性能更好，是现代Python网络编程的主流。同步模式代码看起来更线性，易于理解。Stealth插件对两者都有良好支持。

4.2 自定义与部分启用

playwright-stealth库在内部是多个“隐身技巧”的集合。虽然默认的stealth_async或stealth_sync函数会启用所有推荐的技巧，但在某些极端场景下，你可能需要禁用其中一部分，或者只启用特定的几项。

查看库的源码或者文档，你会发现它包含多个模块，例如处理navigator.webdriver的、处理用户代理的、处理插件列表的等等。目前（以常见版本为例），你可以通过传递参数进行有限的自定义，但更高级的定制可能需要你直接引用或修改其内部的JS脚本。

一个常见的需求是：我只想启用最核心的webdriver属性隐藏和用户代理修复，因为某些网站对过于“完美”的指纹反而起疑。这时，你可以尝试只应用部分脚本。不过，由于库的封装，直接配置选项可能不丰富。一个变通的方法是，研究playwright-stealth依赖的原始JS脚本（它基于puppeteer-extra-plugin-stealth），将你需要的部分单独提取出来，通过page.add_init_script()方法手动注入。这需要一定的逆向工程能力。

# 伪代码示例：手动注入自定义隐身脚本（概念性） custom_stealth_script = """ // 自定义的隐身逻辑，例如只删除webdriver属性 Object.defineProperty(navigator, 'webdriver', { get: () => undefined }); """ async with async_playwright() as p: browser = await p.chromium.launch() page = await browser.new_page() await page.add_init_script(custom_stealth_script) # 在页面加载前注入 await page.goto('your_target_url')

注意事项：自定义脚本需要你对浏览器指纹和反检测技术有较深理解，否则可能弄巧成拙。对于绝大多数应用，直接使用完整的stealth_async函数是最稳妥、最有效的方式。

4.3 结合其他反检测策略

Stealth插件解决了环境伪装问题，但要构建一个健壮的自动化系统，还需要其他策略配合：

1. IP轮换与代理：这是应对基于IP频率限制和黑名单的最有效手段。即使浏览器指纹完美，同一个IP地址在短时间内发出大量请求，也极其可疑。你需要使用高质量的代理IP池（住宅代理或数据中心代理），并在Playwright启动浏览器时配置。

   browser = await p.chromium.launch( proxy={ 'server': 'http://your-proxy-server:port', # 如果需要认证 'username': 'your-username', 'password': 'your-password' } )

2. 人类化行为模拟：在页面上的操作不要像机器一样精准和迅速。引入随机延迟、模拟非直线的鼠标移动、随机滚动页面等。

   import random await page.click('button#submit', delay=random.randint(100, 500)) # 点击前随机延迟100-500毫秒

3. Cookie与会话管理：妥善处理登录状态，避免频繁登录登出。使用browser_contexts来隔离不同的会话和Cookie池。

4. 应对验证码：对于不可避免的验证码，需要有应对方案。可以是接入打码平台，或者对于简单图形验证码使用OCR库尝试识别，再或者设计流程在触发验证码时暂停并等待人工干预。

Stealth插件在这个体系中，扮演的是“打好地基”的角色。它确保了你的浏览器“本体”看起来是可信的。在此基础上，再叠加IP、行为、会话等策略，才能构建一个真正难以被察觉的自动化终端。

5. 实战案例：构建一个抗检测的自动化测试套件

让我们从一个具体的场景出发，看看如何将Playwright Stealth融入一个真实的项目中。假设我们要为一个电商网站（比如一个仿制的练习站点）编写自动化测试脚本，测试商品搜索、加入购物车、结算流程。这个网站有基础的反机器人检测。

5.1 项目结构与配置

首先规划项目结构：

e2e-test-project/ ├── conftest.py # Pytest配置和共享Fixture ├── requirements.txt # 项目依赖 ├── pages/ # 页面对象模型 │ ├── __init__.py │ ├── base_page.py │ ├── home_page.py │ ├── search_page.py │ └── cart_page.py ├── tests/ # 测试用例 │ ├── __init__.py │ ├── test_search.py │ └── test_checkout.py └── utils/ ├── __init__.py └── stealth_helper.py # Stealth工具函数

requirements.txt内容：

playwright==1.40.0 playwright-stealth==1.0.6 pytest==7.4.0 pytest-playwright==0.4.0 pytest-asyncio==0.21.0

5.2 创建核心的Stealth工具模块

在utils/stealth_helper.py中，我们封装Stealth的初始化逻辑，并可以加入一些自定义配置。

# utils/stealth_helper.py import asyncio from playwright.async_api import Page from playwright_stealth import stealth_async async def apply_stealth(page: Page, enhanced: bool = True) -> None: """ 应用Stealth插件到Playwright页面对象。 参数: page: Playwright的Page对象。 enhanced: 是否启用增强模式（默认True）。为后续自定义扩展预留。 """ # 应用基础stealth插件 await stealth_async(page) if enhanced: # 这里可以添加一些额外的、Stealth插件可能未覆盖的指纹修改 # 例如，覆盖一些特定的属性 await page.add_init_script(""" // 示例：覆盖某些特定的性能API属性（某些检测会用到） if (window.performance) { const originalGetEntries = performance.getEntriesByType; performance.getEntriesByType = function(type) { // 对`resource`类型的条目进行过滤或修改，以隐藏某些请求痕迹 const entries = originalGetEntries.apply(this, arguments); if (type === 'resource') { return entries.filter(entry => !entry.name.includes('sensitive_tracker')); } return entries; }; } """) # 注意：上述脚本仅为示例，实际需要根据目标网站的检测点调整。 # 过度修改可能引入不稳定因素。 # 可选：在应用Stealth后，再设置一个更自然的视口大小 await page.set_viewport_size({"width": 1920, "height": 1080})

5.3 在Pytest Fixture中集成Stealth

接下来，在conftest.py中创建Playwright的Fixture，并在这里调用我们的Stealth工具。

# conftest.py import pytest import pytest_asyncio from playwright.async_api import async_playwright, Page from utils.stealth_helper import apply_stealth @pytest_asyncio.fixture(scope="function") # 每个测试函数一个浏览器上下文，隔离性好 async def browser_context_page(): """ 提供一个已经应用了Stealth的Page对象。 """ async with async_playwright() as p: # 启动浏览器，可配置为有头模式便于调试，无头模式用于CI browser = await p.chromium.launch(headless=False, slow_mo=500) # slow_mo让操作变慢，更像人类 # 创建上下文，可以在这里统一设置代理、用户代理等 context = await browser.new_context( viewport={'width': 1920, 'height': 1080}, user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ...' # 可指定一个常见UA ) page = await context.new_page() # ！！！核心：应用Stealth插件！！！ await apply_stealth(page) yield page # 将page对象提供给测试用例使用 # 测试结束后清理 await context.close() await browser.close() # 将这个Fixture暴露给所有测试模块 pytest.fixture def page(browser_context_page): """同步接口适配器，如果测试用例是同步的可以用这个（需要pytest-playwright支持）""" # 这里涉及到异步转同步，实际项目中根据测试框架选择。 # 更推荐全部使用异步测试。 return browser_context_page

5.4 编写使用Stealth的测试用例

现在，在测试用例中，我们可以直接使用这个已经“隐身”的page对象。

# tests/test_search.py import pytest class TestSearchWithStealth: """测试商品搜索功能（使用Stealth）""" @pytest.mark.asyncio async def test_search_for_product(self, browser_context_page): """测试搜索商品并验证结果""" page = browser_context_page # 1. 导航到首页 await page.goto("https://demo.e-commerce.com") # 验证首页加载成功 assert await page.title() == "Demo E-Commerce" # 2. 在搜索框输入关键词 search_input = page.locator("input[name='q']") await search_input.fill("Playwright Book") await search_input.press("Enter") # 3. 等待结果页加载，并验证URL和结果项 await page.wait_for_url("**/search**") product_items = page.locator(".product-item") count = await product_items.count() assert count > 0, "应该至少找到一个商品" # 4. 验证结果中包含关键词 first_product_title = await product_items.first.locator(".title").text_content() assert "Playwright" in first_product_title or "playwright" in first_product_title.lower() print("搜索测试通过，且浏览器环境已通过Stealth伪装。") @pytest.mark.asyncio async def test_add_to_cart_flow(self, browser_context_page): """测试从搜索到加入购物车的完整流程""" page = browser_context_page # ... 具体的测试步骤，例如点击商品、进入详情页、点击加入购物车按钮 # 关键点：所有操作都在已经应用了Stealth的page对象上进行 # 可以加入人类化操作，如随机延迟 await page.click(".add-to-cart-btn", delay=200) # 验证购物车数量增加 cart_badge = page.locator(".cart-badge") await cart_badge.wait_for(state="visible") badge_text = await cart_badge.text_content() assert badge_text == "1"

5.5 运行与验证

使用pytest运行测试：

pytest tests/test_search.py -v

如果一切顺利，测试将在伪装后的浏览器环境中执行，大大降低了被目标网站拦截的风险。你可以在运行测试时，通过设置headless=False来观察浏览器的实际行为，确认没有出现验证码或拦截页面。

这个案例的关键在于：我们将Stealth的集成封装在了测试基础设施层（Fixture）。这样，所有的测试用例无需关心复杂的反检测逻辑，只需专注于业务测试本身，实现了关注点分离。当需要调整隐身策略时，只需修改utils/stealth_helper.py或conftest.py中的一处即可。

6. 常见问题、排查技巧与进阶思考

即使使用了Stealth，在实际操作中仍然会遇到各种问题。下面是我在项目中总结的一些常见坑点和解决思路。

6.1 为什么用了Stealth还是被检测到了？

这是最常遇到的问题。原因可能有多方面：

1. Stealth版本或覆盖不全：反检测技术日新月异，你使用的playwright-stealth库版本可能已经落后于目标网站的检测手段。尝试升级到最新版本。此外，Stealth并非万能，它主要覆盖常见指纹。一些新兴或小众的检测点可能未被包含。
2. IP问题：Stealth只解决浏览器环境问题。如果你的IP地址是数据中心IP、被列入黑名单、或请求频率过高，依然会被封。环境伪装和IP质量是两条腿，缺一不可。
3. 行为指纹：你的脚本操作模式太规律。例如，每次都在页面加载后立即精确点击某个坐标，没有任何鼠标移动轨迹，页面停留时间恒定为3秒等。解决方案是引入随机性和人类化行为库（如playwright-extra的recorder插件模拟，或自己用page.mouse.move()模拟轨迹）。
4. Cookie和本地存储：网站可能通过Cookie或LocalStorage设置了一个“机器人标记”。即使你换了IP和环境，这个标记还在。确保在启动新的浏览器上下文（browser.new_context()）时是干净的，或者定期清理状态。
5. WebGL和Canvas指纹：这是非常高级且难以完全规避的指纹。Stealth插件对此的处理可能有限。如果网站依赖这些进行强验证，规避难度会指数级上升。
6. 目标网站升级了检测：这是持续对抗的过程。需要定期测试你的脚本是否还能通过基础检测页（如sannysoft.com的一系列测试），并关注反检测社区的最新动态。

排查步骤：

• 第一步：用你的脚本访问sannysoft.com或arh.antoinevastel.com/bots/areyouheadless等公开检测页，看基础伪装是否通过。
• 第二步：开启浏览器开发者工具（headless: False），在Application->Storage下查看Cookie和LocalStorage，在Console下运行navigator.userAgent等命令检查指纹。
• 第三步：使用不同的住宅代理IP进行测试，排除IP因素。
• 第四步：录制一段真人操作浏览器的网络请求和行为，与你的脚本进行对比，寻找差异点。

6.2 Stealth与Playwright版本兼容性问题

playwright-stealth作为一个第三方插件，可能滞后于Playwright主库的更新。特别是Playwright进行大版本升级时，其内部API可能发生变化，导致Stealth插件失效或报错。

解决方案：

• 在项目中固定Playwright和playwright-stealth的版本（在requirements.txt中指定），避免自动升级到不兼容的版本。
• 升级前，先在测试环境中验证新版本的兼容性。
• 关注playwright-stealth项目的GitHub仓库的Issue和Release Notes，了解已知的兼容性问题。

6.3 性能开销考量

应用Stealth插件需要向浏览器上下文注入并执行一系列JavaScript代码，这会在浏览器启动和页面初始化时带来一定的性能开销（通常是几十到几百毫秒）。对于追求极致速度的单次脚本运行，这个开销可以忽略。但对于需要频繁创建和销毁浏览器实例的高并发场景（例如大规模并行爬虫），这个开销累积起来可能比较可观。

优化建议：

• 复用浏览器上下文：尽量复用已经应用了Stealth的BrowserContext，而不是为每个任务都创建全新的浏览器实例并应用Stealth。
• 评估必要性：并非所有目标网站都有强检测。对于简单的、无反爬的网站，可以不用Stealth以提升速度。可以通过配置开关来控制是否启用。
• 异步并行：如果必须为每个任务独立实例，利用Playwright的异步API和asyncio.gather等进行并行操作，可以部分抵消单个实例初始化带来的延迟。

6.4 法律与道德边界

这是一个必须严肃对待的话题。Playwright Stealth是一个技术工具，其本身是中性的。但它的用途存在明确的边界：

• 合规的自动化测试：用于自己公司产品或拥有授权的第三方产品的测试，是完全合法合规的。Stealth在这里帮助你绕过测试环境可能存在的、与生产环境不一致的简单反爬机制，让测试更流畅。
• 数据抓取：用于抓取公开数据，且遵守网站的robots.txt协议，尊重版权，不进行恶意爬取导致对方服务器过载，在法律框架内（如遵守相关数据保护条例）通常是可接受的。Stealth在这里用于应对过度的、影响合理访问的反爬措施。
• 绝对禁止：用于绕过付费墙、盗取非公开数据、进行欺诈（如刷单、薅羊毛）、攻击网站等行为，是非法且不道德的。

作为开发者，我们的责任是：在开始任何自动化项目前，务必仔细阅读目标网站的服务条款，明确其是否允许自动化访问。尊重robots.txt。控制请求频率，避免对目标网站造成负担。将技术用于提高效率、保障质量和合法获取信息的场景。

Playwright Stealth是一把锋利的“手术刀”，在合规的自动化测试和合理的数据采集场景中，它能帮助我们切除“反爬干扰”这个病灶，让自动化流程畅通无阻。但它绝非“万能钥匙”，不能也不应被用来打开那些不该打开的门。理解它的原理，掌握它的用法，明确它的边界，才能让这个工具在正确的道路上发挥最大的价值。