【playwright】内网环境下的离线部署实战与避坑指南
1. 为什么需要离线部署Playwright？
在企业内部开发环境中，尤其是金融、政务等对安全性要求较高的领域，开发机器通常处于内网隔离状态，无法直接访问互联网。这种情况下，常规的pip install playwright命令会直接报错，因为无法从PyPI下载依赖包。更麻烦的是，Playwright需要下载特定版本的浏览器二进制文件（Chromium/Firefox/WebKit），这些文件体积庞大且必须与Playwright版本严格匹配。
我去年给某银行做自动化测试方案时就遇到过这个难题：测试服务器完全隔离，连代理都没有。当时花了三天时间才摸清完整的离线部署链条，期间踩过的坑包括浏览器版本不匹配、依赖包遗漏、路径权限问题等。下面就把这套经过实战验证的部署方案拆解给大家，包含你可能遇到的所有"坑点"解决方案。
2. 离线环境部署全流程
2.1 准备离线安装包
首先需要在一台能访问互联网的机器上（比如个人笔记本电脑）准备所有依赖文件。这里有个关键细节：必须使用与内网机器相同操作系统的设备。如果你内网是CentOS，就不要用Windows电脑准备安装包，否则浏览器二进制文件会不兼容。
# 创建离线包目录（建议用Python版本号标记） mkdir playwright-py39-offline && cd playwright-py39-offline # 下载Playwright及其依赖（注意保留版本号） pip download playwright==1.40.0这里有个隐藏技巧：使用pip download时默认不会下载所有依赖项。我建议额外加上这些包：
pip download pip setuptools wheel # 基础环境三件套 pip download pytest-playwright # 测试相关组件2.2 浏览器二进制文件处理
Playwright的浏览器管理是个"暗坑"。执行playwright install时，它会根据当前系统类型下载对应的浏览器版本。以Chromium为例：
- Windows版：
ms-playwright/chromium-XXXX/chrome-win - Linux版：
ms-playwright/chromium-XXXX/chrome-linux - macOS版：
ms-playwright/chromium-XXXX/chrome-mac
关键步骤：
- 在联网机器安装Playwright：
pip install ./playwright-1.40.0-py3-none-any.whl - 下载全部浏览器（根据实际需要选择）：
playwright install chromium playwright install firefox playwright install webkit - 找到下载目录（通常位于用户目录下）：
# Linux/macOS ls ~/.cache/ms-playwright # Windows dir %USERPROFILE%\AppData\Local\ms-playwright
3. 内网机器部署实战
3.1 传输文件的注意事项
将准备好的两个压缩包（playwright-offline.tar.gz和ms-playwright.tar.gz）通过U盘或内部文件服务器传输到内网机器时，要注意：
- 使用tar.gz格式而非zip，避免权限信息丢失
- 记录原始文件的MD5校验值：
md5sum playwright-offline.tar.gz md5sum ms-playwright.tar.gz - 在内网机器验证文件完整性：
md5sum -c checksum.md5
3.2 离线安装Python包
在内网机器解压后，使用--no-index参数强制从本地安装：
# 解压离线包 tar -xzvf playwright-offline.tar.gz cd playwright-offline # 离线安装（注意Python解释器路径） /opt/python39/bin/python -m pip install --no-index --find-links=./ playwright常见问题排查：
- 如果报错
No matching distribution found，检查find-links路径是否正确 - 出现
is not a supported wheel on this platform说明打包环境与运行环境不匹配
3.3 部署浏览器二进制
这是最容易出错的环节，需要严格保持路径一致性：
# 解压浏览器包到用户目录 mkdir -p ~/.cache/ms-playwright tar -xzvf ms-playwright.tar.gz -C ~/.cache/验证目录结构应该是：
~/.cache/ms-playwright/ ├── chromium-XXXX/ ├── firefox-XXXX/ └── webkit-XXXX/4. 环境验证与排错指南
4.1 基础功能测试
使用这个增强版验证脚本，可以检查所有关键组件：
from playwright.sync_api import sync_playwright def test_browser(browser_type): try: with sync_playwright() as p: browser = p[browser_type].launch(headless=False) page = browser.new_page() page.goto("about:blank") print(f"{browser_type} version: {browser.version}") browser.close() return True except Exception as e: print(f"{browser_type} failed: {str(e)}") return False results = { "chromium": test_browser("chromium"), "firefox": test_browser("firefox"), "webkit": test_browser("webkit") } print("\nTest summary:") for name, success in results.items(): print(f"{name.upper():<8}: {'✓' if success else '✗'}")4.2 常见错误解决方案
错误1：Browser not found at /wrong/path...
这是路径配置问题，解决方案：
# 方法1：手动指定浏览器路径 from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch( executable_path="/home/user/.cache/ms-playwright/chromium-XXXX/chrome-linux/chrome" )错误2：Could not find browser revision...
浏览器版本不匹配，需要：
- 检查Playwright版本：
pip show playwright - 查看支持的浏览器版本：
playwright install --dry-run
错误3：Protocol error...
通常是权限问题，尝试：
chmod -R 755 ~/.cache/ms-playwright5. 高级部署技巧
对于需要批量部署的场景，我推荐使用Docker构建离线镜像：
FROM python:3.9-slim # 复制离线安装包 COPY playwright-offline /tmp/playwright-offline COPY ms-playwright /root/.cache/ms-playwright # 离线安装 RUN pip install --no-index --find-links=/tmp/playwright-offline playwright \ && rm -rf /tmp/playwright-offline # 设置环境变量（重要！） ENV PLAYWRIGHT_BROWSERS_PATH=/root/.cache/ms-playwright构建命令：
docker build -t playwright-offline:1.40.0 .6. 维护与更新策略
在内网环境中更新Playwright需要特殊流程：
- 在外网机器下载新版本：
pip download playwright==新版本 -d ./playwright-update playwright install --with-deps chromium - 生成版本差异报告：
pip list --outdated --format=freeze > outdated.txt - 按照前文流程重新打包传输
建议在测试环境验证新版本兼容性后再部署到生产环境，特别是注意浏览器兼容性变化。我在某次升级1.38到1.40时就遇到过WebKit API变更导致测试用例失败的情况。