最后更新：2026 年 10 月 31 日。

如何在 GitHub Actions 中运行多地区 Playwright 测试

电商网站可能会根据访客的网络位置，展示不同的货币、地区 URL 以及市场专属内容。如果只从一个网络位置测试网站，就很难了解网站在不同地区的实际表现。

本文将使用 Python、Playwright、Pytest、GitHub Actions 和不同国家的住宅代理，从美国、英国和德国运行同一套 GeoIP 测试。

测试目标是 Geolizr Shopify Demo Store ，使用的测试脚本是 KindProxy GeoIP Benchmark 仓库 中的 tests/test_geolizr_geoip.py 。

本文只使用这一份 Geolizr 测试脚本。GitHub Actions 负责调度不同地区的任务，Python 测试脚本负责执行浏览器检测。我们不会另外创建通用的 test_region.py，也不会再实现第二套多网站测试逻辑。

目录

• 工作流的作用
• 获取项目
• 了解测试环境
• 在本地安装依赖
• 在 GitHub 中配置代理凭据
• 添加 GitHub Actions 工作流
• 启用 CI 前先在本地运行测试
• 在 GitHub Actions 中查看结果
• 常见 GitHub Actions 问题
• 保护凭据并避免不必要的流量
• 常见问题
• 总结
• 自行运行多地区代理测试

工作流的作用

工作流会针对配置的每个地区运行一个独立 Job：

每个 Job 会执行以下操作：

1. 检出同一个 GitHub 仓库。
2. 安装 Python 依赖和 Chromium。
3. 从 GitHub Secrets 中读取对应地区的代理凭据。
4. 运行 tests/test_geolizr_geoip.py。
5. 上传 Pytest 测试结果文件，以便任务结束后查看。

测试会分别检查代理实际出口国家和网站的本地化行为。这一点很重要：修改浏览器 locale 并不会改变公网 IP 地址，而 IP 查询结果也不能单独证明网站已经展示了预期的市场内容。

1. 获取项目

克隆 GitHub 仓库：

git clone https://github.com/kindproxy/kindproxy-geoip-benchmark.git
cd kindproxy-geoip-benchmark

本文涉及的测试文件是：

tests/test_geolizr_geoip.py

仓库中还包含依赖列表、Pytest 配置和示例环境变量配置。请以仓库当前的文件为准，不需要另外复制或创建一套测试脚本。

2. 了解测试环境

本测试使用三个地区的住宅代理出口，访问同一个 Geolizr Demo Store 进行对比。

浏览器 Context 与代理连接分别配置。代理决定网络路由和公网出口 IP；Playwright 的浏览器 Context 则控制 locale、timezone 等浏览器设置。

为了让对比更有意义，建议在不同地区的测试中保持浏览器设置一致。如果每次测试都改变 locale 或 timezone，就很难判断页面差异究竟来自代理位置，还是浏览器配置。

测试还会为运行创建新的浏览器 Context，以尽量避免之前访问留下的 Cookie 或 Local Storage 影响当前结果。

3. 在本地安装依赖

创建并启用 Python 虚拟环境：

python -m venv .venv

macOS 或 Linux：

source .venv/bin/activate

Windows PowerShell：

.venv\Scripts\Activate.ps1

安装项目依赖和 Chromium：

python -m pip install -r requirements.txt
python -m playwright install chromium

在全新的 Linux 环境中，Chromium 可能还需要操作系统级依赖。如果浏览器无法启动，请参考 Playwright Python 安装文档 ，安装所需的浏览器依赖。

4. 在 GitHub 中配置代理凭据

工作流需要代理网关以及每个地区对应的认证凭据。你可以将它们添加到 GitHub 仓库 Secrets 中，或者更推荐的做法是，创建一个专用的 GitHub Environment。

例如，在 Settings → Environments 中创建一个名为 geo-tests 的 Environment，并添加工作流所引用的 Secrets。

可以采用以下命名方式：

KP_PROXY_USERNAME_US
KP_PROXY_PASSWORD_US
KP_PROXY_USERNAME_UK
KP_PROXY_PASSWORD_UK
KP_PROXY_USERNAME_DE
KP_PROXY_PASSWORD_DE

再将共享代理网关添加为 Environment Variable：

KP_PROXY_SERVER

请使用代理服务商提供的准确网关主机名、端口、协议和国家定向凭据。不同代理服务商的用户名格式和国家选择语法不一定相同。

需要住宅代理进行多地区测试吗？

要测试网站在不同地区的表现，你需要具备可靠国家定向能力的住宅代理连接。

KindProxy 住宅代理提供支持国家定向的 HTTP/HTTPS 住宅端点，因此你可以从不同网络位置运行 Playwright、Selenium 等浏览器自动化。在控制台配置网关、用户名和密码后，将这些值写入本地 .env 文件或 GitHub Secrets。

