Playwright安装教程：Node环境准备与项目初始化

本节目标：在自己机器上装好 Node 和 Playwright，看懂脚手架生成的每个文件，并知道 CLI 有哪些常用命令。

先确认 Node 版本

Playwright 跑在 Node.js 上，版本不对会直接装不上或者跑不起来。

Playwright 1.62.x 要求 Node.js 为 22.x、24.x 或 26.x 的最新补丁版。这个清单随 Playwright 版本升级，换版本时回查官方文档的系统要求那一节。

先看看你机器上是什么：

node -v
npm -v

如果输出的是 v18.x 之类的老版本，先升级再往下走。

Warning

别用奇数号的开发版 Node（比如 23.x、25.x）。这些是非 LTS（长期支持）版本，工具链兼容性没保障，出了问题很难查。

顺手确认操作系统

官方支持的系统清单：

Windows 11 及以上、Windows Server 2019 及以上，或 WSL（Windows Subsystem for Linux）
macOS 14 (Sonoma) 及以上
Debian 12 / 13，Ubuntu 22.04 / 24.04 / 26.04（x86-64 或 arm64）

不在清单里的系统不是一定跑不了，但出问题官方不兜底，CI 上尤其别冒险。

一条命令初始化项目

Playwright 提供了脚手架命令，新项目、老项目都能用。它会判断当前目录状态：空目录就初始化一个新项目，已有项目就把 Playwright 加进去。

按你用的包管理器选一条：

# npm
npm init playwright@latest

# yarn
yarn create playwright

# pnpm
pnpm create playwright

命令跑起来后会问你几个问题，逐个说明：

用 TypeScript 还是 JavaScript？默认 TypeScript，建议直接回车。Playwright 自带类型定义，编辑器补全和报错提示会舒服很多。
测试文件放哪个目录？默认 tests。如果目录已存在，它会建议 e2e。
要不要加 GitHub Actions 工作流？打算上 CI 就选是，它会生成一份可用的配置。
要不要现在下载浏览器？默认是。第一次会下几百 MB，网络慢的话耐心等一下。

Tip

这条命令可以重复跑。它不会覆盖你已经写好的测试文件，所以配置选错了重来一次就行。

装完之后有什么

脚手架会生成这样一套东西：

playwright.config.ts      # 测试配置文件
package.json
package-lock.json         # 或 yarn.lock / pnpm-lock.yaml
tests/
  example.spec.ts         # 一个最小示例测试

逐个说：

playwright.config.ts 是整个项目的控制中心。跑哪些浏览器、超时多久、重试几次、用什么报告器，全在这里。第 6 章会逐字段拆解。
tests/example.spec.ts 是一个能直接跑的示例，打开 playwright.dev 检查标题和链接。
如果你是往已有项目里加，依赖会写进现有的 package.json，不会新建。

打开 package.json 看一眼，应该多了这么一行：

{
  "devDependencies": {
    "@playwright/test": "^1.62.1"
  }
}

注意包名是 @playwright/test，不是 playwright。

这两个包不一样：

@playwright/test：完整测试框架，含测试运行器、断言、Fixture（夹具）
playwright：只有浏览器操控库，没有测试运行器

写测试就用前者。后者的适用场景（库模式）我们后面单独讲。

跑通第一条命令

进项目目录，执行：

npx playwright test

默认行为是：无头模式、并行、在 Chromium / Firefox / WebKit 三个浏览器上各跑一遍。终端会打印每条用例的结果和汇总。

几个立刻能用上的参数：

# 看得见浏览器窗口
npx playwright test --headed

# 只跑某一个浏览器
npx playwright test --project=chromium

# 只跑某个文件
npx playwright test tests/example.spec.ts

# 打开交互式界面
npx playwright test --ui

如果有用例失败，Playwright 会自动打开 HTML 报告。全部通过时不会自动开，想看就手动执行：

npx playwright show-report

报告里能按浏览器、通过、失败、跳过、不稳定（flaky）来筛选，点进单条用例还能看错误、附件和每一步。

CLI 常用命令速查

npx playwright 后面能跟不少子命令。挑常用的过一遍，混个脸熟就行，后面章节会分别展开。

命令	干什么
`playwright test`	跑测试
`playwright show-report`	打开上一次的 HTML 报告
`playwright install`	下载浏览器
`playwright install-deps`	安装浏览器所需的系统依赖（主要用于 Linux/CI）
`playwright codegen`	录制操作、自动生成测试代码
`playwright show-trace`	打开 Trace（追踪）文件排查失败
`playwright merge-reports`	合并分片跑出来的多份报告
`playwright clear-cache`	清掉 Playwright 的各种缓存
`playwright --version`	看当前版本

任何一条后面加 --help 都能看到完整参数：

npx playwright test --help
npx playwright install --help

Note

用 yarn 的把 npx playwright 换成 yarn playwright，用 pnpm 的换成 pnpm exec playwright。后面章节统一写 npx，你自己对应替换。

升级 Playwright

Playwright 是月度发布，跟着升有两个好处：拿到新特性，也拿到新版浏览器引擎。

升级要两步，很多人只做第一步然后一头雾水：

# 1. 升级包
npm install -D @playwright/test@latest

# 2. 下载新版本对应的浏览器和依赖
npx playwright install --with-deps

为什么必须做第二步？因为每个 Playwright 版本绑定了特定版本的浏览器二进制包。包升了、浏览器没升，两边对不上就会报错。

升完确认一下：

npx playwright --version

Warning

升级 Playwright 相当于同时换了浏览器版本。新浏览器可能暴露出你页面里原本就存在的兼容问题。所以升级最好单独提一个 commit，别混在功能改动里，方便出问题时定位。

常见踩坑

装的时候卡在下载浏览器。 国内网络访问微软 CDN 可能慢。可以设代理环境变量 HTTPS_PROXY，或者调大超时 PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT。详细做法在第 3 章。

装错包了。 装成 playwright 之后写 import { test } from '@playwright/test' 会找不到模块。装 @playwright/test 就对了。

跑测试提示找不到配置文件。 npx playwright test 默认在当前目录找 playwright.config.ts。确认你 cd 到了项目根目录，或者用 -c 指定路径。

小结

装 Playwright 本身只有一条命令，真正要留意的是三件事：Node 版本对不对、装的是不是 @playwright/test、升级时有没有同步升浏览器。

下一章专门讲浏览器和系统依赖 —— 这块在 CI 上最容易翻车。

环境准备：安装 Node 与 Playwright

先确认 Node 版本

顺手确认操作系统

一条命令初始化项目

装完之后有什么

跑通第一条命令

CLI 常用命令速查

升级 Playwright

常见踩坑

小结