1. 项目概述：内网自动化测试的独特挑战与Playwright的破局之道

在金融、军工、政府或大型企业内部，我们常常需要面对一个特殊的开发与测试环境——内网。这个环境与互联网物理隔离，无法直接访问外部的软件仓库、镜像源和依赖库。当团队决定引入Playwright这样的现代Web自动化测试框架时，挑战就来了：如何在无法连接外网的生产或测试服务器上，完成从Python环境、Playwright库到浏览器驱动的完整部署？这不仅仅是“安装一个包”那么简单，它涉及到依赖的离线打包、环境的一致性保障、以及后续的维护更新策略。

我经历过多次这样的部署，从最初的“手动搬运”到后来的“一键脚本化”，踩过不少坑，也总结了一套相对成熟的方案。这篇文章，我就来详细拆解一下，如何在内网环境中，从零开始部署一套稳定、可维护的Python + Playwright自动化测试环境。无论你是测试开发工程师、运维，还是需要在内网进行CI/CD集成的开发者，这套实战经验都能帮你省去大量摸索的时间。

2. 内网部署的核心思路与方案设计

2.1 为什么内网部署Playwright比Selenium更复杂？

很多朋友可能熟悉Selenium，觉得内网部署无非就是下载个浏览器驱动（如chromedriver）放到PATH里。但Playwright的架构决定了它的部署更“重”一些。Playwright采用客户端-服务器架构，其Python库（playwright）只是一个客户端，真正的“引擎”是它自带的、特定版本的浏览器二进制文件（Chromium, Firefox, WebKit）以及一个名为playwright-driver的服务器进程。

当你执行pip install playwright时，pip不仅会安装Python包，还会在后台自动下载这些浏览器二进制文件到用户目录（如~/.cache/ms-playwright）。在内网环境下，这个自动下载步骤注定会失败。因此，我们的核心思路就是：将所有依赖（Python包、浏览器二进制文件）在能上网的机器上预先准备好，然后完整地搬运到内网机器上。

2.2 整体部署方案选型

针对内网部署，主要有两种主流方案：

1. 方案一：离线Wheel包 + 手动安装浏览器驱动

   • 思路：在能上网的机器上，将playwright及其依赖包下载为.whl文件。同时，使用playwright install命令下载浏览器驱动，然后将这两部分一起拷贝到内网。
   • 优点：步骤清晰，接近标准安装流程，易于理解。
   • 缺点：需要手动管理浏览器驱动的路径，容易因路径问题导致失败。

2. 方案二：使用playwright命令行工具打包

   • 思路：利用Playwright官方提供的CLI工具，直接打包一个包含所有依赖（包括Python包和浏览器）的独立目录或可执行文件。
   • 优点：官方推荐，打包结果更完整、独立，对环境依赖最小。
   • 缺点：需要了解CLI工具的使用，打包文件体积较大。

经过多次实践，我强烈推荐方案二。它不仅更可靠，而且能更好地处理浏览器驱动的版本匹配问题，这是内网部署中最容易出错的地方。本文将重点围绕方案二展开，并补充方案一作为备选或理解之用。

2.3 环境与工具准备清单

在开始之前，请确保你拥有以下条件：

• 一台能连接互联网的“打包机”：操作系统最好与内网目标机器一致（如都是Linux x64），至少架构要相同（如都是x86_64或arm64）。
• 内网目标机器：已安装Python（版本需与打包机一致或兼容，建议使用3.8+）。
• 网络存储或移动介质：用于将打包好的文件从打包机传输到内网机。
• 基础命令行操作知识。

3. 核心部署流程详解：从外网打包到内网落地

3.1 阶段一：在外网打包机上进行完整打包

这个阶段的目标是创建一个包含所有运行时依赖的“绿色版”Playwright环境。

步骤1：在打包机上创建纯净的虚拟环境并安装Playwright为了避免将打包机上的其他包依赖混入，使用虚拟环境是必须的。

# 创建并激活虚拟环境 python -m venv playwright-offline-pack cd playwright-offline-pack source bin/activate # Linux/macOS # 对于Windows: playwright-offline-pack\Scripts\activate # 升级pip pip install --upgrade pip # 安装playwright pip install playwright

注意：这里直接pip install playwright会让pip从PyPI下载并自动安装浏览器。我们正是要利用这个特性，在打包机完成所有下载。

步骤2：验证安装并记录版本信息安装完成后，运行一个简单命令验证，并记录下关键版本，这对后续排查问题至关重要。

python -c “import playwright; print(playwright.__version__)” playwright --version