了解 KindProxy 住宅代理

如果仓库当前的 .env.example 或测试脚本使用了不同的环境变量名称，请确保测试脚本、本地配置和工作流中的名称保持一致。不要只修改其中一处。

不要将真实代理凭据写入工作流 YAML、源代码、README、截图或测试输出中。 本地 .env 文件应排除在 Git 版本控制之外，请确认 .gitignore 已正确忽略该文件。

GitHub 官方文档：

• 在 GitHub Actions 中使用 Secrets
• 使用 Environments 进行部署

5. 添加 GitHub Actions 工作流

在仓库中创建以下工作流文件：

.github/workflows/geo-playwright.yml

下面的工作流示例展示了 Matrix 结构以及不同地区的 Secret 映射方式。在使用之前，请将 env 部分中的环境变量名称与 tests/test_geolizr_geoip.py 实际读取的变量，以及仓库 .env.example 中记录的名称保持一致。 工作流传入的配置必须与测试脚本实际读取的配置一致，不要引入第二套配置接口。

name: Multi-region Geolizr Playwright tests

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  geolizr-geo-test:
    name: Geolizr GeoIP test (${{ matrix.region }})
    runs-on: ubuntu-latest
    environment: geo-tests
    timeout-minutes: 15

    strategy:
      fail-fast: false
      max-parallel: 3
      matrix:
        include:
          - region: US
            username_secret: KP_PROXY_USERNAME_US
            password_secret: KP_PROXY_PASSWORD_US
          - region: UK
            username_secret: KP_PROXY_USERNAME_UK
            password_secret: KP_PROXY_PASSWORD_UK
          - region: DE
            username_secret: KP_PROXY_USERNAME_DE
            password_secret: KP_PROXY_PASSWORD_DE

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: pip

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          python -m playwright install --with-deps chromium

      - name: Run Geolizr test
        env:
          TEST_REGION: ${{ matrix.region }}
          PROXY_SERVER: ${{ vars.KP_PROXY_SERVER }}
          PROXY_USERNAME: ${{ secrets[matrix.username_secret] }}
          PROXY_PASSWORD: ${{ secrets[matrix.password_secret] }}
        run: |
          pytest -v tests/test_geolizr_geoip.py \
            --junitxml="test-results-${TEST_REGION}.xml"

      - name: Upload test result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: geolizr-result-${{ matrix.region }}
          path: test-results-${{ matrix.region }}.xml
          if-no-files-found: ignore

重要：确保工作流与实际测试脚本匹配

上面的 Matrix 示例展示了如何选择不同地区的代理凭据。它假设测试脚本能够接收地区配置，并从环境变量中读取代理服务器、用户名和密码。

提交工作流之前，请检查实际的 test_geolizr_geoip.py：

• 如果脚本已经读取地区变量，就使用脚本中实际存在的变量名称传入 Matrix 的值。
• 如果脚本要求分别传入各地区的环境变量，就在工作流中映射这些实际变量。
• 如果脚本通过 Pytest 参数或命令行选项选择地区，就使用现有的参数接口。
• 除非 Python 脚本确实读取了 TEST_REGION、PROXY_SERVER 等变量，否则不要擅自在工作流中添加这些变量。

工作流和测试脚本必须遵循同一套配置约定。仓库中的测试文件才是配置接口的最终依据。

fail-fast: false 表示某个地区失败时，其他地区的 Job 仍然可以继续完成。max-parallel: 3 允许三个地区的任务并行运行。timeout-minutes 则可以防止测试卡住后长期占用 Runner。

6. 启用 CI 前先在本地运行测试

在依赖 GitHub Actions 之前，先确认现有测试脚本能够在本地正常运行。

按照仓库 .env.example 和 README 中的变量名称及配置格式完成设置，然后执行：

pytest -v tests/test_geolizr_geoip.py

如果你希望一次只测试一个地区，请使用测试脚本已经实现的地区选择机制。不要假设某个环境变量或命令行选项存在，除非代码中确实实现了它。

先在本地成功运行，可以帮助你区分测试代码或代理配置问题，以及 GitHub Actions 工作流配置问题。

7. 在 GitHub Actions 中查看结果

打开 GitHub 仓库的 Actions 标签页，选择对应的工作流运行记录。

使用三个地区的 Matrix 后，应该能看到三个独立 Job：

• Geolizr GeoIP test (US)
• Geolizr GeoIP test (UK)
• Geolizr GeoIP test (DE)

打开每个 Job 即可查看 Pytest 输出。只要测试生成了结果文件，工作流还会为每个地区上传一个 JUnit XML Artifact。

