安装 Playwright 浏览器自动化

在容器内安装 Chromium 并注册 Playwright MCP 服务器后，AI 即可打开网页、点击元素、填写表单、抓取页面内容与截图。

需要 Debian / Ubuntu 容器

Chrome for Testing 的二进制依赖 glibc，内置 Alpine 镜像使用 musl libc，无法运行。请先参照 容器与镜像 导入自定义 Debian 或 Ubuntu 镜像。

环境基线

项	值
系统	Debian / Ubuntu，容器内默认 root
架构	aarch64（arm64）或 x86_64
浏览器	Chrome for Testing 153.0.8010.12，安装至 /opt/chrome
MCP 服务	@playwright/mcp，由 npx 按需拉取

1. 安装依赖

apt-get update -qq && apt-get install -y -qq unzip fonts-noto-cjk

缺少中文字体时，截图中的中文会显示为方块。

2. 下载并解压 Chromium

以 arm64 为例；x86_64 需将 URL 中的 linux-arm64 替换为 linux64，解压目录名替换为 chrome-linux64。

mkdir -p /opt/chrome
curl -L -o /tmp/chrome.zip \
  https://cdn.npmmirror.com/binaries/chrome-for-testing/153.0.8010.12/linux-arm64/chrome-linux-arm64.zip
unzip -q /tmp/chrome.zip -d /opt/chrome
rm /tmp/chrome.zip

/opt/chrome/chrome-linux-arm64/chrome --version
# 输出 Google Chrome for Testing 153.0.8010.12

上面用的是 npmmirror 镜像，也可改用官方源；该版本下架时替换 URL 中的版本号即可：

https://storage.googleapis.com/chrome-for-testing-public/153.0.8010.12/linux-arm64/chrome-linux-arm64.zip

3. 注册 MCP 服务器

进入「设置 → MCP 服务器 → +」，传输类型选择本地 stdio，按下表填写后保存，App 会自动连接。

字段	值
名称	playwright
启动命令	npx
命令参数	-y、@playwright/mcp@latest、--headless、--no-sandbox、--executable-path、/opt/chrome/chrome-linux-arm64/chrome（逐项添加）
作用域	全局（所有项目共用）或项目（仅当前工作区）

也可直接编辑配置文件，全局为 ~/.aicode/mcp.json，项目级为 <工作区>/.aicode/mcp.json，保存后数秒内自动生效：

{
    "mcpServers": {
        "playwright": {
            "command": "npx",
            "args": [
                "-y",
                "@playwright/mcp@latest",
                "--headless",
                "--no-sandbox",
                "--executable-path",
                "/opt/chrome/chrome-linux-arm64/chrome"
            ],
            "enabled": true
        }
    }
}

其中 --no-sandbox 在容器内必须指定，否则浏览器启动即崩溃；--executable-path 指向已安装的 Chromium，避免 Playwright 重复下载。

默认 headless 的 User-Agent 带有 HeadlessChrome 标识，部分站点会据此拦截，可追加 --user-agent 覆盖（界面中作为两个参数项依次添加）：

--user-agent
Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36

截图等输出文件默认写入运行目录下的 .playwright-mcp/，也就是当前工作区根目录，会在仓库里留下未跟踪文件。追加 --output-dir 可移出工作区：

--output-dir
/root/playwright-output

截图时指定了文件名则例外：相对路径按工作区解析，会绕过 --output-dir，需写绝对路径。

4. 验证

进入「设置 → MCP 服务器」，playwright 一行应显示为已连接并标注工具数量；连接失败时点击右上角的日志按钮排查。

随后新建会话（工具列表在会话开始时确定），令 AI 打开网页并截图，返回图片即表示链路正常。首次连接需等待 npx 下载 @playwright/mcp，实测 3 至 4 分钟。

常见问题

