Playwright自动化实战指南：从原理到爬虫与AI Agent集成-育师

我拿 Playwright 写了三年自动化代码，从最早拿来爬数据，到后来整个测试团队把脚本全部迁到这套框架上，再到现在各种内部平台把 Playwright 当作执行器来用。可以说，Playwright 这个词已经不只是某个开源库的名字，它已经变成了浏览器自动化领域的一个事实标准。不过新手刚接触它的时候，往往会被安装、驱动、定位、等待这些概念劝退。这篇文章我打算从真实使用角度，把 Playwright 从入门到精通的路线完整捋一遍，包括它为什么好、怎么装、怎么写、怎么爬、怎么集成到其他系统，以及那些让人崩溃的报错到底怎么解决。适合刚接触自动化的小白，想从 Selenium 迁移过来的老手，用 Python 或 TypeScript 写爬虫的工程师，还有想做 LLM Agent 浏览器操作的朋友。

1. 从零认识 Playwright：它到底解决什么问题

1.1 为什么是 Playwright 而不是 Selenium

如果你之前用过 Selenium，一定能感受到两者的明显区别。Selenium 诞生得早，生态成熟，但它的架构是古老的 WebDriver 协议，浏览器每次执行一个操作，都要经过一个独立的 driver 进程中转。一旦并发开多个浏览器实例，资源占用和稳定性问题就特别明显。而 Playwright 出生时就是微软牵头搞的，直接走的是浏览器原生的 CDP（Chrome DevTools Protocol）协议，再加上 Firefox、WebKit 各自的原生调试协议，等于和浏览器之间修了一条高速直连通道，不再需要中间人。

我用 Selenium 写过一个并发 20 个浏览器的采集服务，跑不到半小时内存就爆了。换到 Playwright 之后，同样的需求，用 BrowserContext 隔离会话，每个 context 就像浏览器里的一个独立隐身窗口，内存可控，切换干净利落。这个理念非常重要：你在一个 Playwright 实例里，可以创建多个互不干扰的 context，每个 context 有自己的 Cookie、存储、UA、甚至是视口大小。这相当于把十几个“虚拟浏览器”塞进了同一个进程里，极大地压低了资源成本。

另一个让我彻底放弃 Selenium 的理由是 Playwright 的“自动等待”机制。Selenium 你需要自己写显式等待或隐式等待，什么 WebDriverWait、expected_conditions 一大堆。Playwright 几乎把所有等待都封装好了：你调 locator.click()，它会等元素出现、等元素可点击、等元素在页面中稳定，甚至等元素的位置不再变化。这套机制让脚本里基本不需要再出现 time.sleep(3) 这种丑陋的代码，稳定性也直接提升了一个量级。

1.2 Playwright 的核心架构与运行原理

理解 Playwright 的原理，用一句话概括：你的代码通过一个本地 WebSocket 通道连接到一个无头浏览器实例，然后向它发送“去看这个 URL”“去点那个按钮”的指令。Playwright 的驱动模型包含三层：上层是 Python、Node.js、Java、.NET 等语言的 API 绑定；中间是 Playwright Driver，它负责将 API 调用翻译成协议消息；底层是浏览器进程，通过专门的调试管道接收消息并执行操作。

在写代码时，最常用的对象有四个：Playwright（入口对象）、Browser（浏览器实例）、BrowserContext（会话上下文）、Page（页面对象）。关系大概是：Playwright 启动一个 Browser，Browser 里开一个 Context，Context 里开一个 Page。如果你只是偶尔自动化，可以忽略 Context 直接用 Browser.new_page()；但如果你要做爬虫或者测试多用户场景，你必须理解 Context 的隔离价值。

这里有个很常见的认知误区：很多人以为 Playwright 只能跑无头浏览器，也就是不显示界面的模式。实际上它默认就是有头模式，只是你在 CI 上一般会用 headless=True。而且 Playwright 支持 headless 模式和新的 headless 模式之间的切换，新的 headless 模式行为更贴近真实浏览器，能绕开很多“因为检测到无头环境就拒绝访问”的站点。不过，涉及站点反爬的问题，后面我会专门谈，总之不要想着用无头模式去突破什么。

2. 环境准备与第一个脚本

2.1 安装 Playwright 与浏览器内核