下面三张终端风格的结果图展示了 Geolizr 测试中观察到的地区结果。它们是测试输出摘要图，并非 GitHub Actions 界面的截图。

美国（US）

英国（UK）

德国（DE）

Pytest 测试用例通过，表示脚本中定义的断言已经成功执行。这并不意味着页面上所有货币信号都完全一致，也不代表已经验证最终结账金额。请结合具体检测结果进行判断，不要仅凭测试状态就认定所有货币信号都一致。

从不同国家测试你的网站

这些结果说明了为什么要从多个网络位置进行测试。网站可能会根据请求所使用的住宅 IP 位置，对访客做出不同识别。

如果你需要住宅 IP 来进行自己的 GeoIP 检测、本地化 QA 或地区性浏览器工作流，KindProxy 可提供覆盖多个国家的住宅代理访问。你可以使用自己的凭据，复用同一套 KindProxy GeoIP Benchmark 测试模式。

开始使用 KindProxy

8. 常见 GitHub Actions 问题

断言失败并不一定意味着代理存在故障。GeoIP 数据库可能存在差异，网站也可能调整本地化逻辑，Demo Store 本身也可能更新页面实现。

9. 保护凭据并避免不必要的流量

运行带代理认证的浏览器测试时，建议遵循以下做法：

• 将凭据保存在 GitHub Secrets 或受保护的 Environment 中。
• 不要向不受信任的 Pull Request 代码暴露代理凭据。
• 只在可信分支或经过人工批准的工作流中运行带认证信息的测试。
• 每个地区的测试使用独立的浏览器 Context。
• 合理控制并行 Job 数量和请求频率。
• 只测试自己拥有或获得授权的网站。
• 避免在 CI 日志中输出完整代理凭据、Authorization 请求头、Cookie 或其他敏感信息。

示例工作流使用推送到 main 分支和手动触发两种方式，不会在 pull_request 事件中运行带凭据的测试，因为不受信任的代码可能尝试窃取 Job 可访问的 Secrets。

常见问题

GitHub Actions 可以通过住宅代理运行 Playwright 测试吗？

可以。GitHub Actions Job 可以通过环境变量或 GitHub Secrets 将代理网关和认证凭据传递给 Playwright。前提是工作流和 Python 测试脚本使用完全一致的环境变量名称。

可以并行测试多个国家吗？

可以。GitHub Actions Matrix 可以分别为美国、英国和德国创建独立 Job。每个 Job 使用对应国家的代理凭据，同时运行同一份测试脚本。

修改 Playwright 的 locale 会改变代理出口国家吗？

不会。代理决定网络路由和公网出口 IP。Playwright 的 locale 和 timezone 用于配置浏览器偏好，并不会改变网络出口位置。

如果检测到的国家不正确，应该检查什么？

首先检查代理网关、认证凭据和国家定向设置，然后验证实际公网出口 IP，并对比其他 GeoIP 查询来源。不同 GeoIP 数据库可能会返回不同结果。

如何保护 GitHub Actions 中的代理凭据？

将凭据保存在 GitHub Secrets 或受保护的 GitHub Environment 中。不要向不受信任的 Pull Request 代码暴露凭据，不要将凭据直接写入工作流 YAML，也不要在 CI 日志中输出凭据。

总结

通过 GitHub Actions Matrix，可以使用不同地区的代理配置运行同一份 Playwright 测试。在这个项目中，每个 Matrix Job 都会使用不同地区的住宅代理，运行现有的 tests/test_geolizr_geoip.py，并访问 Geolizr Shopify Demo Store。

这样项目结构就很清晰：一份测试脚本、一个目标网站，以及分别运行美国、英国和德国测试的 CI Job。 为了增加 GitHub Actions 自动化能力，没有必要再复制一份通用地区测试代码。

你可以在 KindProxy GeoIP Benchmark GitHub 仓库 中查看测试代码和项目配置。

如果你想了解这套测试在网站上观察到了什么，可以继续阅读配套实测报告：住宅代理会改变电商网站的价格和货币吗？Playwright GeoIP 实测 。

自行运行多地区代理测试

准备好从不同国家测试你的网站了吗？

请用本指南配置 GitHub Actions 工作流，克隆 KindProxy GeoIP Benchmark 项目获取 Playwright 测试脚本，并在需要国家定向住宅 IP 时使用 KindProxy 住宅代理运行你自己的测试。

了解住宅代理套餐

延伸阅读

• 如何在 Playwright 中使用住宅代理
• Playwright 代理认证：常见连接错误及解决方法
• 住宅代理会改变电商网站的价格和货币吗？Playwright GeoIP 实测
• KindProxy GeoIP Benchmark GitHub 仓库
• Playwright Python 官方文档
• GitHub Actions 工作流语法