本教程共 59 篇 · 第 35 篇 · 更新于 2026-08-04 · 约 10 分钟阅读

35. Web 服务启动 webServer 配置

本节目标：学完能在配置里声明一个本地服务器，让 Playwright 在跑测试前自动启动它，跑完自动收尾。

测试总要有一个被访问的网址。你总不能每次手动开终端、敲命令、等服务器起来再跑测试。Playwright 的 webServer 配置就是干这个的：一键托管。

它能帮你做什么

webServer 是写在配置文件里的一项。测试启动前，它会执行你给的命令拉起服务器；服务器就绪后，测试才开始。整个过程全自动。

Note

webServer（Web 服务器）支持同时启动多个服务，比如前端一个、后端一个，适合需要联调的场景。

最小可用配置

最常见的写法，启动命令加监听地址：

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  webServer: {
    command: 'npm run start',          // 启动你本地服务器的命令
    url: 'http://localhost:3000',       // 就绪后返回 2xx/3xx 的地址
    reuseExistingServer: !process.env.CI,  // 本地复用已有服务器
    stdout: 'ignore',
    stderr: 'pipe',
  },
});

reuseExistingServer 这个细节很贴心：本地如果已经开着服务器，就直接用，不重复起；到了 CI 环境（process.env.CI 为真）则强制新起一个，避免误用别处残留的进程。

各字段是干嘛的

配置项不少，挑常用的说：

command：启动服务器的 shell 命令。
url：服务器就绪的判定地址，Playwright 会轮询它直到返回正常状态码。
timeout：最多等多久，默认 60 秒，超时就报错。
reuseExistingServer：是否复用已经运行的服务器。
stdout / stderr：是否把服务器的输出打印出来，调试时设成 'pipe' 更方便。
gracefulShutdown：怎么关掉进程，默认强制结束，可设成发 SIGTERM 再兜底。

服务器起得慢？加超时

有的框架冷启动要一分多钟。把 timeout 调大即可：

webServer: {
  command: 'npm run start',
  url: 'http://localhost:3000',
  reuseExistingServer: !process.env.CI,
  timeout: 120 * 1000,   // 等两分钟
},

配上 baseURL 省得写全地址

再配合 use.baseURL，测试里就能用相对路径，清爽很多：

export default defineConfig({
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
  use: {
    baseURL: 'http://localhost:3000',
  },
});

test('登录页能打开', async ({ page }) => {
  // 不用写全 http://localhost:3000/login
  await page.goto('./login');
});

Tip

设了 baseURL 后，page.goto、page.route 等的相对路径都会自动拼上它，少写一堆重复前缀。

同时起多个服务

前后端分离的项目，两个都要起，给成数组就行，各自起名便于看日志：

webServer: [
  {
    command: 'npm run start',
    url: 'http://localhost:3000',
    name: 'Frontend',
    timeout: 120 * 1000,
    reuseExistingServer: !process.env.CI,
  },
  {
    command: 'npm run backend',
    url: 'http://localhost:3333',
    name: 'Backend',
    timeout: 120 * 1000,
    reuseExistingServer: !process.env.CI,
  },
],

本地调试更顺手

reuseExistingServer 这个开关让本地开发体验很舒服：你平时开着 npm run dev，跑测试时就直接用这个现成服务，不用再起一个；一旦真出问题怀疑是服务本身，把它临时改成 false 强制重起一个干净的，就能排除干扰。

Warning
如果本地没起服务，又设了 reuseExistingServer: true（本地默认），Playwright 会自己拉起一个。但如果端口被别的不相干的进程占了，测试就会连到错误的地方，报出一堆看不懂的断言失败。
怀疑端口冲突时先查一眼：
# macOS / Linux
lsof -i:3000

# Windows
netstat -ano | findstr :3000

什么时候用它

只要你的测试依赖一个本地或临时的服务器，webServer 就该上。

它最大的价值是让测试「自包含」——别人 clone 下代码，一条 npx playwright test 就能跑通，不用先去查文档该开哪个服务。

小结

webServer 写在配置里，测试开跑前自动拉起服务，跑完自动收尾。
command 是启动命令，url 是就绪判定地址，Playwright 会一直轮询直到它返回 2xx/3xx。
timeout 默认 60 秒，冷启动慢的框架记得调大。
reuseExistingServer: !process.env.CI：本地复用现成服务，CI 上强制起新的。
配上 use.baseURL，测试里就能写相对路径，page.goto、page.route 都会自动拼前缀。
前后端分离的项目，把 webServer 写成数组，各起一个 name 便于看日志。
端口被占是最常见的怪问题，先用 lsof 或 netstat 查一眼。

下一章我们把这套东西接进 CI，做到推代码就自动跑。