安装两部分：Python 包和浏览器二进制文件。很多人只装了 Python 包，直接运行就会报 “Executable doesn't exist at path”，因为 Playwright 并不用你系统里的 Chrome，它会下载一个自己锁定的 Chromium 版本。这是有意为之，因为不同浏览器版本对自动化支持差异很大，Playwright 必须保证你跑的浏览器版本和它的 API 是测过的一组。

Python 安装方式很简单：

pip install playwright playwright install chromium

如果你是 Node 项目，则：

npm init -y npm install @playwright/test npx playwright install chromium

第二条命令很重要。它会去下载特定版本的 Chromium，并放到本地的用户缓存目录里。在 Linux 服务器上，如果缺系统库，还需要执行：

playwright install --with-deps

它会自动安装所有浏览器依赖的系统库，推荐在 Docker 镜像或者干净的云服务器上用这个命令。

这里需要特别提醒一下：不要因为你的系统里有 Chrome 就试图绕过这个下载，直接用 executable_path 指向系统浏览器。我试过一次，当时图省事，结果因为浏览器版本太新、协议不匹配，各种定位失败。而且这样等于放弃了 Playwright 的版本管理优势，建议还是老老实实安装它自带的浏览器。

如果下载太慢或经常失败，原因和解决办法我放在后面第 6 章的排查部分，那里面有国内环境可用的镜像方案，请务必看完。

2.2 第一个自动化脚本的完整拆解

装好环境，先写一个最简单的 Python 脚本，用同步 API 打开百度首页，输入关键词，点击搜索按钮，最后截图：

from playwright.sync_api import sync_playwright def main(): with sync_playwright() as p: browser = p.chromium.launch(headless=False) page = browser.new_page() page.goto("https://www.baidu.com") page.get_by_role("textbox", name="搜索").fill("Playwright") page.get_by_role("button", name="百度一下").click() page.wait_for_load_state("networkidle") page.screenshot(path="baidu.png") browser.close() if __name__ == "__main__": main()

这段代码里有几个值得新手注意的点。

第一，with sync_playwright() as p:这个上下文管理器是固定的，它负责启动驱动程序并自动清理资源。Python 用户可以选择同步 API（sync_api）或异步 API（async_api）。在爬虫或服务场景里，强烈建议用异步 API，它不阻塞事件循环，可以并发处理多个页面；但作为新手入门，同步 API 更好理解。

第二，page.goto()之后，其实不需要像 Selenium 那样手写 sleep 等待页面加载。Playwright 内部有各种加载状态检测，page.wait_for_load_state("networkidle")表示等到网络空闲。但这种等待也不是万能的，如果页面一直有轮询接口，networkidle 可能会等待很久，实际项目中我常常不依赖它，而是等具体元素出现。

第三，get_by_role("textbox", name="搜索")这种语义化定位是 Playwright 的亮点。它会根据 HTML 的 role 和可访问名称来定位元素，而不是像 XPath 一样傻傻匹配路径。这个“像人一样找东西”的思路，会让脚本非常有韧性。

用 TypeScript 写第一个测试用例则更简洁，因为 Playwright 本身就内置了测试运行器：

import { test, expect } from '@playwright/test'; test('查看标题', async ({ page }) => { await page.goto('https://www.baidu.com'); await expect(page).toHaveTitle(/百度/); });

运行这个测试只需要npx playwright test。它会自动启动浏览器、执行用例、输出报告，还能生成追溯文件。

3. 核心 API 深度解析：定位器、等待、断言

3.1 定位器：从 CSS 到语义化

定位是自动化的地基。Playwright 的推荐写法是 Locator，也就是page.locator()。你可以传 CSS 选择器、XPath，也可以使用它封装好的一整套语义化定位方法。

我平时用得最多的是这些：

page.get_by_text("你好")：按文本定位，适合链接、按钮等。
page.get_by_role("button", name="确定")：按 ARIA role 定位，适合表单控件。
page.get_by_placeholder("请输入密码")：按输入框 placeholder 定位。
page.locator("#user-list li")：直接写 CSS，适合列表项。

为什么要用语义化定位而不是直接抄一个很长的 CSS？因为前端的类名和 DOM 结构太容易变了。你辛辛苦苦写了一个.content > .wrap > .btn-primary，前端同事改个样式就全挂了。但语义化定位基于的是按钮显示给用户的名称，只要页面功能不变，测试就还能跑。

