1. 项目概述：当自动化测试遇上网络“黑盒”

做UI自动化测试，尤其是用Playwright这种现代框架，最让人头疼的往往不是写脚本本身，而是脚本跑着跑着，突然就卡住了，然后一个刺眼的“Timeout”错误弹出来。这感觉就像你精心设计的机器人，出门执行任务时，不是被门夹住了，就是走错了路，而你只能对着日志干瞪眼。特别是当你的测试环境需要访问外部资源、调用第三方API，或者身处一个复杂的公司内网时，网络就成了那个最大的“黑盒”。

“Playwright测试超时？3种常见网络问题排查与代理配置指南”这个标题，精准地戳中了无数自动化测试工程师和开发者的痛点。它指向的不是语法错误，而是环境问题；不是逻辑缺陷，而是连通性谜题。超时只是一个表象，背后可能是DNS解析失败、可能是目标服务器响应缓慢、也可能是请求根本就没能走出你的本地网络。更复杂的是，在很多开发场景下，访问某些资源必须经过代理（Proxy），如果Playwright没有正确配置，那么所有需要经过代理的请求都会石沉大海，直接导致测试用例失败。

这篇文章，我就结合自己这些年踩过的坑，把Playwright测试中因网络问题导致的超时，掰开揉碎了讲清楚。我们会聚焦三种最常见的网络问题场景：DNS解析问题、资源加载缓慢或阻塞、以及代理配置缺失或错误。我会带你一步步学会如何像网络侦探一样，从超时错误这个“案发现场”出发，利用Playwright内置的工具和浏览器开发者工具，定位到真凶。更重要的是，我会给出针对每种问题的、可立即套用的解决方案，特别是代理配置，我会详细说明在无认证、有认证、以及复杂PAC代理等多种情况下，如何让Playwright“乖乖听话”。无论你是刚接触Playwright的新手，还是正在为团队搭建测试框架的老鸟，这些实战经验都能帮你节省大量排查时间，让自动化测试流程真正稳定可靠。

2. 核心网络问题场景深度拆解

Playwright测试超时，本质上是一个“预期行为未在指定时间内发生”的信号。对于网络操作，这个“预期行为”通常就是收到服务器的响应。下面我们深入看看导致这个信号触发的三大常见根源。

2.1 DNS解析失败：找不到门的钥匙

这是最基础，也最容易被忽略的一类问题。你的脚本里写的是page.goto('https://api.example.com')，Playwright的第一步不是直接发送HTTP请求，而是需要先问一下：“请问api.example.com这个门牌号（域名）对应的实际地址（IP）是什么？”这个过程就是DNS解析。

为什么这会成为问题？

1. 本地Hosts文件干扰：你的操作系统可能修改了hosts文件，将api.example.com指向了另一个IP（比如127.0.0.1或某个内网地址），而测试环境期望的是真实的公网IP。
2. DNS服务器不稳定：公司内网指定的DNS服务器，或者你本地网络配置的公共DNS（如8.8.8.8），可能出现暂时性故障或响应缓慢。
3. 域名本身有问题：你要访问的域名可能已过期、记录被误删，或者还在配置中未生效。

在Playwright中的表现：超时通常发生在page.goto()、page.waitForURL()或者任何发起新导航的指令初期。错误信息可能比较模糊，比如Timeout 30000ms exceeded，你需要进一步查看详细日志或网络跟踪才能确定卡在DNS阶段。

注意：有些情况下，DNS解析慢不会直接导致单次请求超时，但会显著拉长整个测试套件的执行时间，形成“慢性病”。

2.2 资源加载缓慢或阻塞：路上的交通拥堵

DNS解析成功后，请求踏上了前往服务器的“路”。这条路可能很拥堵。

主要瓶颈点：

1. 服务器响应慢（TTFB高）：Time To First Byte（首字节时间）过长。服务器应用本身处理请求慢，数据库查询复杂，或者服务器负载过高。
2. 网络链路质量差：尤其是访问海外站点，或者跨运营商访问，网络延迟（Ping值）高、丢包严重。
3. 资源体积过大：页面依赖的某个JavaScript文件、CSS或图片体积巨大，在慢速网络下下载耗时极长。
4. 第三方资源拖累：页面引入了来自Google Analytics、Facebook SDK等第三方域的脚本，这些资源的可用性不受你控制，一旦它们加载慢或失败，就可能阻塞你页面的load事件。

在Playwright中的表现：超时可能发生在page.goto()等待load事件时，也可能发生在page.waitForSelector()等待一个由慢速JS渲染的元素时。错误信息同样会是超时，但通过Playwright的page.on('request')和page.on('response')监听器，你可以看到具体是哪个请求“在路上”花了太长时间。

