1. 项目概述与核心痛点

最近在帮一个老项目做自动化测试迁移，环境被钉死在了 Python 3.7.9 上，同时需要集成 Playwright 1.9.0 来做浏览器自动化。本以为就是几条 pip install 命令的事，结果从安装到跑通第一个脚本，足足折腾了大半天，踩遍了几乎所有能遇到的坑。从令人困惑的“绿色导入”警告，到恼人的 SSL 证书验证失败，再到浏览器驱动下载卡住，每一步都可能有“惊喜”。如果你也正被类似的环境问题困扰，特别是那些因为项目历史原因或依赖兼容性而无法升级 Python 版本的情况，那么这篇从实战中总结出来的避坑指南，或许能帮你省下好几个小时的搜索和试错时间。这篇文章会详细拆解在 Windows 和 Linux 环境下，如何一步步搞定这个特定版本组合的安装与配置，并重点解决那些官方文档可能一笔带过，但实际工作中高频出现的报错。

2. 环境准备与前置条件解析

2.1 为什么是 Python 3.7.9 和 Playwright 1.9.0？

首先得聊聊为什么会有这种看似“过时”的版本组合需求。Python 3.7 系列在 2023 年 6 月已结束安全支持，而 Playwright 也早已迭代了无数个版本。但在企业级开发中，尤其是维护周期较长的项目，环境冻结是常态。可能因为某个核心的 C 扩展库只兼容到 Python 3.7，或者项目依赖的框架（如某些旧版的 Django、TensorFlow）与更高版本的 Python 存在冲突。Playwright 1.9.0 是一个相对早期的稳定版本，它可能被锁定是因为其 API 与后续版本有较大变化，而现有的数百个测试脚本来不及重构。因此，我们的目标不是追求最新，而是在限定条件下搭建一个稳定、可用的自动化环境。

2.2 系统环境与工具准备

无论你的主力系统是 Windows 还是 Linux（包括 WSL2），以下准备工作是通用的：

1. 确认 Python 版本 ：首先在终端或命令提示符中输入 python --version 或 python3 --version ，确保显示的是 Python 3.7.9 。如果不是，你需要先安装或切换到这个特定版本。对于 Windows，建议使用官方安装包；对于 Linux，可以使用 pyenv 工具来精确管理多个 Python 版本，这是最干净的方法。
2. 升级 pip 和 setuptools ：老版本的 pip 在安装一些依赖时可能会出问题。使用 python -m pip install --upgrade pip setuptools wheel 将它们升级到较新的版本。注意，这里用的是 python -m pip 的调用方式，这能确保你使用的是当前 Python 环境下的 pip，避免因为系统存在多个 Python 而调用错误。
3. 网络环境准备 ：Playwright 安装过程中需要从 GitHub Releases 等地址下载浏览器二进制文件（Chromium, Firefox, WebKit），这些文件体积较大（约 100-200 MB 每个）。确保你的网络能够稳定访问这些资源。如果身处内网或受限环境，需要提前准备好代理或离线安装方案，这部分我们会在后面详细展开。

注意：强烈建议在虚拟环境中进行操作，例如使用 venv 或 conda 。这能完美隔离项目依赖，避免污染系统级的 Python 环境。创建命令： python -m venv playwright_env ，然后激活它。

3. 分步安装流程与避坑实操

3.1 使用 pip 安装 Playwright 1.9.0

最直接的安装命令是：

pip install playwright==1.9.0

但在这里，我们很可能遇到第一个坑。由于 Playwright 1.9.0 发布已久，其依赖的某些包（如 pyee ， websockets ）的版本范围可能与现在 PyPI 上的最新版不兼容。pip 的默认行为是尝试安装满足条件的最新依赖，这有时会导致冲突。

避坑策略 1：使用约束安装 一个更稳妥的方法是，先让 pip 解析出所有兼容的依赖版本，再进行安装。我们可以利用 pip install 的 --dry-run 和 --report 选项（较新 pip 版本支持），或者更简单点，直接使用 pip install 的 --no-deps 选项跳过依赖安装，然后手动安装已知兼容的版本。不过，对于 Playwright 1.9.0，一个经过验证的可行依赖组合是：