我举个例子，假设页面上有一个会变文本的按钮，有时候显示“确认”，有时候显示“已提交”。如果用page.locator("button.submit-btn")，按钮还是那个按钮，好使。但如果它被改成了a标签或者加了别的样式，你就得改代码。而page.get_by_role("button", name="确认")或page.get_by_text("确认")，无论它底层是什么标签，都能找到。

另外要注意，locator()本身并不立即去页面里找元素。它只是一个“配方”，等到你调用.click()、.fill()等动作时，Playwright 才会去解析这个配方并自动等待。这个设计让代码写起来非常自然，也方便在 Page Object 里预先声明所有的定位器。

3.2 自动等待机制与显式等待

新手最容易犯的错就是不理解 Playwright 的等待哲学。前面说了，Playwright 的很多操作都会自动等待，但这个等待不是“等固定时间”，而是检查元素的 actionability 状态。以 click 为例，它在点击前会检查：

元素是否附加到 DOM
元素是否可见
元素是否稳定（没有持续动画）
元素是否接收事件（没有被遮挡）
元素是否可编辑（如果是输入框）

只有在这些条件都满足时才会真正点击。默认超时是 30 秒，你可以通过timeout参数调整。这一套机制解决了 Selenium 里 90% 的 “Element is not clickable at point” 问题。

但自动等待不代表你完全不用写等待逻辑。有些场景需要显式等待，比如你要验证某个请求已经发出，或者等待一个弹窗出现。常用的写法是：

page.expect_response("**/api/comments") # 触发动作前先声明 page.locator("button#load-more").click()

上面这个expect_response是动作和响应之间的“混合等待”，它先注册一个期望，然后再执行点击，点击后如果触发了匹配的请求/响应，才会继续往下走。这个模式在爬虫场景中尤其好用，它可以替代while循环加 sleep 的方式，非常稳定。

还有一种显式等待是page.wait_for_selector()，但我不太推荐滥用。因为一旦你用wait_for_selector，你就放弃了自动等待的优雅性，回归到“等到一个选择器出现”的传统模式。我更建议用expect(locator).to_be_visible()这种断言等待，它更语义化，而且失败时能给出很清晰的错误信息。

3.3 断言与 Playwright 的 count 方法

断言的本质是“等到一个条件满足再继续”，所以它天然也具备等待能力。在 Python 中，断言通常在expect()模块中：

from playwright.sync_api import expect expect(page.get_by_text("操作成功")).to_be_visible() expect(page.locator(".articles")).to_have_count(10)

第一个断言等待“操作成功”出现，第二个断言等待.articles的元素数量变成 10。这里的to_have_count配合count()方法特别实用。

很多人在面对“判断一个元素到底存不存在”的时候，会下意识用page.locator("...").count() > 0来判断。要注意，count()方法是同步的，它不会自动等待。如果页面还在加载，可能返回 0，然后你就误以为元素不存在。正确写法应该是使用expect(locator).to_have_count(1)或者to_be_attached()。但如果你的目的是“往一个列表里追加数据，直到数量超过某个阈值”，那count()就非常适合写进while循环：

while page.locator(".comment-item").count() < 100: page.mouse.wheel(0, 1000) page.wait_for_timeout(500)

这段代码的意思是：如果评论数量还没到 100 条，就滚动一屏，停 500 毫秒，再看数量。很多无限滚动页面都可以这么处理。至于为什么不用 wait_for_selector 去等某个元素，因为评论数量是动态增长的，没有一个固定的“结束标记”，所以用 count 轮询是最直观的办法。

4. 进阶实战：爬虫场景与页面交互

4.1 用 Playwright 爬取评论区动态内容

爬评论区是很多人接触 Playwright 的第一动力。比如抖音评论区、微博评论区，它们都是动态加载的，直接 requests 只能拿到空壳。Playwright 可以模拟真人浏览，很自然地拿走内容。但我要先声明一句：爬取公开数据一定要遵守目标平台的用户协议和 robots 协议，不要爬取个人隐私数据，也不要高频请求给站点造成压力。下面的示例只是技术演示。

