前几天调一个接了 MCP 的 Playwright 自动化任务碰到一个特别磨人的问题测试脚本一启动系统就弹出一个 Safari 窗口紧接着控制台报错大意是 WebKit 驱动没有安装。刚开始我以为是 macOS 系统默认浏览器设置的问题去系统设置里改了默认浏览器结果毫无用处这才老老实实从 Playwright 的浏览器选择逻辑入手排查前后折腾了小半天。这篇就把完整的排查过程和最终方案整理出来尤其适合那些在 Mac 上跑 Playwright MCP、并且被Safari 驱动反复折磨的朋友参考。如果你不太熟悉 MCP可以把它理解成一个让 AI 客户端调用外部工具的协议接口而 Playwright MCP 就是官方提供的浏览器操作工具服务器让大模型能通过自然语言指令打开页面、点击元素、截图等等。这次出问题的恰恰是它的浏览器选择环节。1. 问题现场测试一启动就弹 Safari控制台甩出一行驱动缺失1.1 复现路径先说清楚现象不然排查容易跑偏。我的操作路径非常固定先启动npx playwright/mcplatest拉起 MCP Server然后在客户端里发出一条打开页面的 tool call几乎每次都是同一个结果——一个外观和 Safari 几乎一样的窗口弹出来紧接着终端里抛出一行错误。注意这里弹出来的并不是 macOS Dock 里那个蓝色指南针图标而是一个外观风格与 Safari 高度一致的 WebKit 渲染窗口。这个细节很重要后面章节会专门解释。报错信息长这样Error: browserType.launch: Executable doesnt exist at /Users/me/Library/Caches/ms-playwright/webkit-1403/pw-webkit.app/Contents/MacOS/pw-webkit这条报错的信息量其实很大webkit-1403是 Playwright 根据自身版本决定的一个固定组件编号pw-webkit.app是 Playwright 自己管理的浏览器可执行文件路径明确指向了 macOS 用户的缓存目录。也就是说Playwright 确实想拉起 WebKit 浏览器但它在自己的组件目录里找不到那个可执行文件。那会儿我的第一反应是系统默认浏览器被改成了 Safari于是打开系统设置把默认浏览器换成 Chrome再跑问题照旧。这时我才意识到这和系统默认浏览器可能没有半毛钱关系只能从头开始查 Playwright 自己的配置。1.2 现场环境快照为了不让排查过程变成玄学先把环境固定下来。我的机器是 MacBook ProApple Silicon系统 macOS 14Node 20 系列版本项目里锁定的 Playwright 版本是 1.48 左右MCP Server 用的官方包playwright/mcp最新版。项目根目录还有一个从老项目里继承下来的playwright.config.ts里面保留了多浏览器 project 配置。我建议所有遇到同类问题的朋友先记录三个东西操作系统版本、Playwright 版本、MCP Server 的完整启动命令。后面定位根因的时候这三个信息能帮你少走很多弯路。尤其是 MCP Server 的启动命令很多人是从配置文件里复制出来的自己早就忘了里面写了什么参数。1.3 第一次直觉排查为什么没用绝大多数人遇到每次启动都打开某个浏览器的第一反应都是去系统设置里改默认浏览器。我试过了结论是完全没用。原因后面章节会说清楚——Playwright 拉起的是它自己管理的 WebKit 构建进程和系统里双击 URL 会调用的默认浏览器完全是两条路径。这里先记住一句话Playwright 的浏览器 ≠ 系统安装的浏览器。如果系统默认浏览器不是根因那问题一定出在是什么让 Playwright 选择了 WebKit上。顺着这个方向我开始从配置到环境变量一层层往下摸。2. 先拆清楚Playwright 的Safari 驱动到底指什么2.1 三种浏览器组件和安装机制Playwright 不是一个纯协议封装它把 Chromium、Firefox、WebKit 三种浏览器内核都做成了可下载的组件用npx playwright install就能把这些组件下到本机缓存目录。macOS 上默认位置是~/Library/Caches/ms-playwrightWindows 在%USERPROFILE%\AppData\Local\ms-playwrightLinux 在~/.cache/ms-playwright。npx playwright install webkit这条命令装的不是一个能双击打开的常规应用而是一整套 Playwright 定制的浏览器可执行文件。以 WebKit 为例装完之后缓存目录里会出现类似webkit-1403这样的文件夹里面的pw-webkit.app才是真正会被启动的进程。如果你只装了 Chromium 和 Firefox那么webkit-1403目录就根本不存在报错自然就会出现。2.2 WebKit 与系统 Safari 的关系很多人会把 Playwright 的 WebKit 和系统自带的 Safari 划等号这不算全错但容易误导排查方向。WebKit 是 Safari 使用的渲染引擎Playwright 在 macOS 上下载的 webkit 构建包是一个以系统 WebKit 框架为基础、带自动化接口的独立外壳。换句话说它看起来像 Safari跑起来也是 WebKit 内核但它不是Safari.app本身。这个特性到了 macOS 上尤其容易混淆。Windows 和 Linux 上 Playwright 会捆绑一份完整的 WebKit 构建所以驱动缺失就是纯粹的文件缺失而在 macOS 上你明明能看到窗口弹出来自然觉得Safari 都启动了怎么还报没驱动。这恰恰是问题最迷惑人的地方。对比项系统 SafariPlaywright WebKit进程名Safari.apppw-webkit.app渲染内核系统 WebKit.framework系统 WebKit.framework自动化接口不直接支持完整支持 Playwright 协议组件管理系统/用户管理Playwright CLI 下载并缓存2.3 未安装驱动的准确解读报错文案里的 Executable doesnt exist 翻译成人话就是你要求我启动 webkit 浏览器但我管理的浏览器包列表里根本没有这个东西。webkit-1403这个版本号是和 Playwright 版本一一绑定的不是随便装个 Safari 就能顶上。所以未安装 Safari 驱动并不是说你的 Mac 缺少 Safari而是说Playwright 的组件管理目录里缺少对应版本的 WebKit 可执行文件。搞清楚这层关系问题的走向就清晰了要么把组件补上要么让 Playwright 不要选择 WebKit。3. 完整排查链路它为什么每次都选中 WebKit3.1 第一层项目配置里的 project 列表先从最可疑的地方查。打开项目根目录的playwright.config.ts常见配置长这样import { defineConfig } from playwright/test; export default defineConfig({ testDir: ./tests, projects: [ { name: chromium, use: { browserName: chromium } }, { name: webkit, use: { browserName: webkit } }, ], });npx playwright test执行时会按 project 列表逐个跑。如果你的测试命令没有带--projectchromium同时配置文件里又有 webkit 这个 project那么测试跑到 webkit 项目时就会尝试启动 WebKit。我检查了当前项目确实有这个配置但这里有个关键矛盾我在终端里直接执行npx playwright test --projectchromium并不会弹 Safari 窗口。这个排查结果说明项目配置里的 webkit project 不是每次弹窗的根因。真正的触发点很可能不在 test runner 里而在 MCP 调用链上。记录下这个结论继续往上查。3.2 第二层MCP Server 的启动参数把视角从 test runner 切到 MCP 层面。playwright/mcp本身是一个独立进程它有自己独立的浏览器类型选择逻辑不一定受项目里playwright.config.ts影响。它通过启动参数决定当前会话用哪种浏览器。常见 MCP 客户端配置文件里Playwright server 的声明往往是这样的{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest, --browser, webkit] } } }当我打开 MCP 客户端的配置文件后真相基本浮出水面某次为了验证页面在 WebKit 内核下的兼容性我在启动参数上加过--browser webkit后来这个参数一直没被移除。因此每次 MCP Server 接收 tool call都会按照启动参数拉起 WebKit 浏览器。窗口弹出来了但对应版本的驱动文件在缓存目录里不存在于是一边弹窗一边报驱动缺失。如果你用的是 Claude Desktop、Cline 这类工具注意配置文件路径可能不同但核心都是找到mcpServers.playwright.args里的--browser参数。务必检查自己系统里实际生效的配置而不是凭记忆判断。3.3 第三层环境变量与缓存目录的位置陷阱第二层基本锁定了问题但为了确认驱动确实没有安装而不是装到了别的地方我顺手检查了环境变量和缓存目录echo $PLAYWRIGHT_BROWSERS_PATH ls ~/Library/Caches/ms-playwright输出结果里只有chromium-xxx、firefox-xxx这类目录webkit-1403完全不存在。而且我之前在某次 CI 调试时设置过PLAYWRIGHT_BROWSERS_PATH把它指向了项目内的自定义目录这会覆盖默认缓存位置。如果这个环境变量在 MCP Server 进程里生效那么npx playwright install webkit即使装到了某个位置MCP Server 也可能从另一个位置查找两头不一致就会继续报缺失。这里有个容易忽略的细节MCP Server 的环境变量继承自它的父进程。如果你在终端里export过这个变量那么从同一个终端启动的 MCP Server 都会带着它。排查时必须确认这个变量当前的值必要时直接unset PLAYWRIGHT_BROWSERS_PATH再重启服务。3.4 责任链收束到这里完整的因果链就清楚了我画一条文字链路方便大家理解MCP Server 启动参数里写了--browser webkit每次 tool call 都要求启动 WebKit 浏览器本机缓存目录中没有对应版本的 WebKit 构建包Playwright 找不到可执行文件抛出 Executable doesnt exist因为 macOS 上 WebKit 窗口长得像 Safari用户看到的就是每次启动都调用 Safari 浏览器。我还把这个链条整理成了一张排查表方便对照排查层级检查点本次结果结论项目配置playwright.config.projects存在 webkit project不是主因MCP 参数mcpServers.args --browser设为了 webkit主因组件安装~/Library/Caches/ms-playwright缺少 webkit-1403直接原因环境变量PLAYWRIGHT_BROWSERS_PATH指向自定义目录潜在干扰项如果只装驱动不改 MCP 参数问题会从报错变成每次都正常弹 WebKit 窗口只改 MCP 参数不装驱动又可能在其他项目里踩同样的坑。所以修复要两步走。4. 解决方案装对驱动、锁死浏览器、清理配置4.1 先补装 WebKit 驱动修复的第一步永远是把缺失的组件补上。在项目根目录执行npx playwright install webkit执行成功后~/Library/Caches/ms-playwright下会出现对应的webkit-1403目录。如果想确认安装目标是什么可以先跑npx playwright install --dry-run webkit它会列出将要下载的组件清单和版本号不会真的下载。这里有一个特别值得注意的版本匹配问题npx playwright install webkit装的版本取决于当前目录里node_modules下的playwright版本。如果你用全局安装的 playwright 去装版本可能和项目里锁定版本不一致导致缓存目录里出现两个 webkit 版本最后报错路径指向的还是旧版本。正确做法是确认你运行命令的目录就是项目依赖安装的目录。4.2 修改 MCP Server 的启动参数日常调试场景把 MCP Server 的浏览器参数改回chromium最省心{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest, --browser, chromium] } } }修改后必须重启 MCP Server 和相关客户端让新参数生效。如果确实需要验证 WebKit 兼容性那--browser webkit可以保留前提是第一步已经补装了驱动。两种场景对应两种选择按需求来不要一棒子打死。顺带提一句playwright/mcp的--browser参数接受chromium、firefox、webkit三种值默认是chromium。如果你完全不想折腾驱动问题保持默认是最省事的。4.3 清理缓存里的老版本排查过程中我发现缓存目录里堆了很多历史版本。Playwright 每次升级都可能把旧版本留下时间一长就是几个 GB 的垃圾。确定用不到老版本时可以执行npx playwright uninstall --all这个命令会把缓存目录下所有 Playwright 浏览器组件全部卸载。注意它是全部卸载执行完之后记得重新npx playwright install需要的组件。如果你只想删除某个具体版本可以直接手动删除缓存目录下对应的文件夹不影响其他组件。4.4 如果npx playwright install反复失败补装驱动最容易被卡住的一步就是下载。常见报错是连接超时毕竟浏览器二进制包体积不小网络稍微不稳定就断了。我的处理经验是按顺序试这几招。第一招加大超时时间PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT120000 npx playwright install webkit第二招使用镜像下载源。很多国内用户会卡在默认 CDN 上这时可以指定镜像地址PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install webkit这个变量只影响本次下载不会改动项目配置比较干净。第三招如果镜像也没有对应版本手动下载 zip 包解压到缓存目录也是可行的路子但目录名必须严格匹配报错信息里的版本号比如webkit-1403。手动方式偶尔用于救急不建议日常使用。4.5 别急着改系统默认浏览器整个排查过程中我唯一确定无用的操作就是去系统设置里把默认浏览器从 Safari 改成 Chrome。原因前面说过Playwright 不会通过系统的open机制唤起浏览器它直接启动自己的浏览器进程。系统默认浏览器设置影响的是用户手动点击链接时的行为和自动化框架完全是两条路径。与其改系统设置不如花两分钟看一下 MCP Server 的启动参数。5. 验证与后续避坑跑通之后这几个点更值得注意5.1 一套 5 分钟的验证清单修完之后别急着写业务逻辑先把环境验证一遍。第一步确认浏览器组件齐全npx playwright install --dry-run这个命令会列出当前 Playwright 版本对应的所有浏览器组件和安装状态。第二步跑一条最小用例。写到临时文件或者直接在 Node 环境里执行const { webkit } require(playwright); (async () { const browser await webkit.launch({ headless: false }); const page await browser.newPage(); await page.goto(https://example.com); console.log(Title:, await page.title()); await browser.close(); })();如果这条脚本能正常弹出窗口并打印标题说明驱动层面没问题。第三步从 MCP 客户端发一条 tool call观察是否恢复正常。这里特别建议打开 MCP Server 的控制台日志看启动参数是否已经变成chromium。第四步如果你用的是playwright/test的npx playwright test可以用--list确认当前会执行哪些 projectnpx playwright test --list如果列表里出现你不想要的 webkit project记得跑测试时加--projectchromium或者直接从配置文件里删掉 webkit 条目。5.2 后续容易踩的几个坑第一个坑是 headless 参数。MCP Server 默认是有头模式还是无头模式取决于你启动时的参数。调试时希望看到窗口CI 环境里则必须无头否则进程会一直挂在那里。playwright/mcp支持--headless参数建议在配置里明确写出来别依赖默认值。第二个坑是版本漂移。项目从 Playwright 1.40 升到 1.50缓存目录里会同时存在webkit-XXX和webkit-YYY。如果环境变量或启动脚本引用了旧的缓存路径就很容易出现装好了还是报缺失的假象。升级后建议执行一次npx playwright install全量同步把新版组件补齐。第三个坑是权限弹窗。WebKit 和 Chromium 对摄像头、麦克风、通知权限的处理差异很大。同一套用例切到 webkit 可能会多出系统级权限弹窗导致元素点击失败。做跨浏览器回归时这类问题要单独处理别和驱动缺失混在一起查。5.3 关于 Safari 和 Chrome 的选择说点个人体会这次折腾下来我对自动化里浏览器选型的一个理解更具体了日常调试用 Chromium 效率最高启动快、生态工具多、社区踩坑资料也最多但 WebKit 的兼容性验证永远不能省毕竟真实用户里 Safari 占比不低。最舒服的用法就是 MCP 的--browser参数日常设成chromium只在发版前或者做内核专项验证时才切到webkit。这样既不会天天被 Safari 窗口打扰也不会丢失兼容性防线。如果你现在也卡在Playwright 老是要启动 Safari这个问题上按我上面的顺序查一遍——先看 MCP 启动参数再确认驱动是否安装最后检查缓存路径和环境变量大概率十分钟内能解决。别像我一样先去改系统默认浏览器白白浪费半小时。排查环境的思路比记命令本身更重要把视角从系统设置切回框架自己的组件管理逻辑很多类似问题都能迎刃而解。