pip install playwright==1.9.0

在大多数干净的虚拟环境中，这条命令可以直接成功。如果失败，观察报错信息，通常是某个依赖包版本不兼容。例如，如果报错关于 pyee ，可以尝试先安装一个较旧的兼容版本： pip install pyee==8.2.2 ，然后再安装 playwright。

避坑策略 2：离线安装包准备 对于完全离线的环境，你需要在一台有网的机器上，使用 pip download 命令下载所有依赖的 wheel 包：

pip download playwright==1.9.0 -d ./playwright_packages --platform manylinux1_x86_64 --only-binary=:all: --python-version 37 --abi cp37m

参数解释：

• -d ./playwright_packages : 指定下载目录。
• --platform : 指定目标平台（如 win_amd64 对应 Windows 64位， manylinux1_x86_64 对应 Linux）。
• --only-binary=:all: : 只下载二进制包（wheel），避免下载源码包（tar.gz）可能需要的编译环境。
• --python-version 37 和 --abi cp37m : 精确指定 Python 3.7 的 ABI，确保兼容性。

然后将整个目录拷贝到离线环境，使用 pip install --no-index --find-links=./playwright_packages playwright==1.9.0 进行安装。

3.2 安装浏览器二进制文件

安装完 Python 包后，需要安装 Playwright 管理的浏览器。执行：

playwright install

这个命令会下载 Chromium、Firefox 和 WebKit 的二进制文件到用户目录下的缓存文件夹中（例如 ~/.cache/ms-playwright on Linux/Mac， %USERPROFILE%\AppData\Local\ms-playwright on Windows）。

核心大坑：SSL 证书验证失败与网络超时 这是本指南要解决的最常见问题。在运行 playwright install 时，你可能会看到类似以下的错误：

Error: Failed to download chromium, caused by
Error: read ECONNRESET

或者

Error: Unable to download browser from https://...: SSL certificate problem: unable to get local issuer certificate

解决方案全集：

1. 使用国内镜像源（推荐首选） ：Playwright 允许通过环境变量指定下载镜像。对于国内用户，使用腾讯云镜像可以极大提升速度和成功率。

• Windows (CMD/PowerShell) :

  set PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
  playwright install
  

• Windows (PowerShell) :

  $env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"
  playwright install
  

• Linux/macOS :

  PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright playwright install
  

  或者永久设置到 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc ）:

  export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
  

2. 跳过 SSL 证书验证（临时方案，有安全风险） ：如果镜像源也不可用，或者遇到严格的证书验证问题，可以设置环境变量让 Node.js（Playwright 底层使用）跳过 SSL 验证。 注意：这仅在完全信任的网络环境中临时使用。

set NODE_TLS_REJECT_UNAUTHORIZED=0 # Windows CMD
$env:NODE_TLS_REJECT_UNAUTHORIZED=0 # Windows PowerShell
export NODE_TLS_REJECT_UNAUTHORIZED=0 # Linux/macOS

设置后再运行 playwright install 。

3. 手动下载与离线安装 ：如果网络问题无法解决，这是终极方案。

• 首先，在有网环境查看需要下载的精确文件。运行 playwright install --dry-run 会输出需要下载的文件的 URL。
• 根据你的操作系统和架构，手动从官方仓库（或镜像站）下载这些压缩包。例如，对于 Chromium on Windows，文件名可能类似 chromium-win64.zip 。
• 在目标机器上，找到 Playwright 的浏览器缓存目录（路径见上文）。将下载的压缩包 直接解压到对应的浏览器目录下 。例如，将 chromium-win64.zip 解压到 %USERPROFILE%\AppData\Local\ms-playwright\chromium-XXXX 目录下（ XXXX 是版本号文件夹，可能需要先创建）。
• 关键一步：在缓存目录中，创建一个名为 INSTALLATION_COMPLETE 的空文件。Playwright 通过检查这个文件来判断浏览器是否已安装成功。

3.3 验证安装与“绿色导入”警告

安装完成后，写一个简单的脚本验证：

# test_playwright.py
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False) # 首次测试建议用非无头模式，看得见浏览器
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

运行 python test_playwright.py 。