记下输出的Playwright版本号（例如1.40.0）。

步骤3：使用Playwright CLI进行离线打包这是最关键的一步。Playwright提供了一个playwright install命令的--with-deps选项，但它主要用于安装。对于完整离线打包，我们需要手动定位并复制其缓存目录。

# 找到Playwright的浏览器缓存目录，通常位于用户目录下 # Linux/macOS: ~/.cache/ms-playwright # Windows: %USERPROFILE%\AppData\Local\ms-playwright # 假设我们在用户目录下操作 cd ~ # 创建一个用于存放所有离线文件的目录 mkdir -p playwright-offline-bundle cd playwright-offline-bundle # 1. 导出已安装的Python包列表 pip freeze > requirements.txt # 2. 下载所有依赖包的wheel文件到本地目录 `./wheels` pip download -r requirements.txt -d ./wheels # 3. 复制Playwright的浏览器缓存目录 cp -r ~/.cache/ms-playwright ./ # Windows 对应命令为: xcopy /E %USERPROFILE%\AppData\Local\ms-playwright ms-playwright

现在，你的playwright-offline-bundle目录结构应该类似于：

playwright-offline-bundle/ ├── requirements.txt ├── wheels/ │ ├── playwright-1.40.0-py3-none-any.whl │ ├── greenlet-2.0.2-cp38-cp38-manylinux_x86_64.whl │ └── ... (其他依赖包) └── ms-playwright/ ├── chromium-1084/ ├── firefox-1391/ ├── webkit-1881/ └── playwright-driver-1.40.0/

步骤4：创建部署脚本为了让内网安装过程自动化，我们编写一个安装脚本install_offline.sh(Linux) 或install_offline.bat(Windows)。

Linux安装脚本示例 (install_offline.sh):

#!/bin/bash set -e # 遇到错误立即退出 echo “开始在内网环境安装Playwright离线包...” # 定义目录 WHEELS_DIR=“./wheels” PLAYWRIGHT_CACHE_SOURCE=“./ms-playwright” PLAYWRIGHT_CACHE_TARGET=“${HOME}/.cache/ms-playwright” # 1. 安装所有wheel包 echo “安装Python依赖包...” pip install --no-index --find-links=${WHEELS_DIR} -r requirements.txt # 2. 部署浏览器二进制文件到缓存目录 echo “部署浏览器驱动...” mkdir -p “${PLAYWRIGHT_CACHE_TARGET}” cp -r “${PLAYWRIGHT_CACHE_SOURCE}”/* “${PLAYWRIGHT_CACHE_TARGET}”/ # 3. 验证安装 echo “验证Playwright安装...” python -c “import playwright; print(f‘Playwright版本: {playwright.__version__}’)” playwright --version echo “Playwright离线安装完成！你可以运行 ‘playwright install’ 来验证浏览器驱动（此步骤在内网通常跳过，因为已拷贝）。”

Windows安装脚本示例 (install_offline.bat):

@echo off echo 开始在内网环境安装Playwright离线包... set WHEELS_DIR=.\wheels set PLAYWRIGHT_CACHE_SOURCE=.\ms-playwright set PLAYWRIGHT_CACHE_TARGET=%USERPROFILE%\AppData\Local\ms-playwright echo 安装Python依赖包... pip install --no-index --find-links=%WHEELS_DIR% -r requirements.txt echo 部署浏览器驱动... if not exist “%PLAYWRIGHT_CACHE_TARGET%” mkdir “%PLAYWRIGHT_CACHE_TARGET%” xcopy /E /Y “%PLAYWRIGHT_CACHE_SOURCE%” “%PLAYWRIGHT_CACHE_TARGET%\” echo 验证Playwright安装... python -c “import playwright; print(f‘Playwright版本: {playwright.__version__}’)” playwright --version echo Playwright离线安装完成！ pause

将这两个脚本也放入playwright-offline-bundle目录。至此，打包机上的工作完成。将整个playwright-offline-bundle目录压缩，通过内部网络或U盘拷贝到内网目标机器。

3.2 阶段二：在内网目标机器上进行部署

步骤1：传输与解压将压缩包传到内网机器，并解压到合适目录，例如/opt/playwright-offline。

步骤2：执行部署脚本进入解压后的目录，执行对应的安装脚本。

# Linux cd /opt/playwright-offline chmod +x install_offline.sh ./install_offline.sh # Windows (以管理员身份打开CMD或PowerShell) cd C:\path\to\playwright-offline install_offline.bat

脚本会自动完成所有包的安装和浏览器驱动的部署。

