企业官网建设流程全解析

1. 从零搭建 Node.js Playwright 自动化测试环境到底难在哪

很多刚接触自动化测试的朋友，第一次听到 Node.js + Playwright 这套组合，第一反应是“听起来很专业，是不是要配一堆环境变量”。其实它比想象中友好得多。Playwright 是微软开源的一个浏览器自动化库，能同时驱动 Chromium、Firefox、WebKit 三大内核，写一套用例就能跨浏览器跑。它适合谁？适合想给 Web 项目加端到端测试的前端、想学自动化测试的在校生、以及需要做页面巡检的运维同学。

我见过最多的卡点不是 API 难写，而是环境没搭顺：npm create playwright跑完不知道文件在哪、npm run test报Missing script: "test"、VS Code 里断点打不上、浏览器没装导致启动就崩。这些问题本质都是项目初始化和配置没对齐。这篇就按“能跟做”的标准，把 Node.js Playwright 自动化测试环境从空文件夹一路搭到首个用例跑绿，中间每个配置文件都给完整可复制版本，报错也逐条对照。

你需要的准备只有两样：装好 Node.js（建议 18 LTS 以上）和 VS Code。先在终端确认版本：

node -v npm -v

两条命令都能打印版本号就说明基础环境 OK。如果node提示不是内部命令，去 Node.js 官网下 LTS 安装包重装一次，安装时勾选“Add to PATH”。这一步别跳过，后面所有命令都依赖它。

接着建项目目录。我习惯把测试项目和业务代码分开，避免依赖互相污染：

mkdir my-playwright-project cd my-playwright-project

到这里空目录就准备好了。下一节开始真正初始化，我会把交互式命令的每个选项都解释清楚，避免你一路回车选错语言或漏装浏览器。

2. 用 npm create playwright 初始化项目与依赖安装

在空目录里执行官方脚手架命令：

npm create playwright@latest

它会依次问你几个问题。第一个是语言选择，会看到TypeScript和JavaScript两个选项。零基础建议先选 JavaScript，语法负担小，等熟悉了再迁 TS。第二个问测试目录，默认tests就行。第三个问是否加 GitHub Actions，个人练习选 false。第四个问是否安装 Playwright 浏览器，这里强烈建议选 true，否则后面跑用例会提示找不到浏览器可执行文件。

命令跑完后，目录里会多出这些关键文件：package.json、playwright.config.js、tests/文件夹，以及node_modules。先打开package.json确认 scripts 字段：

{ "name": "my-playwright-project", "version": "1.0.0", "scripts": { "test": "playwright test", "test:headed": "playwright test --headed", "report": "playwright show-report" }, "devDependencies": { "@playwright/test": "^1.44.0" } }

如果你初始化时漏了浏览器，或者想补装，单独执行：

npx playwright install

只想装 Chromium 可以加参数npx playwright install chromium，省下载时间。依赖装完后，node_modules/.bin里会有playwright可执行文件，npm run test才能找到它。

这里插一句，如果你后续想让测试脚本调用大模型做断言辅助或生成用例，可以提前把模型服务的 Key 准备好。我平时会把这类 Key 统一放在 TaoToken 的 API Keys 页面管理，地址是 https://taotoken.net/api-keys ，申请后在代码里通过环境变量读取，不硬编码进仓库。这一步现在不做也不影响跑通 Playwright，属于可选增强。

3. 可复制的 playwright.config 与 VS Code 调试配置

配置文件是整套环境的核心。把项目根目录的playwright.config.js替换成下面这版，参数我都加了注释：

// playwright.config.js const { defineConfig, devices } = require('@playwright/test'); module.exports = defineConfig({ testDir: './tests', timeout: 30 * 1000, fullyParallel: true, retries: 1, reporter: [['html', { open: 'never' }], ['list']], use: { baseURL: 'https://playwright.dev', headless: true, viewport: { width: 1280, height: 720 }, screenshot: 'only-on-failure', trace: 'on-first-retry', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, { name: 'firefox', use: { ...devices['Desktop Firefox'] } }, { name: 'webkit', use: { ...devices['Desktop Safari'] } }, ], });

几个参数值得说：retries: 1让失败用例自动重试一次，减少网络抖动误报；trace: 'on-first-retry'会在重试时录屏，排查问题特别有用；baseURL设好后，用例里page.goto('/')就能自动拼完整地址。

接下来配 VS Code 调试。在项目根目录建.vscode/launch.json：