以爬取某平台视频评论区为例，核心思路是：打开页面，滚动加载，抓取每条评论的文本。这里用 count 做轮询是一种简单可靠的做法：

from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=False) page = browser.new_page() page.goto("https://example.com/video/123") page.wait_for_selector(".comment-list") last_count = 0 for i in range(20): items = page.locator(".comment-item") current_count = items.count() if current_count == last_count: break last_count = current_count page.mouse.wheel(0, 1200) page.wait_for_timeout(500) comments = [] for item in page.locator(".comment-item").all(): text = item.locator(".content").inner_text() comments.append(text) print(len(comments), comments[:5]) browser.close()

这段代码有几个细节需要说明。第一，page.wait_for_selector(".comment-list")是在等待评论列表容器出现，因为只要没有容器，后面的一切都没有意义。第二，循环里的if current_count == last_count: break是一个很实用的“停止条件”，意思是如果连续两轮没有新增评论，就认为已经到底了。第三，items.count()每次调用都会实时查询 DOM，所以不会有缓存问题。

如果你想更精准地捕获在滚动过程中新增的请求，可以用page.expect_response()去监听评论接口，然后从接口返回的 JSON 里直接拿结构化数据。这比解析 DOM 更高效，也更稳。但需要你提前在浏览器 DevTools 里找到评论接口的 URL 规律，这一步往往是爬虫项目里最费时间的部分。

再提醒一个坑：有些页面的评论数据是通过 iframe 加载的，主 DOM 里根本找不到评论节点。这时候就要用到下一小节说的 frame 处理。

4.2 处理 iframe、新页面与文件下载

动态 iframe 是爬虫里让人头疼的东西。常见场景是页面里嵌了一个第三方评论区组件，整个区域是独立的文档。用 Playwright 处理 iframe 有两种姿势。

第一种，如果 iframe 有明确的 name 或 id，可以用page.frame_locator("#comment-frame")在 iframe 内部继续定位元素。比如：

frame = page.frame_locator("#comment-frame") frame.locator(".item").all()

frame_locator返回的也是一个 Locator，只不过它把查找范围限定在 iframe 内部。这里要注意，Playwright 的 frame_locator 只支持同一页面内的 iframe，不支持跨域 iframe 的 DOM 操作？实际上跨域 iframe 也能定位和操作，因为 Playwright 是通过 CDP 直接插进每个 frame 的，不受同源策略限制，这是它比 Selenium 高明的地方。

第二种，如果你要面对的是嵌套 iframe（iframe 套 iframe），可以链式使用：

page.frame_locator("#outer").frame_locator("#inner").get_by_text("确认")

链式框架定位可以把层层嵌套的 iframe 串成一句代码，非常舒适。

处理新页面也是一大痛点。点击一个链接，浏览器新开了 tab，Selenium 需要switch_to.window()来回切。Playwright 的做法是优先使用context.expect_page()，它有点像前面说的expect_response：

with context.expect_page() as new_page_info: page.click("a[target='_blank']") new_page = new_page_info.value new_page.wait_for_load_state() print(new_page.title())

这段代码通过expect_page捕获点击后新打开的页面，然后拿到新页面的 Page 对象继续操作。这样你就再也不用去维护“窗口句柄列表”了，哪个链接开哪个窗口，一一对应，逻辑非常清爽。

文件下载也是一样原理。with page.expect_download() as dl_info:点击下载按钮，然后download = dl_info.value; download.save_as("file.zip")。整个过程不会真的把文件保存到临时目录，而是给你一个 Download 对象，由你自己决定存哪，避免了一堆垃圾文件。

4.3 Playwright 与 Scrapy 结合处理动态页面

如果你的主要爬虫框架是 Scrapy，但又需要执行 JavaScript，可以使用scrapy-playwright插件。这个插件的原理是在 Scrapy 的下载器中间件里面集成 Playwright，让请求可以按需渲染。

安装和配置：

pip install scrapy-playwright

在 settings.py 中：

