Marp CLI 的 Docker 镜像构建与部署指南

Marp CLI 是一个基于 Node.js 的命令行工具，用于将 Markdown 文件转换为幻灯片演示文稿。本文将深入解析其 Docker 镜像的构建过程，帮助开发者理解如何高效地部署和使用 Marp CLI。

镜像构建架构

Marp CLI 的 Docker 镜像采用了多阶段构建策略，这种设计具有以下优势：

1. 构建阶段分离：第一阶段专注于应用构建，第二阶段专注于运行时环境准备
2. 镜像体积优化：最终镜像仅包含必要的运行时文件，不包含构建工具
3. 安全性增强：减少了不必要的构建依赖暴露

构建阶段详解

第一阶段：应用构建

FROM --platform=$BUILDPLATFORM node:22.15.0-bookworm-slim AS build
WORKDIR /home/node/marp-cli
COPY . .
RUN npm ci && npm run build

这一阶段使用 Node.js 22.15.0 的精简版作为基础镜像，特点包括：

• 明确指定构建平台，支持跨平台构建
• 使用 npm ci 而非 npm install，确保依赖版本精确匹配
• 执行构建命令生成生产环境可用的代码

第二阶段：运行时准备

FROM node:22.15.0-bookworm-slim

同样基于 Node.js 22.15.0 的精简版，但仅包含运行时所需的最小环境。

安全与权限管理

镜像采用了严格的用户权限控制：

RUN groupadd -r marp && useradd -r -g marp marp && mkdir -p /home/marp/app /home/marp/.cli && chown -R marp:marp /home/marp

• 创建专门的 marp 用户和用户组
• 设置专用的工作目录和数据目录
• 确保目录权限正确，遵循最小权限原则

Chromium 浏览器集成

Marp CLI 需要 Chromium 进行 PDF 和幻灯片导出：

RUN mkdir -p /tmp/marp-cli-chromium && \
  cd /tmp/marp-cli-chromium && \
  npm i playwright@latest && \
  PLAYWRIGHT_BROWSERS_PATH=/usr/local/bin/pw-browsers npx playwright install --with-deps chromium && \
  ln -s $(find /usr/local/bin/pw-browsers -name "chrome" -executable | head -n 1) /usr/local/bin/chrome && \
  rm -rf /tmp/marp-cli-chromium

技术要点：

• 使用 Playwright 而非 Puppeteer 获取 Chromium，以支持 ARM64 架构
• 安装 Chromium 及其依赖项
• 创建符号链接方便调用
• 清理临时安装文件

环境优化

RUN apt update && \
  apt install -y --no-install-recommends gosu && \
  apt clean && \
  rm -rf /var/lib/apt/lists/* && \
  npm cache clean --force

• 安装必要的系统工具 gosu（用于安全切换用户）
• 清理 APT 缓存和 Node.js 缓存，减少镜像体积

环境变量配置

ENV MARP_USER=marp:marp PATH=$PATH:/home/marp/.cli CHROME_PATH=/usr/local/bin/chrome

关键环境变量：

• MARP_USER：指定运行用户
• PATH：扩展可执行路径
• CHROME_PATH：指定 Chromium 可执行文件位置

应用文件部署

USER marp
WORKDIR /home/marp/.cli
COPY --chown=marp:marp package.json package-lock.json marp-cli.js LICENSE docker-entrypoint ./
RUN npm ci --omit=dev && npm cache clean --force

• 切换到非特权用户
• 复制必要的应用文件并设置正确权限
• 安装生产依赖，不包含开发依赖

构建产物集成

COPY --chown=marp:marp --from=build /home/node/marp-cli/lib/ ./lib/

从构建阶段复制编译后的代码到运行时镜像，保持构建与运行环境分离。

入口点与启动配置

USER root
WORKDIR /home/marp/app
ENTRYPOINT ["docker-entrypoint"]
CMD ["--help"]

• 使用自定义入口点脚本
• 默认显示帮助信息
• 工作目录设置为用户可写目录

V8 编译缓存优化

RUN node /home/marp/.cli/marp-cli.js --version

这一巧妙的设计在构建时预生成 V8 编译缓存，可以显著提升容器启动后的首次执行性能。

最佳实践建议

1. 镜像体积优化：当前设计已考虑精简，但可进一步评估 node:22.15.0-alpine 是否适用
2. 安全扫描：建议在 CI/CD 流程中加入镜像漏洞扫描
3. 多架构支持：当前设计已考虑 ARM64 支持，可扩展至其他架构
4. 版本管理：考虑使用多标签策略管理不同 Node.js 版本

通过本文的详细解析，开发者可以深入理解 Marp CLI Docker 镜像的设计哲学和技术实现，为自定义部署和二次开发奠定基础。