Playwright自动化测试与数据抓取：从安装到实战的完整指南-三亩地-编程学习日记

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

如果你正在为Web自动化测试、数据抓取或者网页操作脚本而头疼，那么Playwright的出现，很可能就是你的“解药”。作为一个由微软开源的现代化浏览器自动化库，它正迅速成为开发者和测试工程师手中的新宠。我最初接触它，是为了解决一个老项目里Selenium脚本运行不稳定、维护成本高的问题。在经历了几个月的实战后，我可以说，Playwright在易用性、稳定性和功能覆盖面上，确实带来了质的飞跃。

简单来说，Playwright能让你用代码控制Chromium、Firefox和WebKit（Safari的引擎）三大浏览器，模拟真实用户的操作：点击、输入、滚动、截图、甚至拦截网络请求。它不像一些“玩具”工具只能处理简单页面，对于现代Web应用中的单页应用（SPA）、Shadow DOM、文件上传下载、跨域iframe等复杂场景，它都提供了优雅且强大的API。无论是你想自动化测试一个React/Vue应用，还是批量抓取一些动态加载的数据，或者做一个定时签到脚本，Playwright都能胜任。

网上相关的教程和热词很多，从基础的“playwright安装”到“playwright自动化框架搭建”，再到与AI结合的“playwright mcp”、“claude code + playwright”，都说明了它的热度。但很多资料要么过于零散，要么直接贴代码缺乏上下文。这篇指南，我将结合自己从零到一的踩坑经验，为你梳理一份结构清晰、可直接上手复现的完整攻略。我们会从最核心的安装开始，一步步深入到实际使用中的关键技巧和避坑指南。

2. 环境准备与核心安装

万事开头难，但Playwright的开头其实相当友好。它的安装过程设计得很“现代化”，一条命令就能解决大部分问题。不过，为了确保后续使用顺畅，我们最好先理清环境。

2.1 选择你的编程语言与包管理器

Playwright官方主要支持三种语言：Node.js（JavaScript/TypeScript）、Python和Java。此外，还有一个独立的.NET版本。根据网络热词来看，python playwright和nodejs相关的搜索量很大，这也是社区最活跃的两个方向。

Node.js / TypeScript：这是Playwright的“原生”环境，更新最快，API特性最先支持。如果你前端技术栈熟悉，或者项目本身就是Node.js环境，这是首选。需要先安装Node.js（建议LTS版本）和npm或yarn、pnpm等包管理器。
Python：对于测试工程师、数据科学家或者习惯Python简洁语法的人来说，Python版是绝佳选择。它通过pip安装，API设计也非常Pythonic。你需要先确保系统已安装Python（建议3.7及以上版本）和pip。
Java：适合Java技术栈的团队集成。通过Maven或Gradle引入。

我的选择与建议：我个人主力使用Python版本，因为它与我现有的数据分析和后端项目集成度最高，且脚本写起来非常快。对于纯Web前端项目，我会用Node.js版本。新手可以从Python入手，语法直观，社区示例丰富。

2.2 一步到位的安装命令

安装Playwright本身非常简单，关键在于安装命令背后的“玄机”。很多人卡在“playwright install chromium 很慢”这个问题上，我们来彻底解决它。

对于Python用户：打开你的终端（CMD、PowerShell或bash），执行以下命令：

pip install playwright

这条命令会安装Playwright的核心Python库。

对于Node.js用户：在你的项目目录下执行：

npm init -y # 如果还没有package.json npm install playwright

或者使用yarn：

yarn add playwright

安装完核心库后，最关键的一步来了：安装浏览器。Playwright的强大在于它自带经过特定补丁和优化的浏览器版本，确保API的稳定运行。你需要运行以下命令来下载浏览器：

# Python playwright install # Node.js npx playwright install

这就是网络热词中“playwright install”的核心。这条命令会默认下载Chromium、Firefox和WebKit三大浏览器。下载的文件体积较大（总计约300-500MB，取决于平台），所以速度慢是正常现象，尤其是在网络环境不佳的情况下。