“绿色导入”警告是什么？ 你可能会在导入 playwright 或 playwright.sync_api 时，看到控制台输出一些绿色的文字，内容大概是提示你运行 playwright install 来安装浏览器。这不是一个错误（Error），而是一个警告（Warning）。它发生在 Playwright Python 包成功导入，但检测到系统缓存目录中没有对应的浏览器二进制文件时。

为什么会出现？

• 你只安装了 playwright Python 包，但没有运行 playwright install 。
• playwright install 安装的浏览器路径没有被正确识别（例如，环境变量 PLAYWRIGHT_BROWSERS_PATH 被设置到了其他目录，但当前环境没使用这个变量）。
• 浏览器缓存目录被误删除或损坏。

如何解决？

1. 如果还没安装浏览器，直接运行 playwright install 。
2. 如果已经安装，检查浏览器是否在预期位置。可以运行 python -c “import playwright; print(playwright.__file__)” 找到包位置，但浏览器不在包内。更直接的方法是，在代码中临时添加以下内容来检查：

   import os
   print(os.path.expanduser(‘~/.cache/ms-playwright’)) # Linux/Mac
   # print(os.path.expandvars(‘%USERPROFILE%\\AppData\\Local\\ms-playwright’)) # Windows
   

   看看该目录下是否存在 chromium-XXXX 这样的文件夹。
3. 如果路径不对，你可以通过环境变量 PLAYWRIGHT_BROWSERS_PATH 明确指定浏览器所在目录，然后重启你的 Python 解释器或 IDE。

4. 高级配置与疑难杂症排查

4.1 配置浏览器启动参数与上下文

Playwright 的强大之处在于其丰富的启动和上下文选项，可以模拟各种真实场景。在 Python 3.7.9 + 1.9.0 环境下，这些配置同样有效。