{ "version": "0.2.0", "configurations": [ { "name": "Debug Playwright Tests", "type": "node", "request": "launch", "program": "${workspaceFolder}/node_modules/@playwright/test/cli.js", "args": ["test", "--headed", "${file}"], "console": "integratedTerminal", "internalConsoleOptions": "neverOpen" } ] }

这样在某个.spec.js文件里按 F5，就会以有头模式只跑当前文件，断点能正常命中。注意args里的${file}表示当前打开的文件，想跑全部用例就把它去掉。

如果你用 TypeScript，把playwright.config.js换成.ts并把require改成import即可，其余结构一致。配置写完后建议先npx playwright test --list验证配置能被解析，能列出用例名就说明语法没问题。

4. 首个测试用例与 npm test 验证成功结果

在tests/下新建example.spec.js：

// tests/example.spec.js const { test, expect } = require('@playwright/test'); test('首页标题包含 Playwright 关键词', async ({ page }) => { await page.goto('/'); await expect(page).toHaveTitle(/Playwright/); }); test('导航到 Docs 页面', async ({ page }) => { await page.goto('/'); await page.getByRole('link', { name: 'Docs' }).click(); await expect(page).toHaveURL(/docs/); });

第一个用例验证标题，第二个模拟点击导航。getByRole是 Playwright 推荐的定位方式，比 CSS 选择器更稳。

现在跑起来：

npm run test

正常输出会类似：

Running 6 tests using 3 workers 6 passed (8.2s) To open last HTML report run: npx playwright show-report

6 个是因为 2 个用例 × 3 个浏览器项目。想只看 Chromium：

npx playwright test --project=chromium

想看浏览器实际动作，加--headed：

npx playwright test --headed

跑完执行npm run report打开 HTML 报告，能看到每个用例耗时、截图和 trace。到这一步，Node.js Playwright 自动化测试环境就算真正跑通了。如果你还想在用例里接入模型能力做智能断言，可以在环境变量里配置 TaoToken 的 API 地址 https://taotoken.net/api 和对应 Key，再在测试辅助函数里调用，这部分按需扩展即可。

5. 常见报错排查：Missing script、浏览器未安装与超时

报错一：npm error Missing script: "test"

这是最高频的。原因就是package.json的scripts里没有test字段。打开文件补上：

"scripts": { "test": "playwright test" }

保存后重跑。如果补了还报，检查是不是在错误的目录执行——必须在含package.json的根目录跑npm run test。

报错二：browserType.launch: Executable doesn't exist

说明浏览器没装。执行：

npx playwright install

如果下载慢或中断，重试一次通常能续上。装完再跑。

报错三：Error: page.goto: net::ERR_CONNECTION_TIMED_OUT

多半是baseURL指向的站点访问不通，或公司网络有限制。先确认playwright.config.js里baseURL写对，再在浏览器手动打开该地址验证连通性。

报错四：Test timeout of 30000ms exceeded

用例 30 秒没跑完。常见于页面加载慢或元素定位不到。临时调大timeout，但更推荐检查定位器是否写错。用--headed跑一遍看卡在哪一步。

报错五：VS Code 断点不生效

检查launch.json里program路径是否指向node_modules/@playwright/test/cli.js，以及是否用了--headed。无头模式下断点体验差，调试时务必加这个参数。

报错六：Cannot find module '@playwright/test'

依赖没装全。删掉node_modules和package-lock.json后重装：

npm install npx playwright install

排查时记住一个顺序：先看报错关键词，再确认目录和配置文件，最后才怀疑依赖。大部分问题都出在前两步。

6. 把环境用起来：下一步可以做什么

环境跑通只是起点。接下来你可以把baseURL换成自己项目的地址，把用例从示例站迁到真实页面；可以用page.route拦截接口做 mock，让测试不依赖后端；也可以把npm run test挂到 CI 里，每次提交自动跑。

如果你想让测试脚本具备模型辅助能力，比如自动生成断言或分析失败原因，可以在项目里通过环境变量注入 Key，模型对话入口在 https://taotoken.net/models ，接入文档在 https://taotoken.net/doc ，按文档把 Base URL 和 Model ID 填进你的辅助脚本即可。长期做编码和 Agent 类任务的话，Coding Plan 页面 https://taotoken.net/coding-plan 有更细的套餐说明。

最后留个实用习惯：每次改完配置先跑npx playwright test --list，能列出用例说明配置没坏；再跑单文件npx playwright test tests/example.spec.js，最后才跑全量。这样定位问题最快，也不容易把环境改乱。