PDF 技能

使用 Python 库和命令行工具进行 PDF 操作的完整指南。

⚡ 功能速查表

一键查询所有支持的操作 —— 快速找到合适的工具。

💡 任何脚本均可通过 --help 查看全部可用选项。

快速决策指南

你需要什么？
├── 从零创建新 PDF               → reportlab  （参见 references/create.md）
├── 提取文本 / 表格               → pdfplumber  （参见 references/extract.md）
├── 合并 / 分割 / 旋转页面         → pypdf 或 qpdf CLI
├── 重新排序页面                  → scripts/reorder_pdf.py
├── 添加水印 / 加密 / 保护         → pypdf
├── 填写 PDF 表单                 → pdf-lib (JS) 或 pypdf  （参见 FORMS.md）
├── 从 PDF 中提取图片             → pdfimages CLI 或 pypdf
├── 对扫描版 PDF 进行 OCR          → pdf2image + pytesseract
├── 压缩 / 减小文件大小            → scripts/compress_pdf.py （qpdf + pypdf）
├── 查看 PDF 信息 / 元数据         → scripts/pdf_info.py
├── 图片转 PDF                    → scripts/images_to_pdf.py （reportlab）
├── PDF 转图片                    → scripts/pdf_to_images.py （pdf2image）
├── 比较 / 差异分析两个 PDF        → scripts/compare_pdf.py
├── 修复损坏的 PDF                → scripts/repair_pdf.py （qpdf + pypdf）
└── 列出 PDF 中的字体             → scripts/list_fonts.py

安装

Linux（Ubuntu/Debian）

# Python 库
pip install pypdf pdfplumber reportlab pdf2image pytesseract Pillow --break-system-packages

# 系统工具
sudo apt-get install -y poppler-utils tesseract-ocr qpdf

# 中文 OCR 支持
sudo apt-get install -y tesseract-ocr-chi-sim tesseract-ocr-chi-tra

# Node.js（表单填写）
npm install pdf-lib

macOS（Homebrew）

# 系统工具（用于 OCR 和命令行操作）
brew install qpdf poppler tesseract

# 重要：非英文 OCR 需单独安装语言包
brew install tesseract-lang

# Python 库
pip install pypdf pdfplumber reportlab pdf2image pytesseract Pillow --break-system-packages

# Node.js（表单填写）
npm install pdf-lib

⚠️ macOS 注意：tesseract-lang 必须单独安装，否则中文、日文等非英文 OCR 将失败。安装后运行 tesseract --list-langs 确认可用语言。

验证安装

# 检查 Python 库
python3 -c "import pypdf, pdfplumber, reportlab, PIL; print('✓ Python libs OK')"

# 检查系统工具
which qpdf       && echo "✓ qpdf OK"       || echo "✗ qpdf not installed"
which tesseract   && echo "✓ tesseract OK"  || echo "✗ tesseract not installed"
which pdftotext   && echo "✓ poppler OK"    || echo "✗ poppler not installed"

# 检查 OCR 语言
tesseract --list-langs 2>/dev/null | head -5

核心操作

读取并提取文本

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())

→ 有关高级提取选项，请参见 references/extract.md

提取表格 → DataFrame

import pdfplumber, pandas as pd

with pdfplumber.open("report.pdf") as pdf:
    for page in pdf.pages:
        for table in page.extract_tables():
            df = pd.DataFrame(table[1:], columns=table[0])
            print(df)

合并 PDF

from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for path in ["a.pdf", "b.pdf", "c.pdf"]:
    writer.append(PdfReader(path))
with open("merged.pdf", "wb") as f:
    writer.write(f)

分割 PDF

markdown

Skill: docs-pdf

Version: 1.0.3

Chunk: 2/2

拆分 PDF 页面

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    w = PdfWriter()
    w.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as f:
        w.write(f)

旋转页面

reader = PdfReader("scan.pdf")
writer = PdfWriter()
for page in reader.pages:
    page.rotate(90)   # 支持 90 / 180 / 270
    writer.add_page(page)
with open("rotated.pdf", "wb") as f:
    writer.write(f)

添加密码保护

from pypdf import PdfReader, PdfWriter

reader = PdfReader("doc.pdf")
writer = PdfWriter()
for page in reader.pages:
    writer.add_page(page)
writer.encrypt("user_pass", "owner_pass", use_128bit=False)  # 使用 AES-256 加密
with open("encrypted.pdf", "wb") as f:
    writer.write(f)

CLI 快速参考（qpdf）

# 合并文件
qpdf --empty --pages a.pdf b.pdf -- merged.pdf

# 提取第 1 到第 5 页
qpdf input.pdf --pages . 1-5 -- out.pdf

# 将所有页面旋转 90°
qpdf input.pdf output.pdf --rotate=+90

# 移除密码保护
qpdf --password=secret --decrypt locked.pdf unlocked.pdf

# 线性化（适用于网页优化）
qpdf --linearize input.pdf output.pdf

可用脚本

直接使用这些脚本，无需重新编写：

运行任意脚本时，可通过 --help 查看其可用选项。

参考文件

在需要深入指导时加载以下文件：

• references/create.md — 使用 reportlab（Platypus、Canvas、样式、表格、页眉页脚）从零创建 PDF
• references/extract.md — 高级文本/表格/图像提取，基于坐标的裁剪，逐词数据提取
• references/security.md — 水印、加密、权限控制、数字签名
• references/ocr.md — OCR 处理流程、语言包、图像预处理、质量调优
• FORMS.md — PDF 表单填写完整指南（AcroForm + XFA，pdf-lib JS）

快速参考表

常见陷阱

• 不要在 reportlab 中使用 Unicode 上标/下标（如 ₂, ⁰），应改用 <sub> / <super> XML 标签，否则可能显示为黑色方块
• 文本提取推荐使用 pdfplumber，而非 pypdf — pypdf 的 extract_text() 会丢失布局信息；pdfplumber 支持布局感知
• 加密 PDF：需在 PdfReader() 和 pdfplumber.open() 中传入 password=
• pip 在沙箱环境：始终添加 --break-system-packages 参数
• 大文件处理优先 qpdf CLI：对于大批量任务，建议使用 qpdf 命令行工具，而非 Python 循环
• macOS OCR 语言包：brew install tesseract 仅包含英文；非英文 OCR 需额外执行 brew install tesseract-lang
• macOS 系统依赖：OCR 和 CLI 操作前需先安装 brew install qpdf poppler tesseract
• 测试表单填充：若无可填写的 PDF，可先运行 python scripts/create_test_form.py 生成测试表单
• OCR 与 pdfplumber 的区别：OCR 仅适用于扫描件（图片型 PDF）。对原生文本 PDF 内容提取，应使用 pdfplumber（速度更快、更准确）
• 中文表单填充：pypdf 内置字体不支持 CJK 字符，中文内容可能显示为方块。如需中文表单填充，请使用 pdf-lib (JS) 方案（参见 FORMS.md）
• 页面旋转：无独立旋转脚本，可使用 python scripts/batch_convert.py rotate input.pdf -d 90

⛔ 限制场景（不适用）