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解析。为什么这会成为问题本地Hosts文件干扰你的操作系统可能修改了hosts文件将api.example.com指向了另一个IP比如127.0.0.1或某个内网地址而测试环境期望的是真实的公网IP。DNS服务器不稳定公司内网指定的DNS服务器或者你本地网络配置的公共DNS如8.8.8.8可能出现暂时性故障或响应缓慢。域名本身有问题你要访问的域名可能已过期、记录被误删或者还在配置中未生效。在Playwright中的表现超时通常发生在page.goto()、page.waitForURL()或者任何发起新导航的指令初期。错误信息可能比较模糊比如Timeout 30000ms exceeded你需要进一步查看详细日志或网络跟踪才能确定卡在DNS阶段。注意有些情况下DNS解析慢不会直接导致单次请求超时但会显著拉长整个测试套件的执行时间形成“慢性病”。2.2 资源加载缓慢或阻塞路上的交通拥堵DNS解析成功后请求踏上了前往服务器的“路”。这条路可能很拥堵。主要瓶颈点服务器响应慢TTFB高Time To First Byte首字节时间过长。服务器应用本身处理请求慢数据库查询复杂或者服务器负载过高。网络链路质量差尤其是访问海外站点或者跨运营商访问网络延迟Ping值高、丢包严重。资源体积过大页面依赖的某个JavaScript文件、CSS或图片体积巨大在慢速网络下下载耗时极长。第三方资源拖累页面引入了来自Google Analytics、Facebook SDK等第三方域的脚本这些资源的可用性不受你控制一旦它们加载慢或失败就可能阻塞你页面的load事件。在Playwright中的表现超时可能发生在page.goto()等待load事件时也可能发生在page.waitForSelector()等待一个由慢速JS渲染的元素时。错误信息同样会是超时但通过Playwright的page.on(request)和page.on(response)监听器你可以看到具体是哪个请求“在路上”花了太长时间。2.3 代理配置缺失或错误没有通行证这是企业内网开发测试中最经典的问题。很多公司为了安全和管理要求所有对外部网络的访问必须通过统一的代理服务器。如果你的Playwright浏览器实例没有配置代理那么所有试图访问公网的请求都会被系统网络层直接拒绝。复杂情况在于代理的类型HTTP/HTTPS代理最常见需要配置代理服务器的地址和端口。认证代理代理服务器需要用户名和密码认证。SOCKS代理另一种代理协议Playwright也支持。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打开开发者工具。Network面板这是主战场。确保勾选了“Preserve log”保留日志然后重现测试步骤。观察请求队列是否有大量请求处于“Pending”挂起状态这可能是达到了浏览器对同一域名的并发连接数限制或者代理服务器处理不过来。Timing瀑布流点击某个耗时长的请求查看“Timing”标签。这里会清晰地将时间分解为Queuing排队、Stalled阻塞、DNS LookupDNS查询、Initial connection初始连接含TCP握手和TLS协商、TTFB首字节时间、Content Download内容下载。哪个阶段长问题就出在哪。Console面板查看是否有JavaScript网络错误例如Failed to load resource: net::ERR_...。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解析问题修改Playwright的启动参数使用特定DNS服务器 如果你怀疑默认DNS服务器有问题可以强制Playwright使用的浏览器使用更可靠的DNS如Google的8.8.8.8或CloudFlare的1.1.1.1。const browser await chromium.launch({ args: [--dns-server8.8.8.8] });在测试环境中配置Hosts文件谨慎使用 对于测试环境有时我们想将某个域名固定指向测试服务器的IP。虽然可以在系统hosts文件修改但更好的方法是在启动浏览器时通过--host-resolver-rules参数动态指定这样不会影响系统其他应用。const browser await chromium.launch({ args: [--host-resolver-rulesMAP api.example.com 192.168.1.100] });这条规则会将api.example.com映射到192.168.1.100。增加全局超时时间治标不治本 如果DNS只是偶尔慢作为临时缓解措施可以适当增加Playwright的全局超时时间或特定操作的超时时间。但这掩盖了根本问题不推荐作为长期方案。// 全局设置 const context await browser.newContext({ timeout: 60000 // 将默认超时从30秒提高到60秒 }); // 或针对单个操作 await page.goto(https://api.example.com, { timeout: 60000 });4.2 应对资源加载缓慢或阻塞优化等待策略避开“慢资源”page.goto()默认会等待load事件触发。如果页面因为一个无关紧要的第三方脚本如广告加载慢而迟迟不触发load你可以改用domcontentloaded事件它会在HTML文档被完全加载和解析后触发不等待样式表、图片和子框架。await page.goto(https://example.com, { waitUntil: domcontentloaded });然后使用page.waitForSelector()来等待你真正关心的、由JavaScript渲染的关键元素出现并为这个等待设置独立的超时。拦截并屏蔽非关键请求 如果页面加载了大量测试无关的资源如图片、字体、分析脚本你可以通过路由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});模拟网络条件建立性能基线 使用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。通常有两种思路离线解析PAC文件如果你的PAC文件是固定的可以手动或写个小脚本分析其逻辑提炼出几条server和bypass规则然后使用上述无认证代理的方式配置。动态获取系统代理设置推荐在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等环境中网络配置是全新的。在Dockerfile中配置全局代理如果构建镜像时需要走代理下载依赖可以在Dockerfile中设置环境变量。ENV HTTP_PROXYhttp://host.docker.internal:8080 ENV HTTPS_PROXYhttp://host.docker.internal:8080host.docker.internal是一个特殊的主机名指向宿主机的本地网络。在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()。使用自托管的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。排查步骤验证代理地址和端口用telnet proxy-server 8080或nc -zv proxy-server 8080检查基本连通性。验证认证信息用户名密码是否包含特殊字符是否需要URL编码尝试用curl带代理认证测试curl -x http://user:passproxy:port -v https://example.com。检查代理协议代理服务器是HTTP还是SOCKSPlaywright的server字段需要正确的前缀如socks5://proxy-server:1080。浏览器上下文覆盖你是否在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测试超时的“网络黑盒”变成一个透明可控的组件。