本文介绍在 ci 环境（如 azure pipelines）中避免端口冲突的可靠方案：通过 playwright 配置动态选取可用端口，无需修改 webpack 或其他构建工具配置，兼顾本地调试与流水线稳定性。
本文介绍在 ci 环境（如 azure pipelines）中避免端口冲突的可靠方案：通过 playwright 配置动态选取可用端口，无需修改 webpack 或其他构建工具配置，兼顾本地调试与流水线稳定性。
在使用 Playwright 启动前端开发服务器（如 npm run start）进行端到端测试时，硬编码端口（如 port: 3000）极易导致 CI 环境下端口占用冲突——尤其在共享 Azure Agent 的多流水线并发执行场景中。手动轮换端口（如 3001、3002）治标不治本，而修改 Webpack 或 Vite 配置又违背“测试配置应独立于构建配置”的工程原则。
Playwright 官方 webServer.port 选项不支持动态端口探测或自动分配（截至 v1.45），但可通过巧妙利用 Node.js 运行时和环境变量，在 playwright.config.ts 初始化阶段提前确定并注入端口，实现“零配置侵入”的动态适配。
✅ 推荐实践：环境感知的端口预分配
核心思路是：不在 webServer 配置中直接写死 port，而是通过 process.env.PORT 提前设置，并让开发服务器（如 webpack-dev-server、Vite、Next.js dev）自动读取该环境变量生效。绝大多数现代前端开发服务器均原生支持 PORT 环境变量覆盖配置。
以下是在 playwright.config.ts 中的安全、可复用实现：
// playwright.config.ts
import { defineConfig } from '@playwright/test';
// 动态分配端口：CI 环境随机选取，本地固定便于调试
if (!process.env.BASE_URL) {
const getAvailablePort = (): number => {
// 仅在 CI 中启用随机端口（避免本地频繁变更影响开发者体验）
if (process.env.CI === 'true') {
const portRange = { min: 10000, max: 30000 };
return Math.floor(Math.random() * (portRange.max - portRange.min) + portRange.min);
}
return 8088; // 本地默认端口，稳定且避开常用服务（如 3000/8080）
};
const port = getAvailablePort();
process.env.PORT = String(port);
process.env.BASE_URL = `http://localhost:${port}`;
}
export default defineConfig({
webServer: {
command: 'npm run start', // 确保你的 start 脚本启动的 dev server 支持 PORT 环境变量
timeout: 120_000,
reuseExistingServer: !process.env.CI, // 本地复用已启动服务，CI 强制新建
},
use: {
baseURL: process.env.BASE_URL,
},
});✅ 关键前提验证：请确认你的 npm run start 所调用的开发服务器支持 PORT 环境变量。
- ✅ Webpack Dev Server：原生支持（无需额外配置）；
- ✅ Vite：原生支持（vite dev --port $PORT 会自动生效）；
- ✅ Next.js：需在 next.config.js 中显式读取：const port = process.env.PORT ? parseInt(process.env.PORT) : 3000；
- ❌ 若不支持，请升级工具链或改用 cross-env PORT=xxx npm run start 包装命令。
⚠️ 注意事项与最佳实践
- 避免端口范围过窄：推荐 10000–30000，避开系统保留端口（
- CI 中禁用 reuseExistingServer：防止多个 Pipeline 复用同一进程引发状态污染；
- 本地开发友好性：固定端口（如 8088）确保浏览器可直接访问、DevTools 可用、HMR 正常工作；
-
端口冲突兜底？ 当前方案基于随机数，极小概率重复；若需强保障，可集成 get-port 库进行真实端口探测（需额外依赖）：
npm install get-port --save-dev
import getPort from 'get-port'; // … 在 getAvailablePort() 中替换为： return await getPort({ port: getPort.makeRange(10000, 30000) });
此方案已在多个 Azure Pipelines 项目中稳定运行，彻底消除因端口争用导致的 EADDRINUSE 测试失败，同时保持本地开发体验无缝一致。真正的端到端测试稳定性，始于基础设施无关的配置设计。