2.3 代理配置缺失或错误：没有通行证

这是企业内网开发测试中最经典的问题。很多公司为了安全和管理，要求所有对外部网络的访问必须通过统一的代理服务器。如果你的Playwright浏览器实例没有配置代理，那么所有试图访问公网的请求都会被系统网络层直接拒绝。

复杂情况在于代理的类型：

1. HTTP/HTTPS代理：最常见，需要配置代理服务器的地址和端口。
2. 认证代理：代理服务器需要用户名和密码认证。
3. SOCKS代理：另一种代理协议，Playwright也支持。
4. PAC代理（自动配置脚本）：浏览器需要从一个指定的URL地址下载并执行一个JavaScript文件（PAC），这个文件会告诉浏览器针对不同目标URL该使用哪个代理，或者直接连接。这是最棘手的一种，因为Playwright需要能访问到这个PAC URL地址，并解析其逻辑。

在Playwright中的表现：表现得很像DNS解析失败或完全的网络断开。对于需要代理才能访问的地址，page.goto()会一直挂起直到超时。而对于不需要代理的内网地址，访问可能完全正常。这种“内外有别”的现象是判断代理问题的重要线索。

3. 诊断工具箱：定位网络问题的具体方法

遇到超时，别急着改代码。先拿起“听诊器”和“显微镜”，给测试运行时的网络状况做个全面检查。

3.1 启用Playwright的详细日志与网络追踪

Playwright提供了强大的内置诊断功能。

方法一：启动浏览器时开启slowMo和headless: false这虽然不是直接的网络日志，但能让你直观地看到浏览器的操作过程。slowMo可以放慢每个操作步骤，方便你观察在哪一步卡住了。配合可视化模式，你能看到页面是否白屏、资源加载图标是否在转圈。

