report_viewer/PDF生成环境说明.md

PDF 生成环境说明文档

📋 概述

本项目使用 Python 脚本将 JSON 数据转换为 PDF 报告。主要依赖 WeasyPrint 库进行 HTML 到 PDF 的转换。

🔧 环境要求

Python 版本

• Python 3.8+ （推荐 Python 3.9 或更高版本）
• 支持 Windows、Linux、macOS

系统依赖

Windows

• 需要安装 GTK+ 运行时库（WeasyPrint 的必需依赖）
• 推荐使用 Conda 环境（自动处理依赖）

Linux

• 需要安装系统级字体库和 GTK+ 相关库
• Ubuntu/Debian: sudo apt-get install python3-dev python3-pip python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
• CentOS/RHEL: sudo yum install python3-devel python3-pip cairo pango gdk-pixbuf2 libffi

macOS

• 需要安装 GTK+ 和相关库
• 推荐使用 Homebrew: brew install cairo pango gdk-pixbuf libffi

📦 Python 依赖包

项目依赖以下 Python 包（见 requirements.txt）：

包名	版本要求	说明
jinja2	>=3.1.2	HTML 模板引擎，用于渲染报告模板
weasyprint	>=60.0	PDF 生成库，将 HTML 转换为 PDF

🚀 安装步骤

方法一：使用 Conda（推荐，Windows 用户首选）

Conda 会自动处理所有系统依赖，包括 GTK+ 运行时库。

# 1. 创建 Conda 环境（可选）
conda create -n pdf-generator python=3.9
conda activate pdf-generator

# 2. 安装 WeasyPrint（自动安装所有依赖）
conda install -c conda-forge weasyprint

# 3. 安装其他依赖
pip install jinja2

方法二：使用 pip + 手动安装系统依赖

Windows

1. 安装 GTK+ 运行时库

   • 下载地址：https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
   • 下载并安装最新的 gtk3-runtime-*.exe（64位版本）
   • 安装到默认路径：C:\Program Files\GTK3-Runtime Win64
   • 确保安装程序自动添加到 PATH，或手动添加：C:\Program Files\GTK3-Runtime Win64\bin

2. 安装 Python 依赖

   pip install -r requirements.txt
   

3. 重启终端（重要！让 PATH 生效）

Linux

# 1. 安装系统依赖（Ubuntu/Debian 示例）
sudo apt-get update
sudo apt-get install python3-dev python3-pip python3-cffi \
    libcairo2 libpango-1.0-0 libpangocairo-1.0-0 \
    libgdk-pixbuf2.0-0 libffi-dev shared-mime-info

# 2. 安装 Python 依赖
pip install -r requirements.txt

macOS

# 1. 安装系统依赖（使用 Homebrew）
brew install cairo pango gdk-pixbuf libffi

# 2. 安装 Python 依赖
pip install -r requirements.txt

方法三：使用虚拟环境（推荐用于生产环境）

# 1. 创建虚拟环境
python -m venv venv

# 2. 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

✅ 验证安装

运行以下命令验证环境是否正确配置：

python -c "from weasyprint import HTML; print('WeasyPrint 安装成功！')"

如果出现错误，请参考下面的"常见问题"部分。

📝 使用方法

基本用法

python generate_pdf.py <数据文件> [输出文件]

示例

# 使用示例数据生成 PDF
python generate_pdf.py public/example.json output.pdf

# 指定输出文件名（默认为 report.pdf）
python generate_pdf.py public/example.json my_report.pdf

数据文件格式

• 支持 JSON 格式文件
• 文件应包含 DWBG8B4D 或 CDWBG8B4D 的谛听报告数据
• 可选包含 FLXG7E8F 或 FLXG0V4B 的司法涉诉数据

🐛 常见问题

问题 1: OSError: cannot load library 'libgobject-2.0-0'

原因：Windows 系统缺少 GTK+ 运行时库。

解决方案：

1. 推荐：使用 Conda 安装 WeasyPrint

   conda install -c conda-forge weasyprint
   

2. 或：手动安装 GTK+ 运行时库

   • 下载：https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
   • 安装后重启终端

问题 2: ImportError: No module named 'weasyprint'

原因：WeasyPrint 未安装或不在当前 Python 环境中。

解决方案：

pip install weasyprint
# 或使用 Conda
conda install -c conda-forge weasyprint

问题 3: ImportError: No module named 'jinja2'

原因：Jinja2 模板引擎未安装。

解决方案：

pip install jinja2

问题 4: 生成的 PDF 中文显示为方块

原因：系统缺少中文字体。

解决方案：

• Windows：系统自带中文字体，通常无需额外配置
• Linux：安装中文字体

  sudo apt-get install fonts-wqy-microhei fonts-wqy-zenhei
  

• macOS：系统自带中文字体

问题 5: Conda 安装 WeasyPrint 时卡住或报错

原因：Conda 依赖解析时间过长或网络问题。

解决方案：

1. 更新 Conda：

   conda update conda
   

2. 使用国内镜像源（如果在中国）：

   conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
   conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
   conda config --add channels conda-forge
   

3. 或使用 pip + GTK+ 运行时库的方式

问题 6: 权限错误（Linux/macOS）

原因：没有权限安装系统依赖。

解决方案：

# 使用 sudo 安装系统依赖
sudo apt-get install ...  # Ubuntu/Debian
sudo yum install ...      # CentOS/RHEL

🔍 环境检查清单

在开始使用前，请确认：

• Python 版本 >= 3.8
• WeasyPrint 已正确安装
• Jinja2 已正确安装
• （Windows）GTK+ 运行时库已安装并添加到 PATH
• （Linux/macOS）系统依赖已安装
• 可以成功导入 WeasyPrint：python -c "from weasyprint import HTML"

📚 相关资源

• WeasyPrint 官方文档：https://weasyprint.org/
• Jinja2 官方文档：https://jinja.palletsprojects.com/
• GTK+ Windows 运行时：https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
• Conda 文档：https://docs.conda.io/

💡 最佳实践

1. 使用虚拟环境：避免污染系统 Python 环境
2. Windows 用户优先使用 Conda：自动处理所有依赖，最简单
3. 定期更新依赖：pip install --upgrade weasyprint jinja2
4. 测试环境：在生成大量 PDF 前，先用示例数据测试

🔄 更新依赖

# 更新所有依赖
pip install --upgrade -r requirements.txt

# 或单独更新
pip install --upgrade weasyprint jinja2

📞 技术支持

如果遇到问题：

1. 检查 Python 版本：python --version
2. 检查已安装的包：pip list | grep -E "weasyprint|jinja2"
3. 查看错误信息：运行 python generate_pdf.py 查看详细错误
4. 验证环境：运行 python -c "from weasyprint import HTML; print('OK')"

---

最后更新：2025-01-20