步骤3：功能验证部署完成后，强烈建议编写一个最简单的测试脚本进行验证，而不是直接跑复杂的业务用例。

创建一个文件test_internal.py：

from playwright.sync_api import sync_playwright def test_basic(): with sync_playwright() as p: # 尝试启动无头模式的Chromium browser = p.chromium.launch(headless=True) page = browser.new_page() # 尝试访问一个本地服务或已知的内网地址，如果纯粹测试框架，可以访问 about:blank page.goto(‘about:blank’) title = page.title() print(f“页面标题: {title}”) browser.close() print(“基础功能测试通过！”) if __name__ == “__main__”: test_basic()

运行这个脚本：

python test_internal.py

如果看到“基础功能测试通过！”，恭喜你，最核心的框架部署已经成功。

4. 进阶配置与最佳实践

4.1 浏览器驱动的版本管理与更新

内网环境最大的痛点之一是更新。Playwright版本和浏览器驱动版本是强绑定的。当你需要升级时，必须在打包机上重复“阶段一”的过程，生成新版本的离线包，然后在内网进行替换。

我的经验是：在项目的README或部署文档中，明确记录当前内网环境使用的Playwright版本号、以及对应的浏览器驱动版本（可以在ms-playwright目录下的子目录名中看到）。升级时，务必先在测试环境验证新版本与现有自动化测试用例的兼容性。

4.2 集成到内网CI/CD流水线

部署好环境后，下一步就是让自动化测试跑起来。在内网Jenkins或GitLab CI上运行Playwright脚本，需要注意几点：

1. 环境变量：确保CI节点的PATH包含了Python和Playwright驱动所在路径。有时需要显式设置PLAYWRIGHT_BROWSERS_PATH环境变量，指向你部署的ms-playwright目录，但这在我们的部署脚本中通过复制到默认缓存目录已经解决。
2. 无头模式与显示服务器：Linux CI服务器通常没有图形界面。Playwright支持无头模式（headless=True），这是默认行为，可以直接运行。但如果你的测试涉及截图对比等需要渲染的功能，可能需要一个虚拟显示服务器，如xvfb。

   # 在Jenkins Pipeline的步骤中 sh ‘xvfb-run --auto-servernum --server-args=“-screen 0 1280x1024x24” python your_test_script.py’

3. 依赖隔离：为每个CI项目使用独立的Python虚拟环境，避免包冲突。我们的离线包可以安装到项目的虚拟环境中。

4.3 处理内网特有的页面与认证

内网应用常常有复杂的登录认证（如域认证、统一SSO）。Playwright提供了强大的上下文（Context）API来处理这类场景。

• 存储状态复用：你可以先在本地（或一个认证服务器）用脚本完成一次登录，然后将浏览器上下文的状态（cookies, localStorage）保存下来。

  # 登录并保存状态 context = browser.new_context() page = context.new_page() # ... 执行登录操作 context.storage_state(path=“auth.json”)

  在内网CI中，可以预先准备好这个auth.json文件（注意安全！），然后在测试开始时加载。

  # 加载认证状态 context = browser.new_context(storage_state=“auth.json”) page = context.new_page() # 此时页面已处于登录状态

• HTTP认证：如果网站使用基础HTTP认证，可以在URL中直接携带或使用page.goto的extra_http_headers参数，但更安全的方式是在创建上下文时配置。

  context = browser.new_context( http_credentials={“username”: “user”, “password”: “pass”} )

5. 常见问题与故障排查实录

在内网部署过程中，你几乎一定会遇到下面这些问题。这里我把踩过的坑和解决方案整理出来，希望能帮你快速定位。

5.1 浏览器启动失败或找不到

这是最常见的问题，通常表现为Error: Failed to launch browser或Executable doesn‘t exist at ...。

• 问题原因1：浏览器驱动未正确部署

  • 排查：检查内网机器上~/.cache/ms-playwright(或对应Windows路径) 目录是否存在，并且里面的子目录（如chromium-1084）是否完整。对比文件大小和数量与外网打包机是否一致。
  • 解决：确保部署脚本中的复制命令执行成功，并且有足够的权限。对于Linux，注意.cache目录的权限问题，有时需要手动chmod -R。

• 问题原因2：动态库缺失（Linux常见）

  • 排查：Playwright的Chromium依赖一些系统库，如libnss3,libatk-bridge2.0-0等。在内网最小化安装的Linux服务器上可能缺失。
  • 解决：在打包机上使用ldd命令检查依赖，然后在内网机安装对应包。或者，更推荐使用Playwright的Docker镜像作为CI运行环境，它能完美解决依赖问题。在内网部署私有Docker Registry并拉取mcr.microsoft.com/playwright/python镜像，是更一劳永逸的方案。

