Ubuntu 下 Playwright 终极安装指南：从环境配置到日志调试

摘要：本文详细介绍了在 Ubuntu 20.04/22.04/24.04 上安装 Microsoft Playwright 的完整流程。涵盖了项目级安装（推荐）、全局安装（慎用）、依赖库处理以及关键的日志调试技巧。无论你是自动化测试新手还是资深开发者，都能在此找到最佳实践。

📅 前言

Playwright 是目前最流行的端到端（E2E）测试框架之一，支持 Chromium、Firefox 和 WebKit。但在 Linux (Ubuntu) 环境下，很多初学者容易卡在“浏览器下载成功但无法启动”这一步，原因通常是缺少系统级依赖。

本文将带你一步步搞定所有问题，并教你如何通过日志排查疑难杂症。

🚀 方式一：项目级安装（官方强烈推荐 ✅）

这是最稳定、最适合团队协作和 CI/CD 集成的方式。每个项目拥有独立的 Playwright 版本，互不干扰。

1. 初始化项目与安装依赖

打开终端，进入你的项目目录：

# 1. 快速初始化 package.json (如果已有可跳过)
npm init -y

# 2. 安装 Playwright 测试运行器作为开发依赖
# 推荐使用 @playwright/test，它包含了核心库和测试框架
npm install -D @playwright/test

2. 下载浏览器二进制文件

安装 npm 包后，需要下载具体的浏览器内核（如 Chromium）：

1 2	npx playwright install chromium # 如果需要所有浏览器：npx playwright install

3. 安装 Ubuntu 系统依赖（关键步骤 ⚠️）

Playwright 的浏览器依赖大量的 Linux 系统库（如 libnss3, libatk-bridge 等）。必须使用 sudo 执行此命令，否则浏览器启动时会报错 missing shared libraries。

1 2	sudo npx playwright install-deps chromium # 如果安装了所有浏览器，则运行：sudo npx playwright install-deps

系统会提示确认安装，输入 Y 并回车即可。

4. 验证与运行

安装完成后，你可以初始化示例项目或直接运行测试：

# 生成示例配置文件和测试用例
npx playwright init

# 运行测试
npx playwright test

🌍 方式二：全局安装（仅限特定场景 ⚠️）

适用场景：仅用于个人临时脚本、系统工具分发或快速原型验证。
缺点：容易导致不同项目间的版本冲突，且 CI/CD 流水线通常无法识别全局包。

1. 全局安装包

1	npm install -g @playwright/test

2. 全局下载浏览器

全局安装后，可以直接使用 playwright 命令（无需 npx）：

1	playwright install chromium

3. 全局安装系统依赖

同样需要 root 权限安装系统库：

1	sudo playwright install-deps chromium

4. 如何使用

在任意目录下直接运行：

1	playwright test my-test.spec.ts

🐳 附赠：Docker 自动化部署片段

如果你需要在 Docker 中运行，以下是精简版的 Dockerfile 逻辑：

FROM mcr.microsoft.com/playwright:v1.42.0-jammy

WORKDIR /app

# 复制依赖文件
COPY package*.json ./
RUN npm ci

# 复制代码
COPY . .

# 运行测试 (镜像已预装浏览器和依赖，无需再次 install-deps)
CMD ["npx", "playwright", "test"]

注：直接使用微软官方的 Playwright Docker 镜像是最省事的方法，里面已经预装了所有浏览器和系统依赖。

🕵️‍♂️ 进阶：如何查看调试日志？

当测试失败或浏览器无法启动时，盲目猜测是低效的。Playwright 提供了强大的日志系统。

1. 查看框架内部通信日志 (DEBUG 模式)

通过设置 DEBUG 环境变量，可以看到 Playwright 与浏览器进程交互的详细过程。

Linux/Mac 命令：

# 查看 API 调用日志
DEBUG=pw:api npx playwright test

# 查看更底层的协议日志 (非常详细)
DEBUG=pw:protocol npx playwright test

常见用途：

排查浏览器为什么启动失败。
查看选择器定位的具体过程。
分析网络请求的拦截情况。

2. 查看网页控制台日志 (Console Log)

如果你想知道网页内部的 JavaScript 报错（如 console.log, Uncaught Error），可以在代码中监听 console 事件，或者直接打开浏览器开发者工具。

代码方式监听：

import { test } from '@playwright/test';

test('check console logs', async ({ page }) => {
  // 监听页面控制台消息
  page.on('console', msg => {
    console.log(`PAGE LOG: ${msg.type()} - ${msg.text()}`);
  });

  await page.goto('https://example.com');
  // 触发某些操作...
});

手动方式：
如果是使用 npx playwright open 或 codegen 启动的浏览器，直接在弹出的浏览器窗口按 F12，查看 Console 标签页即可。

❓ 常见问题解答 (FAQ)

Q: 运行 install-deps 时提示 command not found？
A: 确保你已经安装了 @playwright/test 包。如果是全局安装，请检查 npm 的全局 bin 目录是否在 $PATH 中。

Q: 浏览器启动了但立刻崩溃？
A: 90% 的情况是因为没运行 sudo npx playwright install-deps。请检查是否缺少 .so 共享库。

Q: 国内下载浏览器速度太慢怎么办？
A: 可以配置镜像源。在运行 install 命令前设置环境变量：

1 2	export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright npx playwright install chromium

🎯 总结

步骤	项目级安装 (推荐)	全局安装
安装包	`npm install -D @playwright/test`	`npm install -g @playwright/test`
下浏览器	`npx playwright install chromium`	`playwright install chromium`
装依赖	`sudo npx playwright install-deps`	`sudo playwright install-deps`
运行命令	`npx playwright test`	`playwright test`
稳定性	⭐⭐⭐⭐⭐ (隔离性好)	⭐⭐ (易冲突)