1. 项目背景与核心需求
最近在帮客户部署自动化测试环境时遇到一个典型问题：生产服务器处于内网隔离环境，无法直接联网安装Playwright这类依赖浏览器二进制文件的测试工具。这种场景在企业级开发中非常常见——金融、政务等行业的合规要求往往需要完全离线的开发环境。
Playwright作为微软开源的现代化自动化测试工具，凭借其跨浏览器（Chromium/Firefox/WebKit）支持、自动等待机制和可靠的执行结果，正在逐步取代传统的Selenium方案。但其安装过程需要下载约300MB的浏览器二进制文件，这对没有外网访问权限的环境构成了实质性障碍。
2. 离线安装方案设计思路
2.1 核心问题拆解
实现Playwright离线安装需要解决三个关键点：
- 获取完整的安装包集合（包括Python包和各平台浏览器二进制）
- 处理二进制文件的平台兼容性问题（Windows/Linux/macOS）
- 确保离线环境下的依赖解析正确
2.2 技术选型对比
| 方案 | 优点 | 缺点 |
|---|---|---|
| 手动下载缓存 | 完全可控 | 操作繁琐，易遗漏依赖 |
| pip download | 自动获取Python包 | 不包含浏览器二进制 |
| playwright cli | 官方工具链支持 | 需要二次开发 |
| 容器镜像打包 | 环境隔离完整 | 镜像体积过大 |
最终选择组合方案：使用pip download获取Python包 + playwright install下载浏览器 + 手动整理依赖树。这个方案在可靠性和复杂度之间取得了最佳平衡。
3. 详细实施步骤
3.1 准备联网环境
bash复制# 创建干净的虚拟环境
python -m venv ./playwright-offline
source ./playwright-offline/bin/activate # Linux/macOS
./playwright-offline/Scripts/activate # Windows
# 下载Python包及其依赖
pip download playwright -d ./offline-packages --platform manylinux1_x86_64 \
--python-version 38 --implementation cp
关键参数说明：
-d指定下载目录--platform指定目标系统平台--python-version需与目标环境一致--implementation指定CPython
3.2 下载浏览器二进制
bash复制# 安装Playwright但不执行自动安装
pip install --no-deps playwright
playwright install --dry-run # 查看需要下载的组件
# 实际下载所有浏览器（约需15分钟）
playwright install chromium firefox webkit
下载的浏览器二进制默认存储在：
- Linux/macOS:
~/Library/Caches/ms-playwright - Windows:
%USERPROFILE%\AppData\Local\ms-playwright
3.3 整理离线包
建议目录结构：
code复制playwright-offline/
├── python-packages/ # pip download下载的.whl文件
├── browsers/ # 浏览器二进制目录
│ ├── chromium-XXXX/
│ ├── firefox-XXXX/
│ └── webkit-XXXX/
└── install.sh # 安装脚本
4. 离线环境部署实战
4.1 传输注意事项
-
使用
rsync保持文件权限（特别是Linux环境）bash复制
rsync -azP ./playwright-offline user@target:/opt/ -
Windows系统需确保长路径支持（注册表启用
EnableWin32LongPaths）
4.2 离线安装命令
bash复制# 安装Python包（需先配置pip源指向本地目录）
pip install --no-index --find-links=./python-packages playwright
# 部署浏览器二进制
mkdir -p ~/.cache/ms-playwright
cp -r ./browser/* ~/.cache/ms-playwright/
4.3 验证安装
python复制import playwright
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()
5. 常见问题解决方案
5.1 浏览器启动失败
现象：Browser closed unexpectedly错误
排查步骤：
- 检查二进制路径权限
bash复制ls -l ~/.cache/ms-playwright/ - 验证依赖库
bash复制
ldd ~/.cache/ms-playwright/chromium-XXXX/chrome-linux/chrome
解决方案：
- 缺少
libnss3等库时，需离线安装系统依赖 - 设置环境变量强制使用特定路径
bash复制export PLAYWRIGHT_BROWSERS_PATH=/opt/playwright/browsers
5.2 证书问题
现象：HTTPS网站报安全错误
解决方法：
python复制context = browser.new_context(
ignore_https_errors=True,
bypass_csp=True
)
5.3 多平台兼容
针对异构环境（如开发机Windows+服务器Linux）：
- 为每个平台单独下载浏览器
bash复制
PLAYWRIGHT_DOWNLOAD_HOST=linux playwright install chromium PLAYWRIGHT_DOWNLOAD_HOST=mac playwright install chromium - 在安装脚本中自动识别系统类型
bash复制case "$(uname -s)" in Linux*) platform=linux;; Darwin*) platform=mac;; CYGWIN*) platform=win;; esac
6. 高级技巧与优化
6.1 增量更新方案
-
使用
pip-tools管理依赖版本bash复制
pip-compile requirements.in pip-sync requirements.txt -
浏览器二进制差分更新
bash复制
playwright install --with-deps chromium@stable
6.2 容器化部署
Dockerfile示例：
dockerfile复制FROM python:3.8-slim
COPY ./offline-packages /tmp/packages
RUN pip install --no-index --find-links=/tmp/packages playwright \
&& rm -rf /tmp/packages
COPY ./browsers /root/.cache/ms-playwright
ENV PLAYWRIGHT_BROWSERS_PATH=/root/.cache/ms-playwright
6.3 性能调优
-
复用浏览器实例
python复制browser = p.chromium.launch_persistent_context( user_data_dir="/tmp/profile", headless=False ) -
调整启动参数
python复制browser = p.chromium.launch( args=["--single-process"], timeout=30000 )
在实际企业级部署中，我们通过这种离线方案成功在20多个隔离网段完成了Playwright的批量部署。关键是要确保二进制文件的完整性校验（建议使用sha256sum）和安装脚本的幂等性设计。对于需要更高安全性的场景，还可以考虑对浏览器二进制进行代码签名。