自动化测试 / 系统课时
安装浏览器运行环境
安装浏览器运行环境
Playwright 的 npm 包安装成功,并不代表浏览器已经可以启动。本课解决浏览器可执行文件缺失、下载失败或系统依赖不完整的问题,完成浏览器安装,并通过实际启动 Chromium 验证运行环境是否可用。
学习目标
- 理解 Playwright 包、浏览器二进制文件和系统依赖之间的关系。
- 安装 Playwright 支持的浏览器,并根据需要选择单个浏览器。
- 验证浏览器能否启动,定位常见的安装与环境问题。
浏览器组件说明
Playwright 默认使用与当前 Playwright 版本匹配的浏览器构建,而不是直接调用系统已经安装的 Chrome 或 Firefox。安装 npm 依赖和下载浏览器是两个不同的步骤。
Playwright 主要支持三种浏览器引擎:
- Chromium:用于测试 Chromium 内核浏览器的行为。
- Firefox:用于检查 Firefox 浏览器的兼容性。
- WebKit:用于检查 WebKit 引擎相关的页面行为。
浏览器文件通常下载到用户级缓存目录,与项目中的 node_modules 分开存放。Playwright 负责查找匹配版本的浏览器,并在执行测试时启动浏览器进程。测试结束后应关闭浏览器,释放相关资源。

需要注意,浏览器二进制文件与操作系统依赖也不是一回事。即使 Chromium 已经下载成功,在缺少必要共享库的 Linux 环境中,浏览器仍然可能启动失败。
安装浏览器
先确认已经在项目中安装 @playwright/test,并进入包含 package.json 的项目根目录。运行以下命令安装当前 Playwright 版本所需的默认浏览器:
npx playwright install预期结果:命令正常结束,退出码为 0。首次安装时,终端通常显示浏览器下载进度及缓存位置,例如以下日志片段:
Downloading Chromium <ID> ...
Chromium <ID> downloaded to <PATH>实际版本、下载地址、缓存路径和日志内容可能不同。命令还会处理 Firefox、WebKit 及所需的辅助组件;如果对应文件已经缓存,可能不会再次下载,也不一定显示上述日志。
如果项目只需要 Chromium,例如目前只编写 Chromium 浏览器测试,可以只安装该浏览器:
npx playwright install chromium预期结果:命令成功退出,当前 Playwright 版本对应的 Chromium 浏览器文件可用。如果文件已经存在,安装程序通常直接复用缓存。该命令不会同时安装 Firefox 和 WebKit。
验证浏览器可启动
下载完成不等于运行成功。最直接的验证方法是调用 Playwright 的 chromium.launch(),尝试启动浏览器并正常关闭。
在项目根目录创建 verify-browser.cjs 文件,写入以下代码:
const { chromium } = require('@playwright/test');
async function verify() {
// 使用无头模式,避免依赖可见的桌面窗口
const browser = await chromium.launch({ headless: true });
console.log('Chromium launch OK');
// 验证完成后释放浏览器进程
await browser.close();
}
verify().catch((error) => {
console.error(error.message);
process.exitCode = 1;
});在同一项目目录执行 node verify-browser.cjs。
预期输出:
Chromium launch OK出现这行输出且进程正常退出,表示 Playwright 已经找到 Chromium 浏览器文件,并且浏览器能够在当前操作系统环境中启动和关闭。
如果出现 Executable doesn't exist,通常表示所需浏览器尚未下载、版本不匹配,或者安装与运行时使用了不同的浏览器缓存目录。如果出现缺少共享库的错误,则需要检查操作系统依赖,而不是反复执行同一段 JavaScript。
常见失败处理
浏览器下载失败
如果安装时出现网络连接超时、下载中断或证书相关错误,先确认当前环境可以访问浏览器下载源。需要通过代理访问外网时,应正确配置 HTTPS_PROXY 等环境变量,再重新执行安装命令。
下载中断后可以直接重试。Playwright 会检查已有浏览器文件,无需手动删除整个项目的 node_modules。
Linux 系统依赖缺失
在受支持的 Ubuntu、Debian 等 Linux 环境中,如果浏览器已下载但启动时报缺少系统库,可以执行:
npx playwright install --with-deps chromium预期结果:命令安装 Chromium 所需的操作系统依赖和浏览器文件并正常退出。安装系统软件包可能需要管理员权限,具体日志取决于 Linux 发行版和已安装的软件包。
该命令不是所有操作系统都需要执行的步骤。在 Windows 和 macOS 上,应优先根据实际启动错误排查,不要照搬 Linux 的系统依赖安装方式。
浏览器版本或缓存路径不一致
如果安装成功后仍提示找不到可执行文件,先检查安装命令与运行脚本是否使用同一项目的 Playwright 依赖版本。
如果配置了 PLAYWRIGHT_BROWSERS_PATH,还需要确认安装和运行阶段使用相同的环境变量值。否则浏览器可能下载到了一个目录,而运行时却在另一个目录查找。
修复后重新运行 node verify-browser.cjs。只有实际输出 Chromium launch OK,并且进程正常退出,才说明本课的 Chromium 浏览器运行环境通过了验证。Firefox 和 WebKit 仍需要分别进行启动验证,不能由 Chromium 的成功结果直接推断它们也可用。