Marp CLI 在 Docker 环境中生成 PDF 失败的解决方案

在使用 Marp CLI 进行幻灯片编译时，部分用户在 Docker 容器（如 zenika/alpine-chrome 或 node:20-bookworm）中遇到了 PDF 生成失败的问题。本文将深入分析问题原因并提供完整的解决方案。

问题现象

当用户尝试在容器内执行 Marp CLI 命令时，系统会抛出 ECONNRESET 错误并终止进程。错误日志显示 Chromium 浏览器进程意外终止，导致 PDF 生成失败。

根本原因分析

经过技术排查，发现该问题主要由以下两个因素共同导致：

1. Chromium 沙箱限制：最新版本的 Chromium 浏览器默认启用了安全沙箱机制，当检测到以 root 用户身份运行时（这在 Docker 容器中很常见），会主动终止进程。

2. Marp CLI 版本兼容性：旧版 Marp CLI（v3.4.0）与新版 Chromium 的 headless 模式存在兼容性问题，特别是在容器化环境中表现更为明显。

解决方案

方案一：升级 Marp CLI（推荐）

建议将 Marp CLI 升级至 v4.0.2 或更高版本，该版本已针对容器环境进行了优化：

npm install -g @marp-team/marp-cli@latest

方案二：配置环境变量

对于必须使用特定版本的情况，可通过以下环境变量配置解决问题：

export CHROME_PATH=/usr/bin/chromium
export CHROME_NO_SANDBOX=1

方案三：完整 Docker 配置示例

以下是一个完整的 Dockerfile 配置示例，确保所有依赖正确安装：

FROM node:20-bookworm

RUN apt-get update && apt-get install -y chromium
ENV CHROME_PATH=/usr/bin/chromium
ENV CHROME_NO_SANDBOX=1

RUN npm install -g @marp-team/marp-cli

WORKDIR /app
COPY . .
RUN marp --allow-local-files slides.md -o output.pdf

技术原理详解

1. Chromium 沙箱机制：Chromium 设计的安全沙箱要求进程不能以 root 身份运行，这是现代浏览器的基本安全要求。通过 CHROME_NO_SANDBOX 环境变量可以临时禁用此限制。

2. Headless 模式演进：Chromium 团队对 headless 模式进行了重大改进，新版 Marp CLI 适配了这些变化，而旧版可能无法正确处理新的通信协议。

3. 容器环境特殊性：Docker 容器通常以 root 用户运行，这与常规开发环境不同，需要特别注意权限和沙箱配置。

最佳实践建议

1. 始终使用最新稳定版的 Marp CLI
2. 在 CI/CD 流水线中显式设置 CHROME_NO_SANDBOX
3. 定期更新基础镜像以获取安全补丁
4. 考虑使用官方提供的 Docker 镜像作为基础

通过以上解决方案，用户应该能够顺利在容器环境中使用 Marp CLI 生成 PDF 文件。如遇其他问题，建议启用完整调试日志（--debug=all）进行进一步诊断。