# 用 Python + Edge 无头模式，把飞书导出的 Markdown 压缩包转成精美 PDF

> 飞书文档导出为 Markdown + 图片压缩包后，直接打开是一堆 HTML 标签和散乱的图片，排版完全不可读。本文介绍如何用 Python 写一个通用转换脚本，一键将飞书 Markdown 压缩包转换为排版精美的 A4 PDF，支持表格内图片自动提取、表头颜色识别、封面页生成，零第三方依赖。

## 方案选型：为什么不用现成工具？

在动手写脚本之前，我调研了几种方案：

| 方案 | 优点 | 缺点 |
|------|------|------|
| **Pandoc** | 通用、强大 | 不识别飞书自定义 HTML 标签；表格内图片处理差 |
| **Typora 导出 PDF** | 所见即所得 | 无法批量处理；需要手动安装 |
| **Python-docx 转 Word 再转 PDF** | 可控 | Word 对图片排版天生弱势；多一步转换 |
| **WeasyPrint（Python 库）** | 纯 Python，无需浏览器 | Windows 上需要安装 GTK 运行时，依赖地狱 |
| **Edge/Chrome** |系统自带、CSS 支持最完整、渲染效果最好 | 需要生成中间 HTML |

最终选择了 **Python 生成 HTML → Edge 无头模式渲染 PDF** 的方案。原因：

- Windows 系统自带 Edge，零安装成本
- Chromium 内核对 CSS Grid、Flexbox、分页等特性的支持最完整
- 渲染效果和浏览器预览完全一致，所见即所得
- Python 端只负责文本处理 + CSS 注入，逻辑清晰

## 飞书导出包的标准化结构

先写一段分析脚本，搞清楚飞书导出包到底长什么样：

```python
import zipfile, re, os
from urllib.parse import unquote

z = zipfile.ZipFile('input.zip', 'r')
entries = z.namelist()

# 1. 找 MD 文件
md_files = [e for e in entries if e.endswith('.md')]
md_text = z.read(md_files[0]).decode('utf-8')

# 2. 统计结构
print(f"标题: H1={len(re.findall(r'^# ', md_text, re.MULTILINE))}, "
      f"H2={len(re.findall(r'^## ', md_text, re.MULTILINE))}, "
      f"H3={len(re.findall(r'^### ', md_text, re.MULTILINE))}")
print(f"HTML表格: {len(re.findall(r'<table', md_text))}")
print(f"图片引用: {len(re.findall(, md_text))}")
print(f"引用块: {len(re.findall(r'^>', md_text, re.MULTILINE))}")

# 3. 分析图片路径编码
img_refs = re.findall(r]+src="([^"]+)"', md_text)
for ref in [:5]:
    decoded = unquote(ref)
    print(f"  原始: {ref}")
    print(f"  解码: {decoded}")
```

分析结果：

```
标题: H1=1, H2=13, H3=17
HTML表格: 14
图片引用: 87
引用块: 12
```

关键发现：

1. **图片路径全部 URL 编码**，需要 `urllib.parse.unquote` 解码后才能匹配文件名
2. **图片文件名含空格**，需要做模糊匹配（去除空格后比较）
3. **HTML 表格是纯 `<table>` 标签**，不是 Markdown 管道表格，需要原样保留
4. **颜色样式是 `rgb(r,g,b)` 或 `#xxxxxx` 格式**的内联样式

## 核心设计思路

### 整体流程

```
飞书 zip 包
    │
    ├─ 读取 images/ → base64 编码全部图片
    │
    ├─ 读取 .md 文件
    │     │
    │     ├─ 按空行分块（表格作为整体不拆分）
    │     │
    │     └─ 逐块转换：
    │           ├─ # 标题 → <h1>~<h4>
    │           ├─ > 引用 → <blockquote>
    │           ├─ - 列表 → <ul><li>
    │           ├─ <table> → 注入 CSS class + 提取内部图片
    │           ├─ <img> → 替换为 base64 data URL
    │           └─ 纯文本 → <p>
    │
    └─ 组装完整 HTML（含 PDF 专用 CSS）
          │
          └─ Edge --headless --print-to-pdf → PDF
```

### 为什么图片要 base64 嵌入？

PDF 需要是**自包含的单文件**，不能依赖外部图片路径。所以将所有图片转格式直接嵌入 HTML 中。

### 为什么表格内图片要提取出来？

飞书的表格里经常在一个单元格中塞多张截图。如果直接渲染，图片会把表格撑变形。解决方案：

1. 用正则把表格中所有标签提取出来
2. 表格本身只保留文字内容
3. 提取出的图片以**卡片网格**形式展示在表格下方

这样表格清爽可读，图片也有充足的展示空间。

**系统要求**：Windows 10/11，已安装 Microsoft Edge 或 Google Chrome（系统自带 Edge 即可）。无需安装任何 Python 第三方库。

## workbuddy开发提示词

### 提示词

