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 playwright1.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-winLinux版ms-playwright/chromium-XXXX/chrome-linuxmacOS版ms-playwright/chromium-XXXX/chrome-mac关键步骤在联网机器安装Playwrightpip 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-playwright3. 内网机器部署实战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.md53.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(headlessFalse) 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 常见错误解决方案错误1Browser 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 )错误2Could not find browser revision...浏览器版本不匹配需要检查Playwright版本pip show playwright查看支持的浏览器版本playwright install --dry-run错误3Protocol 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 --formatfreeze outdated.txt按照前文流程重新打包传输建议在测试环境验证新版本兼容性后再部署到生产环境特别是注意浏览器兼容性变化。我在某次升级1.38到1.40时就遇到过WebKit API变更导致测试用例失败的情况。