现象	原因	解决
启动即 Target closed 或崩溃退出	缺少 --no-sandbox	补充该参数后重新连接
终端直接运行 chrome 报 /dev/shm FATAL	容器无 /dev/shm，且 /dev 不可写	附加 --disable-dev-shm-usage；由 Playwright 启动的不受影响
chrome: not found 或二进制无法执行	容器为 Alpine（musl），或包与架构不符	更换 Debian / Ubuntu 镜像，核对 arm64 与 x64 包
截图中文显示为方块	缺少中文字体	执行 apt-get install -y fonts-noto-cjk
截图为空白页或整张透明	无 GPU 环境下渲染偶发失败	重试一次，仍为空白时改用 JPEG 格式
首次调用需等待数分钟	npx 正在下载 @playwright/mcp	等待完成，此后使用本地缓存；也可将 npm registry 换为 https://registry.npmmirror.com
MCP 列表中没有 playwright	配置未生效或 JSON 存在语法错误	确认 mcp.json 可正常解析，再点击右上角「重新连接」

附：一键安装脚本

以下脚本完成第 1 至 3 步，另含下载源自动切换、压缩包校验、已安装时跳过下载、写入前备份 mcp.json。保存为 /tmp/install-playwright.sh 后执行 bash /tmp/install-playwright.sh：

#!/usr/bin/env bash
set -euo pipefail

VERSION="${CHROME_VERSION:-153.0.8010.12}"
DIR=/opt/chrome
ZIP=/tmp/chrome-$VERSION.zip

case "$(uname -m)" in
  aarch64|arm64) SUB=linux-arm64; NAME=chrome-linux-arm64 ;;
  x86_64)        SUB=linux64;     NAME=chrome-linux64 ;;
  *) echo "不支持的架构: $(uname -m)"; exit 1 ;;
esac
BIN="$DIR/$NAME/chrome"

[ "$(id -u)" = 0 ] || { echo "请以 root 运行"; exit 1; }
command -v python3 >/dev/null || { echo "缺少 python3"; exit 1; }
command -v npx >/dev/null || echo "[警告] 未找到 npx，MCP 服务无法启动"

need=()
command -v unzip >/dev/null || need+=(unzip)
fc-list :lang=zh 2>/dev/null | grep -q . || need+=(fonts-noto-cjk)
if [ ${#need[@]} -gt 0 ]; then
  echo "安装依赖：${need[*]}"
  apt-get update -qq && apt-get install -y -qq "${need[@]}"
fi

if [ -x "$BIN" ]; then
  echo "已安装，跳过下载：$BIN"
else
  for url in \
    "https://cdn.npmmirror.com/binaries/chrome-for-testing/$VERSION/$SUB/$NAME.zip" \
    "https://storage.googleapis.com/chrome-for-testing-public/$VERSION/$SUB/$NAME.zip"
  do
    echo "下载：$url"
    curl -fL --retry 3 --retry-delay 2 -o "$ZIP" "$url" && break
    echo "[警告] 该源不可用，切换下一个"
  done
  [ -s "$ZIP" ] || { echo "全部下载源均失败"; exit 1; }

  mkdir -p "$DIR"
  unzip -tq "$ZIP" && unzip -q "$ZIP" -d "$DIR"
  rm -f "$ZIP"
fi

"$BIN" --version

BIN="$BIN" python3 - <<'PY'
import json, os, shutil
p = os.path.expanduser("~/.aicode/mcp.json")
os.makedirs(os.path.dirname(p), exist_ok=True)
data = {}
if os.path.exists(p):
    shutil.copy(p, p + ".bak")
    with open(p, encoding="utf-8") as f:
        data = json.load(f)   # 存在语法错误时报错退出，不覆盖
data.setdefault("mcpServers", {})["playwright"] = {
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest", "--headless", "--no-sandbox",
             "--executable-path", os.environ["BIN"]],
    "enabled": True,
}
with open(p, "w", encoding="utf-8") as f:
    json.dump(data, f, indent=4, ensure_ascii=False)
print("已写入 playwright 配置")
PY

echo "安装完成：$BIN"

CHROME_VERSION 可指定其它版本。安装完成后返回第 4 步验证。