DOWNLOAD_HANDLERS = { "http": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler", "https": "scrapy_playwright.handler.ScrapyPlaywrightDownloadHandler", } TWISTED_REACTOR = "twisted.internet.asyncioreactor.AsyncioSelectorReactor"

然后在 spider 中，对于需要渲染的 Request，加上meta={"playwright": True}：

def start_requests(self): yield scrapy.Request(url, meta={"playwright": True, "playwright_include_page": True}) def parse(self, response): page = response.meta["playwright_page"] # 等待页面中某个数据出现 page.wait_for_selector(".comment") # 用 page.content() 获取渲染后的 HTML html = page.content()

这里有个经典坑：如果你返回了playwright_include_page: True，那 Scrapy 必须在请求结束之后关闭这个 page，否则会内存泄漏。比较好的做法是在解析完数据后：

page = response.meta["playwright_page"] # ... 解析数据 ... yield item page.close()

还有另外一个坑：scrapy-playwright 默认是异步的，如果你在里面调用 Playwright 的同步 API，会直接阻塞整个 Scrapy 的回调线程，效率极低。所以建议在配合 Scrapy 时使用 Playwright 的异步 API（async_playwright），或者让每个请求只做非常有限的渲染操作。

如果只是想在 Scrapy 里抓取某个动态加载的字段，不一定非要集成 Playwright，先看看目标数据是不是在某个 XHR 接口里，如果是，用 Scrapy 直接请求那个接口，更快更稳。Playwright 只适合那些接口加密、数据必须经过完整 JS 执行才能出现的场景。

5. 框架集成与扩展：TypeScript、Dify、midscene

5.1 TypeScript + Playwright 的工程化

如果你是一个测试开发工程师，我强烈建议用 TypeScript + Playwright，而不是 Python。这不代表 Python 不行，而是 TypeScript 版本和 @playwright/test 运行器的结合几乎天生就是为测试框架准备的。它自带断言、Fixture、平行运行、HTML 报告、重试机制、Trace 视频录制，很多东西开箱即用。

一个最基本的测试文件可以这样写：

import { test, expect } from '@playwright/test'; test.describe('登录流程', () => { test('正常登录', async ({ page }) => { await page.goto('https://example.com/login'); await page.get_by_label('用户名').fill('testuser'); await page.get_by_label('密码').fill('123456'); await page.get_by_role('button', { name: '登录' }).click(); await expect(page).toHaveURL(/\/dashboard/); }); });

除了基础的 test 之外，你还可以在playwright.config.ts里配置多个 project，比如一个跑 Chromium、一个跑 Firefox、一个跑 WebKit；还可以配置 baseURL、视口尺寸、是否 headless、报告格式等。这种多浏览器矩阵测试，在真实项目中可以说是最大的卖点。

Fixture 是另一个强大功能。比如你想在每个 Test 之前都准备一份登录状态，可以定义一个 fixture：

import { test as base, expect } from '@playwright/test'; export const test = base.extend({ loggedInPage: async ({ page }, use) => { await page.goto('/login'); await page.get_by_label('用户名').fill('prepared'); await page.get_by_label('密码').fill('pass'); await page.get_by_role('button', { name: '登录' }).click(); await use(page); }, });

然后每个测试都可以直接用loggedInPage这个参数，同时保证了测试之间的隔离。这套玩法很成熟，适合几十上百个用例的大型项目。TypeScript 的静态类型也让重构和维护变得轻松，至少比字符串拼接的 Python 脚本要安全得多。

5.2 midscene 被 Playwright 调用的原理

最近很多朋友在问 midscene 和 Playwright 的关系，特别是“midscene 被 Playwright 调用的原理”这个话题。简单说，midscene 是一个“视觉驱动的自动化 agent”，它能通过截图识别页面上的元素位置，然后让 Playwright 去执行点击、输入等操作。本质上它就是把“人眼看图”的能力接入到了 Playwright 的执行流程里。

原理可以分为四步。第一步，midscene 使用 Playwright 打开一个页面并截图；第二步，把截图传给一个多模态大模型（例如 GPT-4V 等），让模型识别出“屏幕上哪个位置是搜索按钮”；第三步，大模型返回元素的坐标或语义描述；第四步，midscene 再把坐标或描述转换成 Playwright 的page.mouse.click(x, y)或locator.click()调用。这样，只要模型识别够准，你的自动化就能绕开 DOM 结构的限制，直接按照视觉效果操作页面。

用代码概念来理解，大概是：

# 伪代码 page.goto(url) image = page.screenshot() element_info = visual_model.find_element(image, "登录按钮") page.mouse.click(element_info.x, element_info.y)

midscene 并不是要替代 Playwright，而是把 Playwright 当作浏览器操作的“手脚”，自己当“大脑”。这种思路非常适合那些 DOM 层级混乱、class 随机化比较严重、传统定位方式难以稳定使用的页面。但代价是每次操作都需要调用一次大模型，延迟和成本都会比纯 Playwright 高不少。

如果你准备在项目里引入 midscene，我建议先做好两件事：第一，把传统 Playwright 能搞定的场景先全部用传统定位器做掉，不要一上来就上大模型；第二，把 midscene 封装成一个服务，只对真正困难的步骤做视觉推理，比如验证码、滑块、图形按钮。这个混合模式在成本和稳定性之间取得了比较好的平衡。

5.3 将 Playwright 集成到 Dify 流程中

Dify 这类 LLM 应用编排平台，现在已经很流行了。很多团队希望让 AI Agent 不仅能聊天，还能真实操作网页。把 Playwright 集成到 Dify 里，通常的做法是写一个小工具服务，然后把服务注册成 Dify 的自定义工具节点，让工作流在需要时调用它。

举个实际案例：我想做一个“智能查快递”的 Agent。用户问“我的快递到哪了”，Agent 计划要查快递单号。但快递公司的网页只支持输入单号后动态渲染物流轨迹，普通 HTTP 请求拿不到数据。于是我用 FastAPI 包了一个 Playwright 查询接口：

from fastapi import FastAPI from pydantic import BaseModel from playwright.sync_api import sync_playwright app = FastAPI() class Query(BaseModel): tracking_number: str @app.post("/query_kd") def query_kd(q: Query): with sync_playwright() as p: browser = p.chromium.launch(headless=True) page = browser.new_page() page.goto("https://example-kd.com/track") page.get_by_placeholder("请输入运单号").fill(q.tracking_number) page.get_by_role("button", name="查询").click() text = page.locator(".process-list").inner_text() browser.close() return {"result": text}

然后在 Dify 的自定义工具配置里，填入这个 API 的 OpenAPI Schema，Agent 就能通过函数调用来触发它。这个方案的好处是把“浏览器操作”抽象成一个可以复用的工具，和 LLM 的规划能力解耦。哪怕 LLM 说什么都不影响你的 Playwright 代码逻辑，你只要保证接口入参和返回结构足够稳定就行。

需要注意的是，在 Dify 流程中调用 Playwright 工具的并发不要开太大。因为每个请求都会启动一个独立浏览器进程，如果同时来了 10 个请求，服务器很容易被压垮。我通常会加一个信号量控制并发，或者预先用p.chromium.launch()复用一个浏览器实例，每个请求各自开新 context，这样能降低重复启动浏览器的开销。

6. 常见问题排查与避坑指南

6.1 npx playwright install 失败的解决方案

这个问题在群里被问过上百次，尤其是国内网络环境，下载 Chromium 基本很容易失败。常见的报错是：

Failed to download Chromium
Connection refused或者Timeout
Host name lookup failed

解决思路分两类。第一类是网络问题，方案是设置镜像地址。Playwright 的下载地址可以通过环境变量PLAYWRIGHT_DOWNLOAD_HOST指定。你可以使用npmmirror提供的镜像：

export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ npx playwright install chromium

如果你用的是 Python 的playwright install，也可以设这个环境变量，因为它底层用的同样机制。如果设置了镜像还是失败，先检查一下是不是没有挂代理或者公司网络屏蔽了磁盘写入目录。这种情况建议改一下缓存目录：

export PLAYWRIGHT_BROWSERS_PATH=/path/to/your/cache

把浏览器放到一个你有权限写的位置。

第二类是缺少系统依赖库的报错。如果你在一个最小化的 Linux 镜像上运行playwright install chromium成功，但一启动浏览器就报error while loading shared libraries: libnss3.so，那就需要补库。最简单的做法：

playwright install --with-deps

这个命令在 Debian/Ubuntu 下会调用 apt-get 自动安装所有依赖。如果你们服务器不允许自动 apt，那就要看错误里具体缺哪个库，比如libnss3-dev、libatk-bridge2.0-0，手动安装。

还有一个常见问题是版本不匹配：npm 包和 Python 包安装的 Playwright 版本不同，你在一台机器上混用两个环境，容易导致浏览器二进制文件版本互相覆盖。建议一个项目一个虚拟环境，并且固定 Playwright 版本号。

6.2 “未安装 Playwright”的诡异报错

明明pip install playwright成功了，为什么运行脚本时还报ModuleNotFoundError: No module named 'playwright'？这种问题多数时候不是真的没装，而是你运行的 Python 环境和安装时用的不是同一个。比如你在 base 环境用 pip 安装了，但却用 conda 环境的 python 跑脚本，自然找不到。

排查步骤：

import sys print(sys.executable)

看看当前脚本解释器的路径，再确认一下你的 playwright 装在了哪里。可以在命令行里执行：

python -m playwright --version

如果这个命令报没有，说明当前解释器下确实没装。如果你用 PyCharm，很常见的情况是项目解释器没选对，或者虚拟环境没激活。还有一种情况是 IDE 里安装了 Python 插件，但它默认使用的内置解释器不是你想要的。

另一个“未安装”相关的报错是：The file is not a valid Playwright driver，或者Error: Cannot find module 'playwright'。这通常是 npm 项目里npx playwright install之前没有安装@playwright/test。记住，npm 和 Python 的是两套独立组件，手动混搭就会出问题。

6.3 处理动态内容与反爬的注意事项

很多朋友用 Playwright 的主要目的是采集，所以不可避免地会遇到目标站点的反爬手段。像瑞数这类动态防护产品，本质上是在不断检测浏览器环境和用户行为，通过生成动态 Token 来保证请求来自真实浏览器。我必须明确告诉各位：绕过这些防护措施，是不符合平台规则、也可能违反法律的，我不鼓励、不提供任何“过瑞数”的技巧。

但我们可以从合法合规的角度来讨论如何让自动化的行为更像真人，降低触发风控的概率，这适用于你访问自己的网站，或者已经获得授权的采集项目。

一些可落地的策略：

不要用默认的 webdriver 特征明显的 UA，改成一个常见的 Chrome UA，并且设置viewport为真实分辨率。
不要每次打开页面后立刻暴力点击，而是随机暂停 0.5 到 1.5 秒，模拟用户阅读。
用page.mouse.move()模拟鼠标轨迹，不要直接瞬移到目标。
避免高频短时间的重复请求，给每次访问设置一个随机间隔。
使用独立的 BrowserContext，每次启动都清空 cache 和 cookie，模拟“新访客”身份。

这些策略只是让自动化行为更自然，并不是保证能绕过任何防护。我还是建议在做任何采集之前，先查看目标站点的robots.txt，并严格遵守相关法律法规，只采集公开、合法、允许访问的数据。

另外，Playwright 本身有一个很实用的功能，叫做page.route()，可以拦截网络请求并修改请求头或响应。它在应付某些前端硬编码的场景时非常有用，比如你想去掉页面里某个影响加载的资源。但同样地，如果你用它来伪造请求头去欺骗服务器，那就已经进入了灰色地带，我不会推荐这种做法。合规红线一定要守好。

最后分享一点个人体会

做了这么久的自动化，我最大的感悟是：Playwright 真正的难点不在于 API 记不住，而在于你要理解浏览器和页面的生命周期。很多脚本不稳定，不是框架的问题，而是等待模型没选对、定位表达式太脆弱、或者根本没有考虑异常情况。如果你在项目里能始终做到“少用固定等待、多用自动等待和断言等待，尽量用语义化定位而不是 CSS 路径依赖”，你的脚本稳定率会提升一大截。

还有一个小技巧：遇到瓶颈时可以打开 Playwright 的 Trace 查看器，它会记录每一步操作前后的页面截图、DOM 快照、网络请求和浏览器控制台日志。这个工具的调试效率比盲目加 print 高得多，但它需要你在脚本里先开启 trace。

context.tracing.start(screenshots=True, snapshots=True, sources=True) # 你的操作 context.tracing.stop(path="trace.zip")

然后用playwright show-trace trace.zip就能看到完整回放。我每次给团队排查问题都会先导出 trace，这比什么都好用。最后建议大家别好高骛远，先从“自动登录一个网站”“自动填写表格”这种小目标开始，等你真正理解定位和等待之后，再去做爬虫、做集成、做 Agent，都会顺畅很多。