2.3 解决“安装很慢”与镜像加速

遇到“playwright install chromium 很慢”怎么办？这是最高频的问题之一。Playwright默认从Google的存储桶下载，国内访问可能不稳定。

解决方案1：使用环境变量指定镜像（推荐）Playwright支持通过环境变量PLAYWRIGHT_DOWNLOAD_HOST来指定下载镜像源。国内有一些镜像源可用，但稳定性需要自行测试。例如（请注意，以下镜像地址仅为示例，实际可用性需当时验证）：

# 在Linux/macOS的终端中 export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ playwright install # 在Windows PowerShell中 $env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright/" playwright install

解决方案2：只安装你需要的浏览器如果你只需要Chromium，可以只安装它，节省时间和带宽。

playwright install chromium # 或 npx playwright install chromium

解决方案3：手动下载与离线安装（终极方案）如果网络实在不通，你可以从Playwright的GitHub Releases页面或其他可信镜像站手动下载对应操作系统和版本的浏览器包，然后解压到Playwright预期的缓存目录中。缓存路径通常位于：

Windows:%USERPROFILE%\AppData\Local\ms-playwright
macOS/Linux:~/Library/Caches/ms-playwright或~/.cache/ms-playwright

你需要根据playwright --version输出的版本号，找到完全匹配的浏览器包。此方法较繁琐，仅作备选。

安装成功后，你可以通过playwright --version或npx playwright --version来验证安装。

3. 快速上手：你的第一个自动化脚本

理论说再多，不如跑一行代码。让我们写一个最简单的脚本，感受一下Playwright的威力。这个脚本将打开浏览器，访问百度，截图并保存。

3.1 Python版本示例

创建一个名为first_script.py的文件，写入以下内容：

import asyncio from playwright.async_api import async_playwright async def main(): # 启动Playwright，它负责管理浏览器进程 async with async_playwright() as p: # 启动一个Chromium浏览器实例，headless=False表示显示浏览器界面 browser = await p.chromium.launch(headless=False) # 创建一个新的浏览器上下文（类似于一个独立的隐身会话） context = await browser.new_context() # 在新上下文中打开一个页面 page = await context.new_page() # 导航到百度 await page.goto('https://www.baidu.com') # 等待页面加载到网络空闲状态（针对SPA很有用） await page.wait_for_load_state('networkidle') # 对页面进行截图并保存 await page.screenshot(path='baidu_homepage.png', full_page=True) print("截图已保存为 baidu_homepage.png") # 关闭浏览器 await browser.close() # 运行异步主函数 asyncio.run(main())

在终端运行：python first_script.py。你会看到一个浏览器窗口自动打开，访问百度，然后截图保存，最后关闭。

3.2 Node.js (JavaScript) 版本示例

创建一个名为first_script.js的文件，写入以下内容：