• 问题原因3：权限问题

  • 排查：浏览器二进制文件需要可执行权限。
  • 解决：进入ms-playwright下的浏览器目录，执行chmod -R +x .确保所有文件有执行权限。

5.2 Python包安装失败

• 问题原因：wheel文件与平台不兼容
  • 排查：pip install时报错包含 “…none-any.whl is not a supported wheel on this platform.” 或类似信息。
  • 解决：这通常是因为打包机（如macOS）和内网机（如Linux）操作系统或架构不同。务必保证打包环境与目标环境一致。最稳妥的方法是在一台与内网机系统版本完全一致（或至少是相同架构的Linux发行版）的机器上做打包。

5.3 测试运行时超时或卡死

• 问题原因1：内网代理或防火墙

  • 排查：即使访问about:blank或本地localhost也超时。
  • 解决：Playwright启动浏览器时可能会尝试连接某些谷歌服务（如崩溃报告）。在内网需要禁用这些。通过浏览器启动参数设置：

    browser = p.chromium.launch( headless=True, args=[‘--no-sandbox‘, ‘--disable-dev-shm-usage‘, ‘--disable-gpu‘, ‘--disable-setuid-sandbox‘, ‘--no-zygote‘, ‘--disable-features=NetworkService‘] )

    --disable-features=NetworkService在某些网络严格受限的环境下可能有帮助。

• 问题原因2：资源不足

  • 排查：内网测试服务器内存或CPU资源紧张。
  • 解决：限制Playwright使用的资源。可以尝试禁用GPU加速、减少并发测试数，或者使用更轻量的浏览器（如WebKit通常比Chromium内存占用小）。

5.4 如何验证所有浏览器都可用？

部署完成后，运行一个简单的检查脚本：

from playwright.sync_api import sync_playwright def check_browsers(): with sync_playwright() as p: for browser_type in [p.chromium, p.firefox, p.webkit]: try: print(f“正在检查 {browser_type.name}...”) browser = browser_type.launch(headless=True, timeout=30000) page = browser.new_page() page.goto(‘about:blank’) browser.close() print(f“ {browser_type.name} 检查通过！”) except Exception as e: print(f“ {browser_type.name} 检查失败: {e}”) if __name__ == “__main__”: check_browsers()

6. 备选方案与优化建议

6.1 方案一的补充：使用pip download和playwright install --dry-run

如果你坚持使用方案一（离线wheel+手动安装驱动），可以更精确地控制浏览器版本。

# 在打包机 pip download playwright -d ./wheels # 下载特定版本的浏览器驱动 playwright install --dry-run chromium # 这会输出下载链接，你可以用内网下载工具提前下好 # 然后手动组织目录结构，通过环境变量 PLAYWRIGHT_BROWSERS_PATH=0 playwright install 来指向离线目录

这种方法更繁琐，且容易因版本细微差异导致问题，仅作为对方案理解或特殊需求下的备选。

6.2 容器化部署：终极解决方案

对于有条件的内网环境，使用Docker是最佳实践。微软官方提供了Playwright的Python镜像。

1. 在外网拉取镜像：docker pull mcr.microsoft.com/playwright/python:v1.40.0
2. 将镜像保存为文件：docker save -o playwright-python.tar mcr.microsoft.com/playwright/python:v1.40.0
3. 将tar文件导入内网Docker：docker load -i playwright-python.tar
4. 在CI中直接使用该镜像作为运行环境。

这种方式完美解决了系统依赖、环境隔离和版本一致性问题，是团队协作和持续集成的首选。

6.3 编写一个健壮的内网部署脚手架

对于需要频繁在多台内网机器部署的场景，可以将上述所有步骤脚本化，形成一个脚手架工具。这个工具应该包含：

• 版本检查与提示。
• 依赖的系统包检查（针对Linux）。
• 备份旧版本和回滚功能。
• 部署后自动运行健康检查测试。

内网部署Playwright自动化测试环境，核心在于“离线化”和“一致性”。通过在外网机器预先打包完整的运行时环境（Python包+浏览器驱动），并在内网通过脚本化方式部署，可以构建一个稳定可靠的测试基础。过程中，最需要关注的是环境一致性（操作系统、架构）和浏览器驱动的完整性。当环境搭建起来后，结合Playwright强大的API和上下文管理能力，即使面对复杂的内网认证应用，也能构建出高效的自动化测试体系。