Playwright-Java 在 Docker 容器中启动失败的完整解决方案-java教程-PHP中文网

Playwright-Java 在 Docker 容器中启动失败的完整解决方案

Playwright-Java 在 Docker 中抛出 RuntimeException: Failed to create driver，根本原因是官方镜像未预装浏览器二进制文件，且容器缺少必要系统依赖（如字体、libglib、libnss 等），导致 Playwright 自动下载/解压 Chromium 时执行 playwright.sh 失败。

playwright-java 在 docker 中抛出 `runtimeexception: failed to create driver`，根本原因是官方镜像未预装浏览器二进制文件，且容器缺少必要系统依赖（如字体、libglib、libnss 等），导致 playwright 自动下载/解压 chromium 时执行 `playwright.sh` 失败。

在基于 mcr.microsoft.com/playwright/java:v1.35.0-jammy-amd64 的容器中直接调用 Playwright.create() 并 launch() 浏览器，会触发 Playwright Java SDK 的自动浏览器安装逻辑——它尝试在 /tmp 下解压并运行一个名为 playwright.sh 的脚本。然而，该脚本依赖底层 Linux 系统库（如 libnss3, libglib2.0-0, fonts-liberation, ttf-freefont 等），而官方镜像虽已预装 Chromium，但默认未启用 --with-deps 模式安装，也未确保所有运行时依赖就绪；更关键的是，Playwright Java 的自动安装机制在容器受限环境中常因 fork/exec 权限、/tmp 挂载策略或 SELinux/AppArmor 限制而失败（错误日志中 Failed to exec spawn helper: pid: 36, exit value: 1 即典型表现）。

✅ 正确做法是：禁用自动安装，改用预装浏览器 + 显式指定可执行路径，并补全系统依赖。

✅ 推荐 Dockerfile 改写方案（适配 v1.35.0）

FROM mcr.microsoft.com/playwright/java:v1.35.0-jammy-amd64

# 补全 Playwright 运行必需的系统依赖（Ubuntu 22.04）
RUN apt-get update && apt-get install -y \
    libnss3 \
    libglib2.0-0 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libxkbcommon-x11-0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libpango-1.0-0 \
    libcairo2 \
    libfreetype6 \
    fonts-liberation \
    ttf-freefont \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /opt
ARG JAR_FILE=target/*.jar
COPY ${JAR_FILE} ./company-pdf-service.jar

# 关键：通过环境变量告知 Playwright 复用已预装的 Chromium
# 官方镜像中 Chromium 位于 /ms-playwright/chromium-*/chrome
ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright

EXPOSE 8300
ENTRYPOINT ["java", "-Dplaywright.skipBrowserDownload=true", "-jar", "./company-pdf-service.jar"]

⚠️ 注意：PLAYWRIGHT_BROWSERS_PATH 环境变量必须指向 /ms-playwright（官方镜像约定路径），而非 ~/.cache/ms-playwright —— 后者是默认用户缓存路径，在容器中不可靠。

✅ Spring Boot 初始化代码优化（避免资源泄漏与线程安全问题）

原 @PostConstruct 初始化存在严重隐患：Playwright 实例未关闭、Browser 未复用、未启用 headless 模式（容器无 GUI）。应改为：

@Component
public class PlaywrightPdfConverterService {

    private Playwright playwright;
    private Browser browser;

    @PostConstruct
    public void init() {
        LOGGER.info("Initializing Playwright with pre-installed Chromium...");
        // 显式禁用下载，并设置浏览器为 headless（容器必需）
        playwright = Playwright.create(
            new Playwright.CreateOptions()
                .setSkipBrowserDownload(true) // 强制跳过下载
        );
        browser = playwright.chromium().launch(
            new BrowserType.LaunchOptions()
                .setHeadless(true)                    // 必须启用 headless
                .setArgs(List.of("--no-sandbox", "--disable-setuid-sandbox"))
        );
    }

    @PreDestroy
    public void destroy() {
        if (browser != null) browser.close();
        if (playwright != null) playwright.close();
    }

    public byte[] generatePdf(String htmlContent) {
        try (BrowserContext context = browser.newContext();
             Page page = context.newPage()) {
            page.setContent(htmlContent, new Page.SetContentOptions().setWaitUntil(WaitUntilState.NETWORKIDLE));
            return page.pdf(new Page.PdfOptions().setFormat("A4"));
        }
    }
}

? 验证与调试技巧

检查浏览器路径是否存在：进入容器执行

Java JDK 25
Java JDK 25 来自 OpenJDK 官方归档，版本为 JDK 25，本条下载地址已指向官方 Windows x64 zip 安装包直链，适合调试旧项目或兼容旧版 Java 运行环境。

下载
```
ls -la /ms-playwright/chromium-*/
```
应看到类似 chromium-1064/chrome 的结构。

手动测试脚本执行权限（临时诊断）：

chmod +x /ms-playwright/chromium-*/chrome
/ms-playwright/chromium-*/chrome --version

启用 Playwright 日志（开发期追加 JVM 参数）：
-Dplaywright.debug=true -Dplaywright.log.level=DEBUG

? 总结

问题根源	解决方案
playwright.sh 执行失败（exec spawn helper 错误）	补全 libnss3, libglib2.0-0, 字体等系统依赖
自动下载 Chromium 在容器中不可靠	设置 PLAYWRIGHT_BROWSERS_PATH=/ms-playwright + skipBrowserDownload=true
缺少 headless 和 sandbox 参数导致启动失败	launch() 时显式传入 --headless --no-sandbox
@PostConstruct 未释放资源	使用 @PreDestroy 确保 Playwright 和 Browser 正确关闭