```
我需要一个 Python 脚本，将飞书文档导出的 Markdown 压缩包转换为排版精美的 PDF。

## 输入格式
飞书导出的标准 zip 包，结构为：
- 1 个 .md 文件（Markdown + HTML 混合内容）
- images/ 文件夹（所有图片，文件名含中文和空格）

## Markdown 内容特点
1. 标题用 # ~ #### 的标准 Markdown 语法
2. 表格是完整的 HTML <table> 标签（不是 Markdown 管道表格）
3. 表格内部嵌套了 <ul><li>、<img>、<blockquote> 等子元素
4. 图片路径是 URL 编码的
5. 颜色样式通过 inline style 实现（background-color: rgb(r,g,b)）
6. 引用块用 > 开头的标准 Markdown 语法
7. 一个 <td> 单元格里可能塞了 7~10 张图片

## 输出要求
1. 输出为单个 PDF 文件，图片全部嵌入（base64）
2. A4 纸张，页边距 2cm
3. 封面页：文档标题居中，蓝色分隔线，无页码
4. 正文从第二页开始，底部显示页码
5. 表格：圆角边框，表头有背景色（紫色 rgb(100,37,208) 或蓝色 rgb(36,91,219) 需要自动识别）
6. 表格内的图片要提取出来，在表格下方以卡片网格排列（每行3列），每张图片下方显示 alt 说明文字
7. 独立图片居中显示
8. 引用块：左侧蓝色竖线，浅灰背景
9. 使用 print-color-adjust: exact 确保背景色在 PDF 中正确显示
10. 用 CSS Flexbox 而不是 Grid（PDF 渲染兼容性更好）

## 技术约束
1. Python 标准库 only（zipfile、re、os、base64、mimetypes、subprocess），不安装第三方依赖
2. PDF 渲染使用 Edge 或 Chrome 的 --headless --print-to-pdf 模式
3. 先生成临时 HTML 文件（base64 嵌入图片），再用浏览器无头模式渲染为 PDF，渲染完删除临时文件
4. 图片路径需要 urllib.parse.unquote 解码 + 模糊匹配（处理空格差异）
5. HTML 表格块不做深度解析，只注入 CSS class 和提取图片，内部 HTML 原样保留
6. Markdown 文本按空行分块处理，<table> 标签作为整体不拆分
```

### AI 辅助开发的建议

1. **一次性把所有约束写清楚** — 不要分步给要求，AI 容易在前期做错误决策后期难以修正
2. **明确"不要做什么"** — 比如"不要用 WeasyPrint"、"不要深度解析 HTML 表格"，这比"用什么"更重要
3. **提供输入样例** — 给一段实际的飞书 Markdown 内容片段，让 AI 理解真实格式
4. **分步验证** — 先验证图片路径解析是否正确，再验证表格处理，最后验证 PDF 渲染
5. **关注 CSS 兼容性** — PDF 渲染和浏览器预览有差异，`display: grid`、`position: fixed` 等特性在 PDF 中可能失效

*本文工具已开源，完整脚本可从文中直接复制使用。如果觉得有帮助，欢迎点赞收藏。*#workbuddy@腾讯技术创作特训营S18@workbuddy#腾讯技术创作特训营S18

飞书文档导出为 Markdown + 图片压缩包后，直接打开是一堆 HTML 标签和散乱的图片，排版完全不可读。本文介绍如何用 Python 写一个通用转换脚本，一键将飞书 Markdown 压缩包转换为排版精美的 A4 PDF，支持表格内图片自动提取、表头颜色识别、封面页生成，零第三方依赖。

workbuddy开发markdown压缩包转PDF工具腾讯技术创作特训营S18专题分享workbuddy使用经验分享

编程语言

开发工具

后端

本文详细介绍使用Python+Edge无头模式将飞书导出的Markdown压缩包转换为精美PDF的方法。方案采用Python标准库生成HTML并注入PDF专用CSS，通过Edge浏览器无头模式渲染，实现表格内图片自动提取、表头颜色识别、封面页生成。支持A4纸张排版，图片base64嵌入，确保PDF自包含且排版清晰。无需安装第三方依赖，适用于Windows系统自带Edge环境。

图片处理

图片压缩

Windows

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文详细介绍使用Python+Edge无头模式将飞书导出的Markdown压缩包转换为精美PDF的方法。方案采用Python标准库生成HTML并注入PDF专用CSS，通过Edge浏览器无头模式渲染，实现表格内图片自动提取、表头颜色识别、封面页生成。支持A4纸张排版，图片base64嵌入，确保PDF自包含且排版清晰。无需...

workbuddy开发markdown压缩包转PDF工具腾讯技术创作特训营S18专题分享workbuddy使用经验分享-腾讯云开发者社区-腾讯云

workbuddy开发markdown压缩包转PDF工具腾讯技术创作特训营S18专题分享workbuddy使用经验分享

workbuddy开发markdown压缩包转PDF工具腾讯技术创作特训营S18专题分享workbuddy使用经验分享

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