const { chromium } = require('playwright'); (async () => { // 启动浏览器 const browser = await chromium.launch({ headless: false }); // 创建上下文 const context = await browser.newContext(); // 创建页面 const page = await context.newPage(); // 导航到百度 await page.goto('https://www.baidu.com'); // 等待网络空闲 await page.waitForLoadState('networkidle'); // 截图 await page.screenshot({ path: 'baidu_homepage.png', fullPage: true }); console.log('截图已保存为 baidu_homepage.png'); // 关闭浏览器 await browser.close(); })();

在终端运行：node first_script.js。效果与Python版本一致。

3.3 代码逐行解析与核心概念

async/await：Playwright的API是异步的，这是为了高效处理浏览器的I/O操作。在Python中需使用asyncio，在Node.js中则直接使用其原生异步支持。
launch：启动一个浏览器进程。参数headless: false让浏览器界面显示出来，方便调试。在生产环境或服务器上，通常设置为headless: true（无头模式），不显示界面，节省资源。
browser.new_context()：创建一个浏览器上下文。这是Playwright中一个极其重要的概念。每个上下文都拥有独立的cookie、本地存储、缓存和权限设置，相互隔离。这意味着你可以在一个脚本中轻松模拟多个独立的用户会话，而无需启动多个浏览器进程。
context.new_page()：在上下文中打开一个新的标签页。
page.goto()：导航到指定URL。它会等待页面触发load事件。
page.wait_for_load_state('networkidle')：这是一个更高级的等待策略。它等待页面网络活动在至少500毫秒内没有超过2个请求。这对于等待JavaScript动态加载内容（如AJAX请求）完成非常有效，比简单的固定sleep或等待某个元素出现更智能。
page.screenshot()：截图。参数full_page: true可以截取整个可滚动页面的长图。

这个简单的脚本已经涵盖了启动、导航、等待、操作（截图）和关闭的核心流程。接下来，我们要深入更实用的交互操作。

4. 核心交互：模拟真实用户操作

自动化不仅仅是打开网页和截图，更重要的是与页面元素交互。Playwright提供了非常直观的API来定位和操作元素。

4.1 元素定位：多种选择器策略

定位元素是自动化的基石。Playwright支持丰富的选择器引擎，你可以根据实际情况选择最合适的一种。

# 假设我们有一个页面，上面有一个搜索框<input id="kw">和一个搜索按钮<button id="su"> # 1. CSS选择器 (最常用) search_box = page.locator('#kw') # ID选择器 search_box = page.locator('input[name="wd"]') # 属性选择器 # 2. XPath (处理复杂结构时有用) search_box = page.locator('//*[@id="kw"]') # 3. 文本内容定位 (非常实用！) search_button = page.locator('text=百度一下') # 精确匹配文本 search_button = page.locator('text=/百度一下/i') # 正则表达式匹配，忽略大小写 # 4. 根据角色定位 (ARIA属性，语义化) button = page.locator('role=button[name="提交"]') # 5. Playwright专属扩展选择器 # - 根据元素可见文本定位（包含子元素文本） page.locator(':has-text("搜索")') # - 根据邻近元素定位 page.locator('input:left-of(:text("密码"))')

实操心得：优先使用CSS选择器和文本定位。text=选择器在按钮、链接等文本明确的元素上非常可靠且易读。尽量避免使用脆弱的XPath，除非页面结构非常稳定且没有其他好的定位方式。使用page.locator()会返回一个Locator对象，它代表一个或一组元素，后续操作都基于它。

4.2 常用交互操作

定位到元素后，就可以执行操作了。

# 输入文本 await search_box.fill('Playwright教程') # 或模拟逐个字符输入（更真实） await search_box.type('Playwright教程', delay=100) # 每个字符间隔100毫秒 # 点击 await search_button.click() # 强制点击（即使元素被遮挡、不可交互） # await search_button.click(force=True) # 慎用，可能违反业务逻辑 # 勾选复选框、单选框 checkbox = page.locator('#agree') await checkbox.check() # 勾选 await checkbox.uncheck() # 取消勾选 await checkbox.set_checked(True) # 设置状态 # 下拉框选择 dropdown = page.locator('select#city') await dropdown.select_option(label='北京') # 根据显示文本选择 await dropdown.select_option(value='beijing') # 根据value值选择 await dropdown.select_option(index=2) # 根据索引选择 # 文件上传（这是Playwright的强项！） file_input = page.locator('input[type="file"]') # 单文件 await file_input.set_input_files('/path/to/my/file.pdf') # 多文件 await file_input.set_input_files(['/path/to/file1.jpg', '/path/to/file2.jpg']) # 注意：set_input_files 模拟了文件选择对话框，但要求input元素类型为file。

4.3 等待策略：让脚本更稳定

Web页面是动态的，元素可能不会立即出现。硬编码等待（如time.sleep(5)）是糟糕的做法。Playwright提供了智能的等待机制。

# 1. 自动等待：Playwright的核心操作（如click, fill）本身内置了等待，会等待元素可操作（可见、稳定、未动画、可接收事件）。 await search_box.fill('test') # 内部已等待元素可输入 # 2. 显式等待：当你需要等待特定条件时使用。 # 等待元素出现（附加到DOM并可见） await page.wait_for_selector('#result', state='visible', timeout=10000) # 等待元素从DOM中消失 await page.wait_for_selector('#loading', state='hidden') # 等待特定文本出现在页面上 await page.wait_for_selector('text=操作成功') # 等待导航完成 await page.wait_for_url('**/success') # 使用通配符匹配URL # 等待函数返回真值 await page.wait_for_function('window.innerWidth > 1000') # 3. 网络请求等待（前面提到的） await page.wait_for_load_state('networkidle') # 网络空闲 await page.wait_for_load_state('domcontentloaded') # DOM加载完成

最佳实践：尽量依赖Playwright操作的自动等待。只有在需要等待非交互性条件（如特定文本、URL变化、网络请求）时，才使用显式等待。避免混合使用time.sleep。

5. 高级特性与实战技巧

掌握了基本操作，我们来探索一些让脚本更强大、更健壮的高级特性。

5.1 处理弹窗、新窗口与iframe

现代网页中，弹窗和iframe非常常见。

对话框（alert, confirm, prompt）：

# 监听对话框事件，并在触发时执行操作（如接受、取消、输入文本） page.on('dialog', lambda dialog: dialog.accept()) # 自动接受所有弹窗 # 更精细的控制 page.on('dialog', lambda dialog: print(dialog.message)) # 对于需要输入的prompt page.on('dialog', lambda dialog: dialog.accept('输入的文字'))

新窗口/标签页：

# 监听新页面打开事件（例如点击一个target=_blank的链接） async with page.expect_popup() as popup_info: await page.click('a[target="_blank"]') # 触发打开新窗口的操作 new_page = await popup_info.value # 获取新页面的Page对象 await new_page.wait_for_load_state() print(await new_page.title())

iframe：

# 定位iframe元素 frame_element = page.frame_locator('iframe[name="content"]') # 在iframe内部定位和操作元素 button_in_iframe = frame_element.locator('button.submit') await button_in_iframe.click() # 或者通过URL或名称获取Frame对象 frame = page.frame(name='content-frame') if frame: await frame.click('button')

5.2 网络请求拦截与模拟

这是Playwright相比Selenium等工具的一大杀手锏。你可以监听、修改甚至阻断网络请求，极大提升自动化能力。

# 1. 路由（拦截）请求，并返回自定义响应（例如模拟API数据、屏蔽广告） await page.route('**/api/ads/*', lambda route: route.abort()) # 阻断广告请求 await page.route('**/*.jpg', lambda route: route.abort()) # 阻断所有jpg图片，加速测试 # 更复杂的：修改请求或响应 async def handle_route(route): # 获取原始请求 request = route.request # 可以修改请求头 headers = {**request.headers, 'x-custom-header': 'my-value'} # 继续请求，或返回模拟响应 if 'mock-data' in request.url: await route.fulfill( status=200, content_type='application/json', body=json.dumps({'mock': 'data'}) ) else: await route.continue_(headers=headers) await page.route('**/*', handle_route) # 2. 监听请求/响应 page.on('request', lambda request: print('>>', request.method, request.url)) page.on('response', lambda response: print('<<', response.status, response.url))

5.3 执行JavaScript

有时需要通过注入JS来获取复杂数据或执行特殊操作。

# 在页面上下文中执行JS，并返回值 dimensions = await page.evaluate('''() => { return { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight, deviceScaleFactor: window.devicePixelRatio }; }''') print(dimensions) # 将Python变量传入JS上下文 selector = '#result' text = await page.evaluate('(sel) => document.querySelector(sel).innerText', selector) print(text) # 在元素句柄上执行JS element = await page.query_selector('h1') bounding_box = await element.bounding_box() # 这本身就是一个通过JS获取的属性

5.4 模拟设备与地理位置

Playwright可以轻松模拟移动设备访问，或者设置虚拟地理位置。

from playwright.sync_api import sync_playwright with sync_playwright() as p: # 使用预定义的设备描述符模拟iPhone iphone = p.devices['iPhone 12'] browser = p.chromium.launch(headless=False) # 创建上下文时传入设备参数 context = browser.new_context(**iphone, locale='zh-CN') # 同时设置语言环境 page = context.new_page() await page.goto('https://m.example.com') # 此时页面看到的将是移动端视图和User-Agent # 设置地理位置和权限 context = browser.new_context( geolocation={'longitude': 116.397, 'latitude': 39.916}, permissions=['geolocation'] ) page = context.new_page() await page.goto('https://maps.example.com') # 页面将获得定位权限，并访问到模拟的北京坐标

6. 工程化实践：测试、调试与部署

当脚本越来越多，就需要考虑如何组织、调试和持续运行。

6.1 Playwright Test Runner (强烈推荐)

Playwright提供了自己的测试运行器（@playwright/testfor Node.js,pytest-playwrightfor Python），它比单纯写脚本更强大，专为自动化测试设计，支持并行、重试、截图对比、HTML报告等。

Python (pytest) 示例：

安装：pip install pytest-playwright
安装浏览器：playwright install
创建测试文件test_example.py:

import re from playwright.sync_api import Page, expect def test_baidu_search(page: Page): """测试百度搜索功能""" page.goto('https://www.baidu.com') page.locator('#kw').fill('Playwright') page.locator('#su').click() # 使用Playwright Test的断言，它会自动等待 expect(page).to_have_title(re.compile('Playwright')) # 或者等待结果区域出现 expect(page.locator('#content_left')).to_be_visible() def test_has_search_input(page: Page): """测试百度首页有搜索框""" page.goto('https://www.baidu.com') search_input = page.locator('#kw') expect(search_input).to_be_empty() expect(search_input).to_be_editable()

运行测试：pytest test_example.py --browser chromium --headed。它会自动管理浏览器生命周期，测试失败时会自动保存截图和追踪信息。

6.2 调试技巧

慢动作与暂停：在launch或操作中设置slow_mo参数，让所有操作以指定毫秒延迟执行，方便观察。
```
browser = await p.chromium.launch(headless=False, slow_mo=500) # 每个操作延迟500ms
```
录制器 (Codegen)：Playwright提供了一个强大的命令行工具，可以录制你的操作并生成代码。对于快速生成脚本原型或学习API非常有用。
```
playwright codegen https://www.baidu.com
```
运行后会自动打开浏览器和代码生成器窗口，你的操作会被实时转换成代码。
追踪查看器：在测试运行失败时，Playwright Test会生成一个追踪文件（.zip）。使用playwright show-trace trace.zip命令可以打开一个图形化界面，逐帧回放测试过程，查看网络请求、DOM快照、控制台日志等，是调试复杂问题的神器。
浏览器开发者工具：在非无头模式（headless: false）下运行脚本，你可以手动打开浏览器的开发者工具（F12），观察元素、网络和Console，与手动操作无异。

6.3 配置与部署

配置文件：对于大型项目，使用配置文件管理浏览器类型、基础URL、超时时间、截图目录等非常方便。在Node.js中通常是playwright.config.ts，在Python的pytest中可以通过pytest.ini或conftest.py配置。
CI/CD集成：Playwright可以轻松集成到GitHub Actions, GitLab CI, Jenkins等持续集成环境中。关键点：
1. 在CI环境中安装Playwright和浏览器（通常使用playwright install --with-deps安装系统依赖和浏览器）。
2. 使用无头模式运行。
3. 上传测试报告和失败追踪文件作为产物。
Docker部署：Playwright官方提供了Docker镜像（mcr.microsoft.com/playwright），里面已经包含了所有依赖和浏览器，是部署到服务器或云环境的理想选择，可以保证环境一致性。

7. 常见问题排查与性能优化

在实际使用中，你一定会遇到各种问题。这里总结了一些高频问题的排查思路和优化技巧。

7.1 元素定位失败

这是最常见的问题，错误信息通常是TimeoutError: Timeout 30000ms exceeded。

排查步骤：

确认页面已加载：在定位前，确保页面加载到了正确状态。使用page.wait_for_load_state('networkidle')或等待某个标志性元素出现。
检查选择器：在浏览器开发者工具中（Console里）用document.querySelector('你的选择器')测试，看是否能找到元素。注意Playwright的text=选择器在Console里无法直接测试。
元素在iframe或Shadow DOM中：如果是，需要使用frame_locator或page.locator('...').shadow_root来深入。
元素是动态生成的：等待元素出现。使用page.wait_for_selector()或Playwright Test的expect(locator).to_be_visible()。
页面有多个匹配项：page.locator('div.button')可能匹配到多个元素，默认操作第一个。使用更精确的选择器，或者使用locator.first,locator.nth(index),locator.last来指定。

启用调试与截图：在定位失败前手动截图，查看页面状态。

await page.screenshot(path='debug_before_click.png', full_page=True) await button.click()

7.2 脚本运行缓慢

减少不必要的等待：用智能等待（networkidle,wait_for_selector）替代固定的time.sleep。
重用浏览器上下文：启动浏览器和创建上下文开销较大。如果多个测试或任务不依赖完全隔离的会话，可以复用同一个browser或context。
并行执行：Playwright Test支持并行运行测试。在CI中，可以利用sharding将测试分片到多个机器上并行执行。
拦截无用资源：使用page.route()拦截并中止对图片、样式表、字体或广告脚本的请求，可以显著提升页面加载速度。
使用无头模式：headless: true比显示GUI快得多，资源占用也更少。

7.3 浏览器启动或安装问题

executable doesn‘t exist错误：通常是因为浏览器未正确安装。重新运行playwright install，并注意终端输出是否有错误。检查缓存目录是否存在浏览器文件。
内存不足：运行大量测试或复杂页面时，浏览器可能内存泄漏。确保定期关闭不再使用的page和context对象，最终关闭browser。在长时间运行的脚本中，可以考虑定期重启浏览器上下文。
沙箱问题（常见于Docker或某些Linux环境）：在启动浏览器时添加args: ['--no-sandbox', '--disable-setuid-sandbox']参数。
```
browser = await p.chromium.launch(args=['--no-sandbox', '--disable-setuid-sandbox'])
```

7.4 与CI/CD集成的认证问题

在CI环境中，可能需要处理登录态。最佳实践是：

使用存储状态：在本地先完成一次登录，然后将浏览器上下文的状态保存下来。

# 登录后保存状态 context.storage_state(path='auth_state.json') # 在CI中，加载状态创建上下文 context = await browser.new_context(storage_state='auth_state.json')

使用环境变量：将用户名、密码或API Token通过CI的环境变量传入脚本，在脚本中执行登录流程。注意安全，不要将敏感信息硬编码在脚本中。

从一条简单的安装命令，到一个能稳定处理复杂Web交互、具备良好工程结构的自动化项目，Playwright提供的是一整套现代化的解决方案。它解决的不只是“能用”，更是“好用”和“稳定”。我自己的项目从Selenium迁移过来后，脚本的稳定性提升了至少70%，调试效率也大大提高。尤其是在处理文件上传、网络拦截和移动端模拟这些场景时，那种“原来可以这么简单”的感觉非常强烈。当然，任何工具都有学习曲线，初期在元素定位和等待策略上可能会花些时间琢磨，但一旦掌握，你会发现它为Web自动化打开了一扇新的大门。

日记详情

Playwright自动化测试与数据抓取：从安装到实战的完整指南