alcintra/weasyprint-docker

docker-weasyprint 镜像文档

镜像概述

docker-weasyprint 是一个基于 WeasyPrint 的 Docker 镜像，旨在提供便捷的 HTML/CSS 转 PDF 功能。WeasyPrint 是一款功能强大的工具，能够将 HTML 和 CSS 文档渲染为高质量 PDF，支持 CSS Paged Media 规范，适用于生成报告、发票、电子书等结构化文档。该镜像将 WeasyPrint 及其依赖项容器化，消除了本地环境配置的复杂性，确保跨平台运行一致性。

核心功能与特性

• HTML/CSS 转 PDF：支持将标准 HTML5 和 CSS3 文档转换为 PDF 格式，保留页面布局、样式和字体。
• CSS Paged Media 支持：完全支持 CSS 分页媒体属性（如 @page、page-break 等），可自定义页面大小、边距、页眉页脚。
• 轻量级容器：基于精简基础镜像构建，体积小，启动速度快。
• 无依赖部署：无需在主机安装 Python、GTK 或其他系统库，直接通过容器运行。
• 灵活的文件挂载：支持挂载本地目录，实现输入文件读取和输出文件保存。

使用场景

• 服务器端 PDF 生成：Web 应用中动态生成 PDF 报告（如订单确认、统计报表）。
• 自动化文档处理：CI/CD 流程中批量转换 HTML 模板为 PDF 文档。
• 跨平台开发：在不同操作系统（Windows、macOS、Linux）上提供一致的 PDF 生成环境。
• 原型验证：快速验证 HTML/CSS 设计在 PDF 中的渲染效果。

使用方法

基本使用（docker run）

通过挂载本地目录，将 HTML 文件转换为 PDF：

bash
# 将当前目录下的 input.html 转换为 output.pdf
docker run --rm -v $(pwd):/data alastairtodd/weasyprint input.html output.pdf

参数说明：

• --rm：容器运行结束后自动删除。
• -v $(pwd):/data：将当前目录挂载到容器内的 /data 目录，实现文件共享。
• input.html：输入的 HTML 文件路径（相对于挂载目录 /data）。
• output.pdf：输出的 PDF 文件路径（相对于挂载目录 /data）。

传递 WeasyPrint 命令行参数

支持 WeasyPrint 原生命令行参数，例如指定页面大小、添加样式表等：

bash
# 指定页面大小为 A4，添加自定义样式表
docker run --rm -v $(pwd):/data alastairtodd/weasyprint \
  --page-size A4 \
  --stylesheet custom.css \
  input.html output.pdf

常用参数：

• --page-size：设置页面大小（如 A4、Letter、A5）。
• --margin-top/right/bottom/left：设置页面边距（单位：mm、cm、in）。
• --stylesheet：添加额外的 CSS 样式表。
• --presentational-hints：启用对 HTML 演示属性（如 align）的支持。

docker-compose 配置示例

创建 docker-compose.yml 文件，定义 PDF 生成服务：

yaml
version: '3'
services:
  weasyprint:
    image: alastairtodd/weasyprint
    volumes:
      - ./html:/data/input  # 挂载输入 HTML 目录
      - ./pdf:/data/output  # 挂载输出 PDF 目录
    command: input/report.html output/report.pdf

启动服务：

bash
docker-compose up

注意事项

• 文件权限：确保挂载目录具有读写权限，避免因权限问题导致文件无法读取或写入。
• 字体支持：若 PDF 中需要特殊字体，需将字体文件挂载到容器内的字体目录（如 /usr/share/fonts）。
• HTML/CSS 兼容性：WeasyPrint 对现代 CSS 特性支持有限，建议使用标准 CSS 2.1 和 CSS Paged Media 规范。

相关链接

• 项目源码：https://github.com/alastair-todd/docker-weasyprint
• WeasyPrint 官方文档：[***]