const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch({ headless: false, // 显示浏览器窗口 slowMo: 500, // 每一步操作放慢500毫秒 }); const page = await browser.newPage(); // ... 你的测试代码 })();

方法二：监听所有网络请求和响应这是最直接的网络诊断工具。通过监听request、response和requestfailed事件，你可以看到每个请求的生命周期。

page.on('request', request => console.log(`>> ${request.method()} ${request.url()}`)); page.on('response', response => console.log(`<< ${response.status()} ${response.url()}`)); page.on('requestfailed', request => console.log(`xx ${request.failure().errorText} ${request.url()}`));

运行测试，观察控制台输出。如果某个请求只有>>发出，没有对应的<<响应或xx失败，那它很可能就是导致超时的“元凶”。requestfailed事件会给出失败原因，如net::ERR_PROXY_CONNECTION_FAILED（代理连接失败）或net::ERR_TIMED_OUT（超时），这是关键线索。

方法三：使用Playwright Trace Viewer对于复杂的交互流程，开启Trace记录可以事后像看录像一样复盘。

await context.tracing.start({ screenshots: true, snapshots: true }); // ... 执行你的测试步骤 ... await context.tracing.stop({ path: 'trace.zip' });

使用playwright show-trace trace.zip命令打开可视化界面，在“Network”标签页下，你可以按时间线查看所有网络请求的详细时序、状态码和大小，精准定位是哪个请求耗时过长。

3.2 利用浏览器开发者工具进行现场分析

当浏览器以非无头模式启动时，你可以直接按F12打开开发者工具。

1. Network面板：这是主战场。确保勾选了“Preserve log”（保留日志），然后重现测试步骤。观察：
   • 请求队列：是否有大量请求处于“Pending”（挂起）状态？这可能是达到了浏览器对同一域名的并发连接数限制，或者代理服务器处理不过来。
   • Timing瀑布流：点击某个耗时长的请求，查看“Timing”标签。这里会清晰地将时间分解为：Queuing（排队）、Stalled（阻塞）、DNS Lookup（DNS查询）、Initial connection（初始连接，含TCP握手和TLS协商）、TTFB（首字节时间）、Content Download（内容下载）。哪个阶段长，问题就出在哪。
2. Console面板：查看是否有JavaScript网络错误，例如Failed to load resource: net::ERR_...。
3. Application面板 -> Storage -> Cookies：如果你测试的站点依赖特定Cookie，检查它们是否存在且未过期。有时因为Cookie问题导致的302重定向循环，也会表现为超时。

3.3 基础网络命令排查（外部验证）

在运行Playwright的机器上，使用命令行工具进行快速验证，这能帮你判断问题是出在Playwright层面，还是更底层的系统网络。

• ping：检查到目标域名的基本连通性和延迟。ping api.example.com。如果ping不通或延迟很高，那Playwright肯定也访问困难。注意：有些服务器禁用了ICMP协议，ping不通不代表HTTP不通。
• nslookup或dig：手动进行DNS解析。nslookup api.example.com。检查返回的IP地址是否符合你的预期。如果解析失败或返回127.0.0.1，那就是DNS问题。
• curl：这是最接近浏览器HTTP请求的工具。尝试curl -v https://api.example.com。
  • -v参数会输出详细过程，你可以看到DNS解析、TCP连接、TLS握手、发送请求、接收响应的全过程。
  • 如果curl能快速成功，但Playwright不行，那问题很可能出在Playwright的配置（如代理、浏览器上下文）上。
  • 如果curl也卡住或报错（如Could not resolve host或Connection timed out），那就是系统环境或网络本身的问题。

4. 针对性解决方案与代理配置实战

诊断出问题根源后，我们就可以“对症下药”了。

4.1 解决DNS解析问题

1. 修改Playwright的启动参数，使用特定DNS服务器： 如果你怀疑默认DNS服务器有问题，可以强制Playwright使用的浏览器使用更可靠的DNS，如Google的8.8.8.8或CloudFlare的1.1.1.1。

   const browser = await chromium.launch({ args: ['--dns-server=8.8.8.8'] });

2. 在测试环境中配置Hosts文件（谨慎使用）： 对于测试环境，有时我们想将某个域名固定指向测试服务器的IP。虽然可以在系统hosts文件修改，但更好的方法是在启动浏览器时通过--host-resolver-rules参数动态指定，这样不会影响系统其他应用。

   const browser = await chromium.launch({ args: ['--host-resolver-rules=MAP api.example.com 192.168.1.100'] });

   这条规则会将api.example.com映射到192.168.1.100。

3. 增加全局超时时间（治标不治本）： 如果DNS只是偶尔慢，作为临时缓解措施，可以适当增加Playwright的全局超时时间或特定操作的超时时间。但这掩盖了根本问题，不推荐作为长期方案。

   // 全局设置 const context = await browser.newContext({ timeout: 60000 // 将默认超时从30秒提高到60秒 }); // 或针对单个操作 await page.goto('https://api.example.com', { timeout: 60000 });

4.2 应对资源加载缓慢或阻塞

1. 优化等待策略，避开“慢资源”：page.goto()默认会等待load事件触发。如果页面因为一个无关紧要的第三方脚本（如广告）加载慢而迟迟不触发load，你可以改用domcontentloaded事件，它会在HTML文档被完全加载和解析后触发，不等待样式表、图片和子框架。

   await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

   然后，使用page.waitForSelector()来等待你真正关心的、由JavaScript渲染的关键元素出现，并为这个等待设置独立的超时。

2. 拦截并屏蔽非关键请求： 如果页面加载了大量测试无关的资源（如图片、字体、分析脚本），你可以通过路由（Route）功能拦截并中止这些请求，极大提升加载速度。

   await page.route('**/*.{png,jpg,jpeg,svg,gif,woff,woff2}', route => route.abort()); await page.route('https://www.google-analytics.com/**', route => route.abort()); await page.goto('https://example.com'); // 记得在需要时取消路由 // await page.unroute('**/*.{png,jpg,jpeg}');

3. 模拟网络条件，建立性能基线： 使用Playwright的setViewportSize和emulateNetworkConditions来模拟弱网环境（如3G），这不仅能测试页面在慢速网络下的表现，也能帮你发现哪些资源在弱网下会成为瓶颈。

   const context = await browser.newContext({ viewport: { width: 1280, height: 720 }, }); const page = await context.newPage(); // 获取慢3G的网络条件对象（Playwright内置） const slow3G = playwright.devices['Slow 3G']; await context.emulateNetworkConditions(slow3G);

4.3 代理配置的完整指南

这是重头戏。Playwright允许在不同层级配置代理：浏览器级别、浏览器上下文级别和页面级别。最常用的是在启动浏览器时配置。

场景一：配置简单的HTTP/HTTPS代理（无认证）

const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch({ proxy: { server: 'http://my-proxy-server:8080', // 代理服务器地址和端口 // 可选： bypass 规则，指定哪些地址不走代理 bypass: '*.internal.company.com, localhost, 127.0.0.1' } }); const page = await browser.newPage(); await page.goto('https://external-site.com'); // 此请求将通过代理 await page.goto('http://internal.company.com'); // 此请求将直连 })();

场景二：配置需要用户名密码认证的代理

const browser = await chromium.launch({ proxy: { server: 'http://my-proxy-server:8080', username: 'your-username', password: 'your-password' } });

重要安全提示：切勿将真实的代理密码硬编码在脚本中！应使用环境变量或安全的配置管理服务。

username: process.env.PROXY_USER, password: process.env.PROXY_PASS

场景三：处理复杂的PAC代理配置

PAC代理是最大的挑战，因为Playwright本身不直接执行PAC JavaScript。你需要根据当前运行环境，手动计算出针对目标URL应该使用的代理服务器，然后将这个结果配置给Playwright。通常有两种思路：

1. 离线解析PAC文件：如果你的PAC文件是固定的，可以手动或写个小脚本分析其逻辑，提炼出几条server和bypass规则，然后使用上述无认证代理的方式配置。

2. 动态获取系统代理设置（推荐）：在Node.js环境中，可以使用get-system-proxy这类第三方库来获取当前系统针对特定URL的代理设置。

   const { getProxyForUrl } = require('get-system-proxy'); const { chromium } = require('playwright'); (async () => { const targetUrl = 'https://external-site.com'; const proxyInfo = await getProxyForUrl(targetUrl); let launchOptions = {}; if (proxyInfo && proxyInfo !== 'DIRECT') { // proxyInfo 可能是 'http://proxy-server:port' launchOptions.proxy = { server: proxyInfo }; } const browser = await chromium.launch(launchOptions); const page = await browser.newPage(); await page.goto(targetUrl); await browser.close(); })();

   这种方法更通用，能让Playwright继承你系统浏览器（如Chrome）的代理设置。

场景四：为特定请求单独设置代理（精细化控制）

如果你需要在一个测试会话中访问多个需要不同代理的目标，可以在创建浏览器上下文（BrowserContext）时设置代理。每个上下文就像是一个独立的浏览器会话。

const browser = await chromium.launch(); // 上下文1：使用代理A访问外网 const context1 = await browser.newContext({ proxy: { server: 'http://proxy-a:8080' } }); const page1 = await context1.newPage(); await page1.goto('https://site-requiring-proxy-a.com'); // 上下文2：不使用代理访问内网 const context2 = await browser.newContext(); const page2 = await context2.newPage(); await page2.goto('http://internal-site.com'); await context1.close(); await context2.close(); await browser.close();

5. 进阶技巧与持续集成（CI）环境适配

将Playwright测试集成到CI/CD流水线中时，网络环境更加不可控，需要额外的策略来保证稳定性。

5.1 实现智能重试与熔断机制

对于偶发的网络波动，一个健壮的测试框架应该具备容错能力。

async function gotoWithRetry(page, url, maxRetries = 3, baseDelay = 1000) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { await page.goto(url, { timeout: 30000 }); return; // 成功则退出函数 } catch (error) { console.log(`尝试 ${attempt}/${maxRetries} 访问 ${url} 失败: ${error.message}`); if (attempt === maxRetries) { throw error; // 重试次数用尽，抛出错误 } // 指数退避延迟，避免重试雪崩 const delay = baseDelay * Math.pow(2, attempt - 1); console.log(`等待 ${delay}ms 后重试...`); await page.waitForTimeout(delay + Math.random() * 1000); // 加一点随机抖动 } } } // 使用示例 await gotoWithRetry(page, 'https://unstable-api.com');

对于关键的业务操作，也可以封装类似的clickWithRetry、waitForSelectorWithRetry函数。

5.2 CI环境下的代理与依赖管理

在Docker容器或GitHub Actions、GitLab CI等环境中，网络配置是全新的。

1. 在Dockerfile中配置全局代理：如果构建镜像时需要走代理下载依赖，可以在Dockerfile中设置环境变量。

   ENV HTTP_PROXY=http://host.docker.internal:8080 ENV HTTPS_PROXY=http://host.docker.internal:8080

   host.docker.internal是一个特殊的主机名，指向宿主机的本地网络。

2. 在CI脚本中动态配置Playwright代理：从CI平台的安全变量（Secrets）中读取代理配置。

   # GitHub Actions 示例 - name: Run Tests env: PROXY_SERVER: ${{ secrets.PROXY_SERVER }} PROXY_CREDENTIALS: ${{ secrets.PROXY_CREDENTIALS }} run: | if [ -n "$PROXY_SERVER" ]; then export PLAYWRIGHT_LAUNCH_OPTIONS='{"proxy": {"server": "$PROXY_SERVER"}}' fi npm test

   在你的测试启动脚本中，可以读取PLAYWRIGHT_LAUNCH_OPTIONS环境变量并解析为JSON对象，传入chromium.launch()。

3. 使用自托管的CI Runner：对于网络限制极其严格的公司，将CI Runner部署在可以直通所需网络资源的内网环境中，是最一劳永逸的方案。

5.3 构建网络健康检查与测试隔离

在测试套件开始前，增加一个简单的网络健康检查。

// network-check.js const { chromium } = require('playwright'); const { getProxyForUrl } = require('get-system-proxy'); async function checkNetworkAccess(url) { const browser = await chromium.launch(); const page = await browser.newPage(); try { const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 }); if (response.ok()) { console.log(`✓ 网络连通性正常 (${url})`); return true; } else { console.error(`✗ 访问 ${url} 返回状态码: ${response.status()}`); return false; } } catch (error) { console.error(`✗ 访问 ${url} 失败:`, error.message); // 可以尝试获取系统代理并打印，辅助调试 const proxy = await getProxyForUrl(url); console.log(`当前系统代理设置: ${proxy}`); return false; } finally { await browser.close(); } } // 在测试运行前调用 if (!await checkNetworkAccess('https://www.google.com')) { console.error('网络检查失败，测试中止。请检查代理或网络设置。'); process.exit(1); }

同时，确保每个测试用例是独立的。一个测试用例的网络失败（如下载一个大文件）不应该影响到下一个测试用例。使用test.afterEach或afterEach钩子来清理上下文、关闭页面，确保每次测试都从一个干净的网络状态开始。

6. 疑难杂症排查清单与经验总结

即使掌握了所有方法，有些问题依然诡异。这里记录一些我遇到过的“坑”和排查思路。

问题1：本地运行正常，CI上超时。

• 排查：首先在CI Runner上执行curl -v和nslookup，对比与本地环境的差异。99%的问题出在DNS或代理上。检查CI Runner是否运行在Docker容器内，容器网络模式（如host或bridge）会影响它对宿主机代理的访问。尝试在CI脚本中显式设置DNS服务器。

问题2：只有部分图片或字体加载超时。

• 排查：检查这些资源的域名是否不同。可能是CDN域名没有被正确纳入代理的bypass规则，或者该CDN域名本身可访问性差。使用开发者工具的Network面板，查看这些失败请求的详细错误信息。可以考虑在测试中路由（route）并模拟（fulfill）这些非关键资源，返回一个空的响应或本地模拟文件。

问题3：配置了代理，但依然报错net::ERR_PROXY_CONNECTION_FAILED。

• 排查步骤：
  1. 验证代理地址和端口：用telnet proxy-server 8080（或nc -zv proxy-server 8080）检查基本连通性。
  2. 验证认证信息：用户名密码是否包含特殊字符？是否需要URL编码？尝试用curl带代理认证测试：curl -x http://user:pass@proxy:port -v https://example.com。
  3. 检查代理协议：代理服务器是HTTP还是SOCKS？Playwright的server字段需要正确的前缀，如socks5://proxy-server:1080。
  4. 浏览器上下文覆盖：你是否在browser.newContext()或page级别又覆盖了代理设置？更具体的设置会覆盖上级设置。

问题4：超时时间设置得足够长，但请求依然在更短的时间内失败。

• 排查：注意Playwright中有多种超时设置，它们共同作用：
  • browser.newContext({ timeout: 60000 })：上下文级别的默认导航、加载超时。
  • page.setDefaultNavigationTimeout(60000)：页面级别的默认导航超时。
  • page.setDefaultTimeout(60000)：页面级别所有操作的默认超时（如click,fill）。
  • page.goto(url, { timeout: 60000 })：单次操作超时，优先级最高。 确认你修改的是正确的超时设置。另外，浏览器或操作系统本身也可能有TCP连接超时限制。

一个宝贵的习惯：记录完整的上下文信息当在CI中遇到网络超时失败时，让测试框架不仅输出错误日志，还尽可能多地记录上下文信息：

• 测试运行时的系统时间。
• 目标URL。
• 当前生效的代理配置（可以打印出来）。
• page.on('requestfailed')捕获到的所有失败请求的错误文本。
• 最近一次成功的网络请求日志（用于对比）。 这些信息对于事后在本地复现和诊断问题至关重要。网络问题排查，很多时候就是一场信息收集和对比的侦探游戏。耐心、系统地运用上述工具和方法，你就能把那个导致Playwright测试超时的“网络黑盒”，变成一个透明可控的组件。