常用启动参数示例：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # 启动 Chromium，配置视窗大小、忽略 HTTPS 错误、使用代理等
    browser = p.chromium.launch(
        headless=False, # 显示浏览器窗口
        slow_mo=100, # 将每个操作放慢100毫秒，方便观察
        args=[
            ‘--disable-blink-features=AutomationControlled‘, # 隐藏自动化控制痕迹（部分网站会检测）
            ‘--window-size=1920,1080‘
        ],
        # 如果公司网络需要代理
        # proxy={
        #     ‘server‘: ‘http://myproxy.com:8080‘,
        #     ‘username‘: ‘user‘,
        #     ‘password‘: ‘pass‘
        # }
    )
    # 创建浏览器上下文，可以独立设置视口、User-Agent、地理位置等
    context = browser.new_context(
        viewport={‘width‘: 1366, ‘height‘: 768},
        user_agent=‘Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ...‘,
        ignore_https_errors=True # 忽略 HTTPS 证书错误，用于测试环境
    )
    page = context.new_page()
    page.goto(‘https://whatsmyuseragent.org/‘)
    print(page.content())
    context.close()
    browser.close()

4.2 典型报错与解决方案速查表

下表整理了在这个特定版本环境下，除了安装问题外，运行时可能遇到的典型错误及解决方法。

报错信息/现象	可能原因	解决方案
TimeoutError: Timeout 30000ms exceeded.	页面加载太慢、元素定位不到、网络延迟。	1. 增加超时时间： page.wait_for_selector(‘selector‘, timeout=60000) 。 2. 检查选择器是否正确，页面是否已加载完成。 3. 使用 page.wait_for_load_state(‘networkidle‘) 等待网络空闲。
Error: Page closed	在页面关闭后尝试对其进行操作。	确保你的操作逻辑在页面生命周期内。检查是否有异步操作导致页面提前关闭。使用 try...except 捕获该异常进行容错处理。
Error: Target closed	类似 Page closed，通常是浏览器上下文或浏览器本身被关闭。	检查 browser.close() 或 context.close() 的调用时机，确保在完成所有操作后才关闭。
playwright._impl._api_types.Error: Protocol error (Target.createTarget): Target closed.	通常发生在多页面或复杂异步操作时，底层通信协议出错。	1. 简化脚本，确保同步操作顺序。 2. 尝试使用 browser.new_context() 和 context.new_page() 来更清晰地管理页面生命周期，而不是直接 browser.new_page() 。 3. 升级到 Playwright 1.9.0 内的最新小版本（如 1.9.2），有时小版本修复了协议稳定性问题。
脚本执行无误，但浏览器无响应或白屏	浏览器二进制文件损坏，或与当前系统图形库不兼容。	1. 尝试安装依赖库：在 Ubuntu/Debian 上 sudo apt install libgbm1 libasound2 ；在 CentOS/RHEL 上 sudo yum install alsa-lib atk at-spi2-atk cups-libs gtk3 libXcomposite libXdamage libXrandr mesa-libgbm 。 2. 删除缓存目录中的浏览器文件，重新运行 playwright install 。 3. 尝试以无头模式运行 ( headless=True )，看是否正常。
ImportError: cannot import name ‘X‘ from ‘playwright‘	Python 包版本与代码语法不匹配。Playwright 1.x 早期版本 API 可能有变动。	确认你的脚本代码是针对 Playwright 1.9.0 的。查阅 Playwright 1.9.0 的官方 Python API 文档 来核对导入语句和用法。避免使用从新版本教程中照搬的代码。

4.3 在 CI/CD 环境中的配置要点

在 Jenkins、GitLab CI、GitHub Actions 等持续集成环境中配置此环境，需要特别注意：

1. 缓存浏览器二进制文件 ：每次流水线都下载几百兆的浏览器是不现实的。利用 CI 系统的缓存机制（如 GitHub Actions 的 actions/cache ）缓存 Playwright 的浏览器目录（ ~/.cache/ms-playwright ）。这能极大缩短构建时间。
2. 安装系统依赖 ：Linux CI 镜像通常是最小化安装，缺少浏览器运行所需的图形库。必须在安装 Playwright 前，通过包管理器安装这些依赖。例如，对于 GitHub Actions 的 ubuntu-latest 镜像，需要在步骤中添加：

   - name: Install system dependencies
     run: |
       sudo apt-get update
       sudo apt-get install -y libwoff1 libopus0 libwebp6 libwebpdemux2 libenchant1c2a libgudev-1.0-0 libsecret-1-0 libhyphen0 libgdk-pixbuf2.0-0 libegl1 libgles2 libevent-2.1-7
       # 上述是部分依赖，更全的列表可参考 Playwright 官方文档
   

3. 使用无头模式 ：在 CI 中务必设置 headless=True （这是默认值）。对于更复杂的渲染测试，可以考虑使用 xvfb 来模拟一个虚拟显示服务器。
4. 环境变量 ：记得在 CI 的配置中设置可能需要的环境变量，如 PLAYWRIGHT_DOWNLOAD_HOST 指向国内镜像，以确保下载成功。

5. 从1.9.0迁移到更新版本的考量

虽然本文聚焦于锁定版本的安装，但了解如何迁移也是有价值的。如果你未来有机会升级，从 Playwright 1.9.0 迁移到较新的版本（如 1.40.0），主要关注以下几点：

1. API 变更 ：较新的版本中，一些同步 API 的命名可能更规范，异步 API ( async/await ) 的支持更成熟。需要仔细阅读官方迁移指南，逐项修改 API 调用。例如，早期版本的一些 waitForX 方法可能已被更通用的 wait_for_X 替代。
2. 浏览器版本 ：新版本的 Playwright 会捆绑更新的浏览器二进制文件，这意味着网页的渲染和行为可能略有不同，需要回归测试。
3. 依赖兼容性 ：更高版本的 Playwright Python 包可能需要更高版本的 Python（如 3.8+）。在升级前，需要评估整个项目 Python 版本升级的可行性。
4. 功能增强 ：新版本会带来更多强大的功能，如更好的网络拦截、移动设备模拟、组件测试等，升级可以解锁这些能力，但也要评估学习成本和改造工作量。

对于当前被 Python 3.7.9 锁定的项目，更务实的做法可能是将 Playwright 的版本也长期锁定在 1.9.0，并围绕它构建稳定的测试套件，而不是追求版本的新特性。稳定性往往是老旧项目自动化测试的第一要务。