2. 开篇Playwright 到底卡在哪一步做自动化测试或者爬虫的朋友应该都对 Playwright 不陌生。它的定位很直接一套 API 同时驱动 Chromium、Firefox、WebKit 三大浏览器内核录制脚本、自动等待、多标签页管理这些能力开箱即用比早期的 Selenium 方案省心不少。但有个问题始终绕不过去——在国内环境安装 Playwright下载速度是真的难受。很多人卡在pip install playwright或者npm i playwright这一步进度条半天不动最后超时失败。我最初接触这个项目时装一次 Playwright 前后折腾了一个多小时失败三次才成功。后来把整个安装链路拆开看了一遍发现慢的原因其实很清晰第一层是 Python 包或 npm 包本身的下载第二层是安装后还要执行playwright install去拉取浏览器内核这两个环节都依赖网络源只要其中一个慢整体安装体验就会非常差。这篇东西就是把我后来沉淀下来的一整套提速方案整理出来从镜像源配置讲起最后落到一个一键安装脚本上。目标很明确让一条干净的命令在几分钟内跑完整个安装流程不管你用的是 pip 还是 npm都能直接抄作业。适合正在被 Playwright 安装问题折磨的测试开发、爬虫工程师以及刚入门自动化测试但还不熟悉国内环境加速套路的朋友。3. 拆解安装链路为什么慢慢在哪里3.1 安装分几个阶段每个阶段吃什么网络资源Playwright 的安装不是一条命令就完事的它内部明显分为两个大阶段。第一个阶段是运行时核心库的安装比如pip install playwright拉取的其实只是 Python 客户端代码和内置的 driver这个包本身不算特别大但依赖有些零碎。第二个阶段才是大头执行playwright install chromium或者不指定浏览器直接全装此时会去下载对应浏览器内核的压缩包。以 Chromium 为例单个包体积通常在 150MB 到 200MB 之间Firefox 和 WebKit 也类似三个浏览器全装合计超过 500MB 很常见。问题在于这两个阶段的下载源默认都指向国外服务器。Python 包默认走 PyPInpm 包默认走官方 registry浏览器二进制则是从 Playwright 自己维护的 CDN 地址拉取。国内访问这些源的时候延迟高、带宽不稳定有时候甚至直接连接重置。尤其是浏览器二进制这一步经常出现下载到一半断掉的情况而 Playwright 的下载逻辑遇到中断后不会自动续传只会报错让你重试体验非常糟糕。还有一个很多人忽略的阶段是系统依赖安装。在 Linux 环境下执行playwright install --with-deps会调用系统的包管理器去安装一堆动态链接库比如 libnss3、libatk 这类。如果是 Debian 系会用 apt-get如果是 Fedora 系会用 dnf。这一步同样走系统软件源如果你的服务器软件源没配置成国内镜像光装依赖也可能卡半天。3.2 提速的核心逻辑把三个下载源全部换掉理解了阶段划分后提速方案其实就一句话把 Python 包下载源、npm 包下载源、浏览器内核下载源全部替换为国内可稳定访问的镜像地址。这三者缺一不可只换其中一两个安装过程还是会卡在最慢的那个环节上。先说 Python 包这一层。针对 pip最通用的做法是配置清华源或者阿里源。我个人推清华源多一点因为它同步频率高、稳定性好而且对 Playwright 这种更新节奏快的库比较友好。配置方式有两种一种是临时指定-i参数另一种是写进全局配置文件。临时参数适合一次性操作全局配置则适合长期使用后者更省事。npm 这边类似用淘宝镜像registry.npmmirror.com是主流选项。npm 的镜像切换也是两种方式命令行临时指定或者用.npmrc文件固定。浏览器二进制这一层是 Playwright 特有的。Playwright 默认下载浏览器时会从一个固定的 CDN 地址拼接版本号和文件名后发起请求。它提供了环境变量PLAYWRIGHT_DOWNLOAD_HOST来覆盖这个基础地址国内一般使用https://npmmirror.com/mirrors/playwright/这个镜像路径。设置好这个环境变量后再执行playwright install下载速度会有质的提升。提示PLAYWRIGHT_DOWNLOAD_HOST环境变量是 Playwright 官方支持的配置项不是第三方 hack所以不用担心版本升级后失效的问题。它从很早期的版本就存在目前所有主流版本都兼容。把这三层逻辑理清楚之后剩下的就是怎么优雅地把它们组合起来写成一个别人拿到就能用的安装脚本。4. 镜像配置实操pip、npm、系统源三步走4.1 pip 源配置从临时参数到全局配置先看最常见的情况用 pip 安装 Python 版的 Playwright。如果你只是临时想装一次可以直接带上-i参数pip install playwright -i https://pypi.tuna.tsinghua.edu.cn/simple这样做的问题是后续如果你要升级 Playwright或者装其他比较冷门的库还得再手动带一次参数很容易忘。而且有些工具链在内部调 pip 时并不会继承你这个命令行参数就会重新落入默认源。所以我一般建议直接把源写进 pip 配置。Linux 环境下pip 的配置文件在~/.pip/pip.conf或者~/.config/pip/pip.conf不同版本有点差异。一个比较保险的做法是手动创建~/.pip/pip.conf文件写入以下内容[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cnWindows 环境下配置文件的路径通常是%APPDATA%\pip\pip.ini内容是一样的。这里有个细节trusted-host这行不是必需的因为清华源本身有有效的 HTTPS 证书但如果你所在的环境有额外的证书代理或者你用的是一个非标准端口的内部镜像加上trusted-host可以减少一些麻烦。配置完成之后试着执行一遍pip config list或者直接再日常安装一个小库验证下。如果输出里的index-url变成了清华源的地址就说明配置生效了。4.2 npm 源切换临时指定与持久化配置Node.js 生态的 Playwright 安装路径是另一条独立链路。基础的安装命令是npm i playwright如果没配置镜像npm 会直接去官方 registry 拉包。Playwright 的 npm 包加了一堆依赖虽然不至于像浏览器二进制那么大但下载速度依然受制于网络状况。临时指定镜像的命令是这样npm i playwright --registryhttps://registry.npmmirror.com持久化配置则可以直接改项目根目录的.npmrc文件写入registryhttps://registry.npmmirror.com如果你有多个项目要管理也可以在用户主目录下维护一个全局.npmrc作用域更广。这里提醒一句.npmrc的配置优先级是项目级大于用户级大于全局级所以如果你发现某个项目安装还是走了官方源先看看项目目录下有没有一个写错内容的.npmrc把它覆盖了。npm 包安装完成之后同样需要执行npx playwright install来下载浏览器内核。这一步的环境变量配置方式和 pip 版完全一致后面单独说。4.3 系统依赖源Linux 用户别漏掉这一层前面提到过Linux 环境下如果执行playwright install --with-deps会触发系统包管理器的依赖安装。以 Ubuntu/Debian 系为例它会调apt-get update然后安装一批包。如果你的/etc/apt/sources.list里还是默认的官方源那apt-get update的速度就基本取决于你对官方源的实际访问速度。我个人的习惯是先把 apt 源换成清华源或者阿里源。Ubuntu 的源配置文件在/etc/apt/sources.list也有新版系统拆分成/etc/apt/sources.list.d/下的独立文件。换源有一个易踩的坑不同 Ubuntu 版本对应的源地址格式略有差异不能随便抄一个就上去。建议去清华源网站找到对应版本号的配置复制后替换。替换完成后一定要执行sudo apt-get update确认输出里没有报错再继续。如果apt-get update就失败那后续的依赖安装一定会失败所以这一步其实是整个 Playwright 安装流程的前置条件别等脚本跑挂了才回头排查。CentOS/RHEL 系则是配置/etc/yum.repos.d/下的 repo 文件把mirrorlist和baseurl替换成国内地址这里不展开细说用 CentOS 的朋友应该已经有一套自己的习惯了。5. 浏览器内核下载提速环境变量与验证方法5.1 设置 PLAYWRIGHT_DOWNLOAD_HOST 的正确姿势浏览器内核下载是整个过程里最耗时的部分也是提速效果最明显的地方。Playwright 官方支持通过环境变量自定义浏览器下载地址核心就是PLAYWRIGHT_DOWNLOAD_HOST。最基本的用法是每次安装前在当前 shell 窗口导出生效export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ playwright install如果你用的是 Windows 的 PowerShell$env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ playwright install但这种方式有个问题环境变量只在当前会话里有效换一个终端窗口又得重新设置。所以更好的做法是把它写进 shell 的配置文件。bash 用户写到~/.bashrczsh 用户写到~/.zshrc在文件末尾追加export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/之后每次打开终端这个变量就自动生效了。5.2 镜像地址的选择一个就够了别患选择困难症浏览器内核镜像地址现在其实不少常见的有https://npmmirror.com/mirrors/playwright/和https://playwright.azureedge.net这个不是国内镜像不推荐。还有一个思路是可以用PLAYWRIGHT_DOWNLOAD_HOST指向你自己的内网服务器或者对象存储如果你所在团队有统一的二进制分发平台完全可以把自己下载好的浏览器包传到内网然后把环境变量指向内网地址。这样团队成员安装时完全不走外网速度最快。但个人使用或小团队场景下我实测下来 npmmirror 的 Playwright 镜像已经足够稳定没必要自己再包一层服务。它的目录结构和 Playwright 官方 CDN 保持一致路径拼接规则也兼容直接替换主机名就行。这里要说清楚一个细节设置环境变量只需指定到镜像的根路径不要在后面多拼具体的浏览器版本路径。Playwright 内部会自己去拼接chromium-XXXXX.zip这样的文件名。如果你多写了一段路径反而会导致 404。5.3 验证下载源是否生效从日志里找线索设置完环境变量之后怎么确认配置真的生效了最简单的方法是看 Playwright 的下载日志。执行playwright install chromium时正常输出会显示当前正在从哪个 URL 下载文件。如果你看到类似Downloading from https://npmmirror.com/mirrors/playwright/...这样的输出就说明环境变量已经生效。如果输出显示的仍然是官方 CDN 地址那说明环境变量没被正确读取。这时候依次检查三件事第一环境变量名是否拼写正确PLAYWRIGHT_DOWNLOAD_HOST注意是DOWNLOAD_HOST不是DOWNLOAD_URL我见过多次拼错的情况第二当前 shell 是否执行过source ~/.bashrc或重启过终端第三是否有代理工具在拦截环境变量。5.4 pnpm 和 yarn 用户怎么处理现在很多前端项目用 pnpm 而不是 npmPlaywright 的安装命令也对应变化但环境变量的逻辑不变。pnpm 安装 Playwright 包pnpm add playwright然后:npx playwright install这里npx playwright install其实就是在调用 Playwright CLI 做浏览器下载和 npm 安装后执行的命令是同一个。yarn 用户也一样核心的浏览器下载逻辑都封装在 Playwright CLI 内部只要你设置了PLAYWRIGHT_DOWNLOAD_HOST它就会读取。有个别版本在 pnpm 下遇到过一个奇怪问题浏览器二进制下载完后还会做一次完整性校验如果校验失败会重试但重试的时候没有再次读取环境变量导致重复失败。这种情况通常发生在早期版本后来的版本已经修掉了。如果还有人遇到最简单的绕法是把PLAYWRIGHT_DOWNLOAD_HOST同时写进系统的全局环境变量和项目的.env文件双保险。6. 一键安装脚本从零到能跑测试的完整流程6.1 脚本设计思路先探测环境再分步安装有了前面这些配置手动安装已经很顺畅了但人总会犯错而且团队里每个人都要手动配置一遍也很烦。所以更有价值的部分是把它封装成一个一键脚本。脚本的目标是在一台几乎全新的机器上一条命令完成所有安装工作最终能够顺利运行 Playwright 的示例测试。设计脚本时我遵循了几个原则。第一幂等性脚本可以重复执行不会因为之前跑过一半而报错。第二尽量少干扰系统不擅自修改系统级的配置文件改为在项目目录或用户级别写配置。第三失败要可识别每步结束都检查退出码有问题就停下来输出提示而不是黑盒式地继续。脚本语言我选择 bash因为它在绝大多数 Linux 环境里开箱即用macOS 也默认带了 bash。Windows 环境则可以单独写一个 PowerShell 版本或者建议直接使用 WSL 后在 Linux 环境里跑这个 bash 脚本这样适配性更好。6.2 核心实现环境变量、pip/npm 双支持、浏览器下载看一段完整的 bash 脚本核心部分#!/usr/bin/env bash set -e PYPI_MIRRORhttps://pypi.tuna.tsinghua.edu.cn/simple NPM_MIRRORhttps://registry.npmmirror.com PLAYWRIGHT_CDN_MIRRORhttps://npmmirror.com/mirrors/playwright/ export PLAYWRIGHT_DOWNLOAD_HOST$PLAYWRIGHT_CDN_MIRROR echo 配置 pip 源 mkdir -p ~/.pip cat ~/.pip/pip.conf EOF [global] index-url $PYPI_MIRROR trusted-host pypi.tuna.tsinghua.edu.cn EOF echo 配置 npm 源 if [ -f .npmrc ]; then echo .npmrc echo registry$NPM_MIRROR .npmrc else echo registry$NPM_MIRROR .npmrc fi echo 安装 Python 版 Playwright if command -v pip3 /dev/null 21; then pip3 install playwright elif command -v pip /dev/null 21; then pip install playwright else echo 未找到 pip/pip3请先安装 Python exit 1 fi echo 安装 Node 版 Playwright可选 if command -v npm /dev/null 21; then npm install playwright --registry$NPM_MIRROR fi echo 安装浏览器内核 if command -v playwright /dev/null 21; then playwright install chromium else python3 -m playwright install chromium fi echo 完成这段脚本有几个细节值得展开。首先set -e让脚本在任意一条命令返回非零退出码时立即停止避免后面继续跑一些没有意义的内容。其次pip 源配置直接写入了~/.pip/pip.conf这一层是用户级的不需要 sudo但要注意如果之前已经存在这个文件且里面有自定义配置直接用cat 覆盖可能把原有内容冲掉。更保险的写法是先备份再覆盖。npm 源配置写到了项目级.npmrc这样只影响当前项目不会全局干扰。但如果你这台机器上所有项目都用默认官方源也没配过其他私有源直接写到用户级~/.npmrc也完全可以看使用习惯。6.3 只装 Chromium 还是全装合理取舍脚本里我只写了playwright install chromium没有把三个浏览器全部装齐。这是因为在实际的自动化测试和爬虫场景里Chromium 占据了绝大多数用例Firefox 和 WebKit 更多用在浏览器兼容性测试里。全部安装意味着要多下载两三百 MB 的包很多场景根本用不上平白增加安装时间和磁盘占用。如果你的需求确实需要多浏览器内核把脚本里的安装命令展开成playwright install chromium firefox webkit就可以了。但注意WebKit 的包体积不小而且它在 Linux 下编译得比较晚版本更新也慢一些如果不是明确要做 WebKit 内核的测试我通常不建议主动装。在 macOS 上playwright install webkit有时候还会遇到一些系统权限问题比如需要额外的开发者工具组件。这种问题不会在安装脚本层面体现而是第一次启动 WebKit 环境时报错属于另一个维度的坑了。6.4 脚本的可扩展性参数化与超时控制上面这个基础脚本可以进一步优化。比如允许通过命令行参数传入浏览器列表./install_playwright.sh firefox webkit实现方式是在脚本里用$接收额外参数如果没有传就默认chromium。还可以加超时控制防止某个下载任务长时间卡住不报错也不完成timeout 180 curl -fsSL -o /dev/null -w %{http_code} $PLAYWRIGHT_DOWNLOAD_HOST || { echo 无法访问镜像地址请检查网络 exit 1 }这个探测请求放在脚本的最前面比较合适提前发现网络不通比跑到一半才发现有意义得多。6.5 Docker 场景下的一键化思路如果你的 Playwright 跑在容器里那脚本的思路要稍微变一下。用 Docker 官方镜像mcr.microsoft.com/playwright的话其实镜像内部已经帮你装好了浏览器和系统依赖你只需要在构建自己镜像时设置环境变量即可。但国内拉取mcr.microsoft.com的镜像速度可能也比较感人。解决办法是在 Dockerfile 里直接设置 Playwright 的下载镜像并用 apt 镜像源来装系统依赖FROM ubuntu:22.04 ENV PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ RUN sed -i s/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g /etc/apt/sources.list \ apt-get update apt-get install -y python3 python3-pip RUN pip3 install playwright -i https://pypi.tuna.tsinghua.edu.cn/simple \ playwright install --with-deps chromium这样构建镜像的过程就会快不少但注意在 Dockerfile 里设置ENV PLAYWRIGHT_DOWNLOAD_HOST之后如果后续执行playwright install命令环境变量一定会被读取这个方式比在 base image 里预先下载更可控一些。7. 常见问题与排查技巧实录7.1 下载进度条卡住不动是不是要等这个是新手最容易陷入的困境。Playwright 下载浏览器的时候进度条有时候长时间停在某几个百分比上但网络其实还在跑只是显示不够平滑。我的经验是先观察五分钟如果五分钟内进度条一点没动而且某一侧的网卡流量统计也完全没有变化基本可以判断当前离线了。这时候直接开新的安装命令前先不要急着重试。因为 Playwright 每次下载失败重试都是从头开始的不会续传。正确做法是检查当前是否有人正在下载或者是代理策略有问题然后确认镜像地址可访问后重新执行。实测中如果网络环境能稳定访问 npmmirror 镜像这个卡住的情况会变得极少。7.2 浏览器下载成功但启动时报缺少系统库这个问题的表现是playwright install看上去一切正常浏览器文件也完整下载了但真正执行playwright.launch()时弹出类似error while loading shared libraries: libnss3.so这样的错误。原因是浏览器内核是编译好的二进制文件运行它需要系统里有一堆动态链接库。解决办法是使用 Playwright 自带的依赖检测能力playwright install-deps它会自动对照当前系统的包管理器和 Playwright 要求的依赖列表把缺失的库补装完。在 Ubuntu 上这个命令会执行一系列apt-get install在 Fedora 上则调用dnf install。如果你的网络源没换这步可能也会慢所以前面说的系统源配置要提前做好。7.3 公司内网环境有代理但证书不信任公司内网开发环境下很多人会配置 HTTP 代理来访问外网。Playwright 下载浏览器时走的还是常规的 HTTP/HTTPS 请求所以它会透传HTTP_PROXY、HTTPS_PROXY这些标准环境变量。但有个隐患如果你的代理服务器是自签证书的而系统根证书里没有它那 HTTPS 请求会直接失败。这时候不要尝试去信任一个你拿不准的证书再说先明确一个范围命令行工具下载阶段受代理影响大浏览器内核运行阶段通常不受影响。如果你只想解决安装问题可以设置环境变量跳过验证export NODE_TLS_REJECT_UNAUTHORIZED0但这是开发调试用的临时手段不建议长期使用。更稳妥的做法是把公司的根证书加入系统信任链这个可以让运维的同事给一份统一说明。7.4 pip 安装成功但命令行找不到 playwright如果你用 pip 安装的是用户级而不是系统级比如加了--user参数那么playwright这个命令行工具可能不在 PATH 里。这时候要么直接把安装路径找出来配置到 PATH要么干脆不依赖命令行改成 Python 代码里调用from playwright.sync_api import sync_playwright with sync_playwright() as p: browser p.chromium.launch() page browser.new_page() page.goto(https://example.com) print(page.title()) browser.close()这段代码不依赖命令行只要 Python 能 import playwright 成功就能正常跑。所以很多时候我并不强求playwright命令在 PATH 里能跑代码就行。7.5 如何确认所有浏览器都下载完整如果下载过程中有某一次失败之后重新执行playwright install可能会发现它跳过了之前已经下载成功的部分。Playwright 的机制是浏览器内核解压后放在用户缓存目录Linux 在~/.cache/ms-playwright/下下次安装时检测到这个目录里有对应版本的文件就会认为这一步已完成直接跳过。所以如果你想彻查所有浏览器文件是否完整就去看这个缓存目录。里面每个子目录对应一个浏览器进入子目录后会有对应的可执行文件。用 Chromium 的话通常能看到chrome-linux/chrome这样的路径。如果某个浏览器目录存在但里面文件明显不完整删掉这个目录再重新执行对应的playwright install [browser]就好。这个缓存目录的位置可以通过环境变量PLAYWRIGHT_BROWSERS_PATH修改如果你想把浏览器内核下载到项目目录里一起打包分发这个环境变量是很好的工具。只是注意修改路径后Playwright 会认为新的路径是唯一存储位置旧的缓存就不再管了。8. 收尾我的实际经验和一点额外建议整套方案用下来我最直观的感受是Playwright 在国内环境安装的痛点本质上不是工具本身的问题而是网络链路上多个环节没有一个统一的加速方案。单独看每一步改镜像、设环境变量都不复杂但如果你不系统化地处理就会反复在某个随机环节上卡住。我个人的习惯是在新机器上部署 Playwright 之前先把三样东西准备好pip 的全局镜像配置、npm 的 registry 配置、以及PLAYWRIGHT_DOWNLOAD_HOST的导出。这三样配齐后安装流程几乎不会遇到什么意外。然后才是跑脚本。说到脚本再补充一个实际操作中用得比较多的小技巧脚本里加一个自动写入环境变量的步骤。虽然前面建议把环境变量写进.bashrc但有些团队会用别的 shell或者在 CI 环境里根本不会加载.bashrc。所以最开始那一版脚本里我用的是export指令这只对当前会话有效。如果你面向的是 CI 场景更合适的方式是直接在任务的全局环境变量里配置好PLAYWRIGHT_DOWNLOAD_HOST或者把导出语句写进 CI 平台的预构建命令里。另外关于浏览器内核的版本匹配问题也要小心。Playwright 升级版本后通常会对应新的浏览器内核版本如果你只升级了 Python 包但没有重新执行playwright install运行时可能会提示浏览器内核版本不匹配。版本不一致时Playwright 会明确报错不会默默跑起来所以这一点不用太担心只要记得升级后手动跑一次安装脚本就行。反过来说如果你想固定整个环境建议在项目里锁住 Playwright 版本避免偶尔的自动升级打乱浏览器内核的对应关系。最后分享一个我在多人协作项目里的做法把整个安装脚本纳入项目仓库不放在个人目录下。新同事入职或者换新机器时一条命令拉完代码再跑一次脚本所有环境就绪。过程中如果有人遇到问题更新脚本本身也比各自口头传递经验要可靠得多。脚本里所有镜像地址都抽成了变量以后如果某个镜像地址失效了改一行就能全局替换维护成本很低。Playwright 本身是个好工具安装这一关跨过去后后面编写用例、调试脚本的过程会顺很多。希望这套镜像配置加一键脚本的思路能帮你少走一些我当年走过的弯路。