如果你也被pip install playwright卡到怀疑人生大概率是没意识到Playwright 的安装不是一个动作而是两段独立下载。第一段是拉取 Python 包第二段是拉取浏览器内核。只要把这两段的下载源都换成国内镜像安装时间就能从十几分钟变成一两分钟。这篇文章不聊怎么用 Playwright 写脚本专门解决 Python 3.8 环境下怎么给它安装提速以及安装前后最容易踩到的坑。适合刚接触自动化测试、被安装劝退的新人也适合要在 CI 环境里反复安装的老手。1. 卡了一下午才装好先搞清楚慢在哪两个环节1.1 你以为的慢和实际的慢不是一回事很多人第一次装 Playwright觉得不就跟装别的库一样嘛一行pip install playwright搞定。实际上执行完这条命令pip 只是把一个不大的 Python 包装了进去这个包本身只有几 MB在正常网速下几秒钟就能拉完。但紧接着如果你直接写脚本运行十有八九会报错提示找不到浏览器可执行文件。原因在于 Playwright 的独特设计它不像 Selenium 那样需要你自己去下载 ChromeDriver 或者对应版本的浏览器而是通过playwright install命令把配套的 Chromium、Firefox、WebKit 内核单独拉下来。这一步才是整个安装流程里真正的“重头戏”。单个浏览器压缩包动辄几十 MB甚至上百 MB而且默认是从官方 CDN 下载。国内网络环境下这一环节经常出现连接超时、传输中断、进度条卡死的情况。这也是为什么我见过不少同事在第一步换源之后高兴没两秒又卡在了playwright install chromium这一步。他们以为装完 Python 包就万事大吉根本没意识到 Playwright 是“包装”和“内核”两件事。1.2 顺着下载链路拆解提速空间想要提速不能只盯着一处猛调。下面我把两条独立链路拆开看链路 Apip从 PyPI 源下载 Playwright 的 Python 包。这个环节的瓶颈在于 pip 默认指向官方 PyPI跨海链路慢丢包率高。链路 Bplaywright install从官方浏览器下载服务器拉取浏览器二进制包。瓶颈同样在物理距离和带宽质量而且包体更大表现得更明显。所以提速思路很清晰链路 A 换 pip 国内镜像源链路 B 通过环境变量或者手动放置的方式把浏览器二进制下载也导向国内镜像或本地。两条链路都加速安装过程才能真正“飞”起来。另外还有一个经常被忽略的点缓存目录。Playwright 下载完浏览器之后会解压到系统的一个缓存目录里如果这个目录没有写权限或者被某些安全软件拦截安装也会失败。这个我在后面的排查部分会专门提到。2. Python 包安装提速给 pip 换一个国内镜像源2.1 临时用一次-i参数如果你只是想快速试一下不想动全局配置最省事的办法是安装时加上-i参数临时指定一个国内镜像源pip install -i https://mirrors.example.com/pypi/simple playwright注意https://mirrors.example.com/pypi/simple只是一个占位示例你需要把它替换成自己实际要用的镜像地址。不同镜像站的 URL 结构可能略有不同有的会带simple路径有的不带建议去镜像站首页看它给出的 pip 配置示例。这种临时指定的方式好处是零副作用不会影响系统里其他 Python 项目。坏处是每次安装都得手打参数而且在安装依赖比较多的项目时很容易忘掉-i又回到龟速下载。我建议你装之前可以先拿一个小包试试速度比如requests对比一下不同源在本地网络环境下的真实表现。毕竟“快不快”这件事和你的宽带运营商、你所在的区域关系很大别人说好用的源到你那儿不一定是最快的。2.2 永久改配置pip config如果你不是只在命令行偶尔装一个库而是会长期使用 Python 做开发那直接改掉默认源是更一劳永逸的方案。用 pip 自带的配置命令就能完成pip config set global.index-url https://mirrors.example.com/pypi/simple执行完可以再用pip config list确认是否设置成功。设置之后你后续所有的pip install都会默认走这个镜像源不用再每次加-i。这个命令会在当前用户目录下生成或修改 pip 配置文件。对大多数开发场景来说这已经足够了。但有一点要提醒全局配置会影响这台机器上所有 Python 环境包括不同虚拟环境。如果你手头同时在维护多个项目而不同项目对依赖下载源有特殊要求那就不要用全局配置而是用项目级配置。2.3 项目隔离配置文件与环境变量更精细的做法是在虚拟环境级别指定 pip 源。当你激活某个虚拟环境之后pip 会优先读取当前环境目录下的配置文件。常见的配置文件位置如下Linux/macOS 用户级~/.config/pip/pip.confLinux/macOS 虚拟环境级venv路径/pip.confWindows 用户级%APPDATA%\pip\pip.iniWindows 虚拟环境级venv路径\pip.ini在没有pip config set命令行工具的时候也可以手动创建这些文件。内容很简单[global] index-url https://mirrors.example.com/pypi/simple trusted-host mirrors.example.comtrusted-host这一行是在使用非 HTTPS 或证书有特殊情况的源时才需要如果镜像站是正规 HTTPS一般不用加。还有一个方式是通过环境变量PIP_INDEX_URL指定export PIP_INDEX_URLhttps://mirrors.example.com/pypi/simple这种方式适合在 CI 脚本里用既不影响本机配置又能保证每次构建时统一行为。说白了就是把配置外置让脚本和环境分离。2.4 镜像源的选择原则经常有人问我到底该选哪个源。我的建议是不要只看名气要看同步速度和网络连通性。开源的 pip 镜像站不少维护水平有高有低。选源的时候可以留意这么几点同步频率。至少应该每小时从官方 PyPI 同步一次否则你可能装不到最新版本的包。运营商访问速度。不同源对不同运营商的表现差异很大用curl -I或者实际 pip 拉包速度测试更靠谱。是否提供 Playwright 浏览器二进制的镜像。少数综合镜像站会把浏览器二进制也一并同步这种源对安装提速的帮助是双倍的。如果你在公司内网那优先看公司是否自建了 PyPI 代理。内网源在速度和一致性上通常远胜公网源。3. 浏览器内核下载提速PLAYWRIGHT_DOWNLOAD_HOST与环境目录3.1 用环境变量把浏览器下载导到国内镜像pip源解决了 Python 包的下载速度但浏览器二进制下载默认不走 pip 源它用的是 Playwright 自己的一套下载机制。要让它提速需要设置一个环境变量PLAYWRIGHT_DOWNLOAD_HOST。这个变量就是用来指定浏览器二进制文件的下载基地址的。做法很简单export PLAYWRIGHT_DOWNLOAD_HOSThttps://cdn.example.com/playwright playwright install chromium在 Windows PowerShell 里写法是$env:PLAYWRIGHT_DOWNLOAD_HOSThttps://cdn.example.com/playwright playwright install chromium设置之后Playwright 会去这个基础地址下找对应平台的浏览器压缩包下载速度取决于这个镜像服务在你网络环境下的表现。需要提醒的是不是随便填一个镜像地址就能用。这个地址必须确实提供了 Playwright 浏览器二进制文件并且目录结构要和官方保持兼容。去镜像站首页找它自己的 Playwright 镜像说明照着它给的环境变量值填才是最靠谱的。有些镜像服务还会顺带把浏览器驱动等文件一起同步这种体验最佳。3.2 提前下载浏览器压缩包并手动放置有些场景下目标机器网络受限或者镜像站没有合适的浏览器文件。这时候最硬核但最可靠的办法就是“人肉搬运”在一台网络通畅的机器上把 Playwright 和浏览器都装好然后把整个浏览器缓存目录打包传到目标机器上解压。Playwright 的浏览器缓存目录默认路径如下Windows%USERPROFILE%\AppData\Local\ms-playwrightmacOS~/Library/Caches/ms-playwrightLinux~/.cache/ms-playwright打包命令可以用tar -czf ms-playwright.tar.gz -C ~/.cache ms-playwright传到目标机器后解压到相同路径即可。如果目标机器的系统版本不同建议还是重新用playwright install走一遍因为浏览器二进制和系统库的兼容性可能会出问题。手动放置时千万注意目录结构。Playwright 会根据版本号生成类似chromium-1049这样的目录里面才是真正的可执行文件。如果你手痒改了目录名Playwright 会找不到对应版本报Executable doesnt exist之类的错。3.3 自定义浏览器缓存目录如果你有多个项目共用同一个浏览器缓存或者 CI 构建机想避免反复下载可以设置PLAYWRIGHT_BROWSERS_PATH来指定浏览器统一存放的位置export PLAYWRIGHT_BROWSERS_PATH/opt/playwright-browsers playwright install chromium设置之后不管你新建多少虚拟环境只要这个环境变量保持一致Playwright 都会去同一个目录找浏览器。这样做的好处非常明显你只需要完整下载一次浏览器之后切换项目时不会再触发下载也不会因为不同项目用了不同 Playwright 版本而重复下载大体积文件。不过要小心如果你手动清理这个共享目录一定要先确认当前项目依赖的浏览器版本号还在。我就见过有人在清理磁盘时把还在用的旧版本目录随手删了结果一跑脚本又开始重新下载白白浪费了半小时。4. 安装后的 5 分钟验证从导入到跑通最小脚本4.1 三步验证法安装提速搞定了不代表万事大吉。我习惯用三步验证确保整个链路是通的。第一步验证 Python 包是否正常python -c from playwright.sync_api import sync_playwright; print(ok)如果能输出ok说明 Playwright 的 Python 包已经可以导入。如果这一步就报错那是环境和包的问题先检查虚拟环境有没有激活。第二步验证浏览器内核是否就位playwright install --list这个命令会列出当前 Playwright 版本里所有可用的浏览器及其安装状态。看到chromium对应的状态是installed才说明浏览器内核真的装好了。第三步写一个最小脚本真实启动浏览器访问页面。我一般用官方保留的示例域名比如https://example.com避免访问外部站点带来的不确定因素from playwright.sync_api import sync_playwright with sync_playwright() as p: browser p.chromium.launch(headlessTrue) page browser.new_page() page.goto(https://example.com) print(page.title()) browser.close()能正常打印出标题就说明从 Python 包到浏览器内核、再到系统依赖整条链路已经畅通。这一步做完后续写自动化脚本时就不会再被环境问题反复打断。4.2 最小启动代码与常见报错对照上面那段代码虽然简单但能暴露不少问题报错Executable doesnt exist at ...说明浏览器内核没装或者PLAYWRIGHT_BROWSERS_PATH指向错了。报错No module named playwright说明当前解释器不是安装 Playwright 的那个环境检查which python或者python --version指向哪里。报错PlaywrightException: Browser closed多半是系统缺少浏览器运行依赖尤其常见于精简版 Linux 服务器。报错Permission denied是缓存目录没有写权限用sudo或修改目录所有者也可以像前面那样指定一个可写的PLAYWRIGHT_BROWSERS_PATH。如果你是在一台刚装好的 Linux 服务器上操作最省心的方式是直接运行playwright install --with-deps chromium这个命令会在安装浏览器的同时尝试用系统包管理器补齐所有缺失的共享库。注意它需要管理员权限因为它会调用包管理器。如果不想改系统全局也可以用--with-deps之外的方式后期再单独补库。5. 高频问题排查速查表5.1 一张表格搞定安装期问题我把实际踩过、以及身边同事踩过的问题汇总成了一张速查表按问题现象、可能原因、解决思路三列来列方便你在遇到问题时快速定位。问题现象可能原因解决思路pip install超时或速度极慢默认源是官方 PyPI配置国内镜像源用-i或pip config setCould not find a version that satisfies the requirement playwright镜像同步不及时或包名写错换同步频率高的镜像检查拼写和版本约束playwright install卡在下载进度条前段浏览器二进制直连官方 CDN 慢设置PLAYWRIGHT_DOWNLOAD_HOST为国内镜像地址Executable doesnt exist at ...未执行playwright install或缓存路径/版本目录不对执行playwright install检查PLAYWRIGHT_BROWSERS_PATHModuleNotFoundError: No module named playwright安装到别的 Python 环境当前环境找不到激活正确的虚拟环境用python -m pip install重新装Browser closed或Missing dependenciesLinux 系统缺少浏览器运行库playwright install --with-deps 浏览器名Permission denied浏览器缓存目录无写入权限给目录授权或通过PLAYWRIGHT_BROWSERS_PATH指定可写目录下载文件校验失败hash mismatch下载中断或镜像文件不完整清掉缓存重新下载或换个镜像源再试5.2 几个我踩过的还真没人写的坑先说第一个坑把 pip 换源当成全部。刚开始我也以为只要 PyPI 源快了整个安装就快了。结果装完包运行playwright install chromium进度条纹丝不动。这时候才意识到Playwright 的浏览器下载走的是另一套通道。所以后来我在任何教程里都会强调两个环境变量要同时关注PIP_INDEX_URL和PLAYWRIGHT_DOWNLOAD_HOST。第二个坑用sudo pip install装包。尤其是 Linux 系统有人习惯直接sudo pip install playwright结果包被装到了系统 Python 目录下。之后在虚拟环境里怎么都 import 不到。正确思路是先创建并激活虚拟环境再在里面安装。如果你确实需要装到系统环境也别用pip直接python -m pip install能避免一部分环境错乱的问题。第三个坑手动下载浏览器时版本目录名对不上。Playwright 每次发版都可能把浏览器更新到新版本缓存目录名是带版本号的比如chromium-1084这种。你可千万别觉得版本号不好看就改成chromiumPlaywright 是严格按照版本目录去查找的。改错名后即使浏览器文件就在那里它也不认。第四个坑反复重装导致缓存目录越占越大。ms-playwright目录里通常会有多个版本的浏览器时间久了硬盘很容易被吃到只剩几个 G。建议隔一段时间清理一次但清理前先用playwright install --list确认当前项目到底依赖哪个版本手里的项目跑着跑着突然要求重新下载那就很耽误事了。6. 顺手把安装流程固化成脚本进阶6.1 写一个跨平台的安装脚本等到你把这些步骤都理清了就很值得把它们固化成一个脚本让新环境一键完成安装。下面是一个 Linux/macOS 下的 Bash 脚本示例#!/bin/bash set -e export PIP_INDEX_URLhttps://mirrors.example.com/pypi/simple export PLAYWRIGHT_DOWNLOAD_HOSThttps://cdn.example.com/playwright python -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install playwright1.40.0 playwright install --with-deps chromium脚本里的版本号和 URL 都是示意实际使用时替换成你自己选定的版本和镜像地址。--with-deps在 Linux 上会自动安装系统依赖如果你不想让脚本改动系统环境可以去掉它手动补依赖。Windows 用户可以写成批处理或者 PowerShell 脚本$env:PIP_INDEX_URL https://mirrors.example.com/pypi/simple $env:PLAYWRIGHT_DOWNLOAD_HOST https://cdn.example.com/playwright python -m venv .venv .venv\Scripts\Activate.ps1 pip install --upgrade pip pip install playwright1.40.0 playwright install chromium写脚本的价值不只是省事最重要的是让所有环境保持一致的安装姿势避免每个人按自己的方式操作最后出现“我这能跑你那不能跑”的问题。6.2 团队协作时如何统一版本和环境如果你是在团队里协作开发我强烈建议把 Playwright 的版本写进requirements.txt而不是不加版本号地安装。Playwright 的浏览器版本是跟随 Python 包版本走的所以只要包版本锁定了浏览器内核版本也基本锁定团队里每个人下载的内核是一致的。在 README 里把安装提速需要设置的环境变量写清楚让新成员照着粘贴就好。不要默认每个人都懂PLAYWRIGHT_DOWNLOAD_HOST是什么意思。我在团队里还见过一个现象成员在本地已经装好了一到 CI 环境又装不上后来发现是 CI 脚本里少了环境变量。如果是 CI 环境还可以把ms-playwright目录纳入缓存策略。第一次构建时下载完整浏览器后续构建如果缓存命中就直接使用能省下不少时间。不过要注意缓存 key 里必须包含 Playwright 的版本信息否则版本升级后你还在复用旧缓存一样会出问题。我把这套流程整理成内部文档后团队新人在一台新电脑上从零装好 Playwright 的时间基本控制在三分钟以内。踩过那么多次坑最大的感受是安装问题绝大多数是“源”和“环境”的问题和代码无关。你提前把下载链路和缓存目录规划好后面写自动化脚本时就不会被环境问题反复打断。