Playwright浏览器自动化实战：从安装到元素定位与自动等待详解

脚本专家

Playwright 是由 Microsoft 开发维护的开源浏览器自动化框架，支持 Python、JavaScript、Java、.NET 等多语言，内置 Chromium、Firefox、WebKit 三大浏览器引擎。与传统的 Selenium 相比，Playwright 无需手动安装 WebDriver，原生支持自动等待、网络拦截、多页面隔离等特性，在现代 E2E 测试与数据采集场景中逐渐成为首选。本文基于 Python 同步 API 讲解核心概念、环境搭建、常用操作、元素定位策略及自动等待机制，并提供可直接运行的代码示例。

2. from playwright.sync_api import sync_playwright
4. with sync_playwright() as p:
5.     browser = p.chromium.launch(headless=False)  # headless=True 无界面模式
6.     page = browser.new_page()
7.     page.goto("https://playwright.dev/")
8.     print(page.title())
9.     page.screenshot(path="homepage.png", full_page=True)
10.     browser.close()

复制代码

运行上面代码即完成第一个 Playwright 脚本：打开浏览器、导航到 Playwright 官网、打印标题并截取整屏截图。安装过程只需两步：

• pip install playwright
  
• playwright install（自动下载 Chromium、Firefox、WebKit 的适配版本）
  

在国内若下载缓慢可设置环境变量 PLAYWRIGHT_DOWNLOAD_HOST 为镜像地址。安装后在 Linux 服务器可能还需要运行 playwright install-deps 安装系统依赖。

Playwright 的核心执行流程可概括为五步：
1. 启动浏览器（browser = p.chromium.launch()）
2. 创建页面（page = browser.new_page()）
3. 定位元素（page.locator() 或 get_by_*）
4. 执行动作（fill/click/text_content 等）
5. 获取结果或截图/录屏
理解这五步就能应对绝大多数自动化场景。

导航操作：page.goto(url)、page.reload()、page.go_back()、page.go_forward()。
点击操作：click()、dblclick()、支持 modifiers 参数（如 Shift+click）。
输入操作：fill() 清空并输入，press_sequentially() 模拟逐字符输入（适合带输入事件监听的页面）。
数据获取：text_content()、inner_text()、get_attribute()、input_value()、page.title()、page.url。
截图与录屏：page.screenshot(full_page=True) 截整页，clip 参数截取区域；录屏需创建 context 时指定 record_video_dir。

元素定位是 Playwright 最核心的能力，官方推荐优先使用语义化定位器：
- get_by_role()：基于 ARIA 角色定位，如 page.get_by_role("button", name="登录").click()
- get_by_text()：按可见文本匹配，支持 exact=True 精确匹配或 re.compile 正则
- get_by_label()：根据 label 的 for 属性定位输入框
- get_by_placeholder()：按 placeholder 属性定位
- get_by_test_id()：通过 data-testid 属性定位，测试最稳定
- get_by_title()：按 title 属性定位

若以上方式不适用，可使用通用 CSS 选择器或 XPath。CSS 定位：page.locator("#id")、page.locator(".class")、page.locator('[type="submit"]')。XPath 定位：page.locator('//button[text()="提交"]')、支持 contains 和轴定位。链式定位可先定位父容器再缩小范围，配合 filter 按文本或子元素过滤，使用 nth(index)、first、last 选取特定匹配。

定位优先级建议：
测试场景：get_by_test_id > get_by_role > get_by_label > get_by_text > CSS > XPath
采集场景：常用 CSS 和 XPath，灵活度高。

自动等待是 Playwright 相比 Selenium 的最大优势之一。当执行 page.locator("button").click() 时，Playwright 会自动检查以下条件（全部满足后才执行 click）：
1. 元素出现在 DOM 中
2. 元素可见（非 display:none/visibility:hidden）
3. 元素稳定（位置不再变化）
4. 元素可接收事件（不被其他元素遮挡）
5. 元素可交互（非 disabled 状态）
默认超时 30 秒，超出则抛 TimeoutError。

因此，编写脚本时应尽量避免使用 time.sleep()，而是依赖自动等待或显式等待 API：
- page.wait_for_selector("#result", state="visible")
- page.wait_for_load_state("networkidle")  等待网络空闲
- page.wait_for_url("**/dashboard")
- page.wait_for_function("document.querySelector('#result') !== null")

对于复杂场景，Playwright 提供了更多高级 API：
- 浏览器上下文（BrowserContext）隔离 Cookie 和 LocalStorage，一个 Browser 可创建多个 Context 实现并行隔离
- 设备模拟：context = browser.new_context(**playwright.devices["iPhone 12"])
- 网络拦截：page.route("**/*.png", lambda route: route.abort()) 阻止图片加载；或利用 page.expect_response() 捕获特定请求的响应
- 文件上传：page.locator('input[type="file"]').set_input_files("file.pdf")
- iframe 操作：page.frame_locator("iframe[name='xxx']").locator(...).click()
- 执行 JavaScript：page.evaluate("() => document.title")
- 弹窗处理：page.on("dialog", lambda dialog: dialog.accept())
- 多标签页：context.wait_for_page() 监听新页面

Playwright 还提供 Codegen 代码录制工具：运行 playwright codegen url 即可在浏览器中交互并自动生成对应代码。调试时可用 headed 模式 + slow_mo 减缓操作速度，或使用 Trace Viewer 查看录制的完整操作轨迹。

总结：Playwright 以其简洁的 API、内置自动等待、跨浏览器支持及丰富的调试工具，是现代浏览器自动化的首选方案。掌握本文的核心五步法、定位策略与自动等待机制，即可快速上手开发爬虫、自动化测试或 RPA 脚本。后续可进一步学习与 pytest 集成、远程浏览器控制、组件测试等进阶功能。

热心网友5

感谢楼主这么详细的分享！我之前主要用Selenium，最近刚接触Playwright，看你这篇教程把很多关键点都讲透了，尤其是自动等待机制和定位器的优先级建议，非常实用。有个小问题想请教：在国内环境下，除了设置 PLAYWRIGHT_DOWNLOAD_HOST 镜像，还有没有其他加速安装的小技巧？另外录屏那个 record_video_dir，是不是只能在 BrowserContext 级别开启，如果只想要某个页面的局部录屏该怎么处理？期待楼主后续能再讲讲网络拦截和 mock 接口的具体用法，那个场景在测试里也很常用。再次感谢！

热心网友6

谢谢楼主分享这么详细的 Playwright 教程！从安装到核心 API，再到定位策略和自动等待机制，每一步都讲得很清楚，对新手特别友好。我之前一直用 Selenium，最近也在试着转 Playwright，看到你提到自动等待内置了可交互性检查，感觉确实省心很多。不知道你在实际项目中有没有遇到过元素定位策略切换的坑？比如某些场景下 get_by_role 匹配不到，最终用 CSS/xpath 才解决的情况？想听听你的经验。

热心网友2

感谢楼主的详细分享！Playwright 的自动等待确实比 Selenium 省心很多，以前写 Selenium 脚本时总得手动加各种 `WebDriverWait`，现在一个 `click()` 就能自动等元素稳定可见，代码干净多了。另外你提到的定位优先级对测试和采集场景的区分很实用，我平时做数据采集时常用 CSS 和 XPath，确实灵活度更高。想问一下：遇到动态加载的表格数据（比如滚动加载更多行），用 `page.wait_for_function` 和 `page.evaluate` 配合检查 DOM 长度变化是不是比等 `networkidle` 更可靠？期待后续还能分享更多实战技巧！