1. 为什么 Markdown 转 Word/PDF 总在图片和字体上翻车把一份带 16 张截图的 Markdown 教程转成 Word 和 PDF听起来像是pandoc一行命令的事。但真正动手做过的人都知道坑几乎全集中在三个地方本地图片路径找不到、中文字体在 PDF 里变成方块、分页和目录页码对不上。这三个问题不解决导出的文档要么图片全丢要么满屏豆腐块要么目录页码和正文差了三页。我自己维护过一批技术教程源文件是 Markdown图片放在同级images/目录用相对路径引用。第一次导出 docx 时Word 里所有图片位置都是红色叉号换成 PDF 后中文标题直接变成一排问号。后来才搞清楚Markdown 里的这种相对路径在转换工具的工作目录和源文件目录不一致时就会失效而 PDF 引擎默认字体不含中文字形必须显式指定 CJK 字体。这篇就按“技术写作者批量导出图文教程”这个场景把整条链路拆开讲。核心思路是用脚本统一管理导出流程把模型调用凭据收敛到 TaoToken 一个 Key 上避免在多个脚本里散落不同的 API Key。适合手里有几十篇 Markdown 教程、需要定期产出 Word 审阅版和 PDF 交付版的人。先说清楚最终要达成的验收标准后面每一步都围绕它展开图片是否内嵌docx 和 pdf 打开后所有截图都在正确位置不依赖外部文件目录页码是否对齐PDF 目录里“第三章”指向的页码和实际正文页码一致docx 与 pdf 输出是否一致同一份 Markdown两种格式的标题层级、表格、图注不能有明显差异这三个标准看着简单但每一个都对应一类具体的配置错误。下面从环境准备开始一步步把链路搭起来。2. TaoToken 统一 Key 管理导出脚本的模型调用凭据导出脚本里为什么会用到模型调用因为纯pandoc只能做格式搬运做不了“智能”的部分。比如自动生成图注、把 Markdown 里的口语化标题润色成正式章节名、检查目录层级是否跳级、给 PDF 生成封面文案。这些环节我会调模型来处理而调模型就需要 Key。问题在于如果每个脚本里都硬编码一个 Key时间一长就会出现A 脚本用 Key1B 脚本用 Key2某个 Key 额度用完了不知道是哪个脚本在报 401。更麻烦的是有些导出流程会调用不同厂商的模型比如一个负责润色、一个负责生成封面描述如果每家都单独配 Key管理成本直接翻倍。我的做法是把所有模型调用统一走 TaoToken 的 API 通道脚本里只保留一个环境变量。TaoToken 的 API 地址是https://taotoken.net/api兼容常见的 OpenAI 风格调用方式所以现有脚本基本不用大改把base_url和api_key换掉就行。具体操作上我建议在项目根目录建一个.env文件只放两个变量# .env TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在导出脚本里用dotenv加载。这样无论脚本有多少个Key 只有一个来源。换 Key 的时候只改.env不用去翻每个.py文件。Key 的获取在控制台的 API Keys 页面登录后新建一个即可。建议给导出脚本单独建一个 Key命名成markdown-export方便后续按用途排查额度消耗。控制台地址是https://taotoken.net/consoleAPI Keys 管理页是https://taotoken.net/api-keys。这里有个细节要注意导出脚本调用模型时建议把model参数也做成可配置的。因为润色标题和生成封面文案对模型能力要求不同前者用轻量模型就够后者可能需要更强的推理能力。在 TaoToken 的模型对话页面可以先试一下不同模型对同一段 Markdown 标题的处理效果确认后再写进脚本配置。配置片段我一般写成 JSON放在项目里config/export.json{ taotoken: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, models: { polish: kimi-k2.6, cover: glm-5 } }, export: { source_dir: ./docs, image_dir: ./docs/images, output_dir: ./output, formats: [docx, pdf], cjk_font: Noto Sans CJK SC, toc_depth: 3 } }这个 JSON 是整个导出链路的配置中心。api_key_env指向环境变量名而不是 Key 本身避免 Key 进版本库。cjk_font是解决中文方块的关键后面会展开。toc_depth控制目录生成到几级标题设成 3 表示 H1 到 H3 都进目录。把 Key 收敛到一处之后接下来就可以放心写导出脚本了。脚本里所有模型调用都从config/export.json读配置从.env读 Key逻辑清晰排障也快。3. 可复制的导出配置图片路径、中文字体与分页样式这一节是整篇的核心给出可以直接复制运行的配置和脚本。我按“图片路径 → 中文字体 → 分页样式”的顺序来因为这三个问题的排查难度是递增的。3.1 图片路径相对路径失效的根因与修复Markdown 里写pandoc在转换时是相对于当前工作目录去找图片的而不是相对于 Markdown 文件所在目录。如果你在项目根目录执行pandoc docs/tutorial.md -o out.docx它会去根目录下的images/找而不是docs/images/于是图片全丢。修复方式有两种。第一种是执行前先cd到 Markdown 文件所在目录cd docs pandoc tutorial.md -o ../output/tutorial.docx第二种更稳妥用--resource-path显式指定图片搜索路径pandoc docs/tutorial.md \ --resource-pathdocs:docs/images \ -o output/tutorial.docx--resource-path里用冒号分隔多个路径pandoc会依次查找。我实测下来第二种方式在批量脚本里更可靠因为不用改工作目录。但这里还有个隐藏坑如果 Markdown 里用的是绝对路径或者带盘符的 Windows 路径--resource-path不生效。批量导出前建议先跑一个检查脚本把所有图片引用扫一遍确认都是相对路径且文件真实存在import re, os, json with open(config/export.json) as f: cfg json.load(f) src_dir cfg[export][source_dir] img_dir cfg[export][image_dir] missing [] for root, _, files in os.walk(src_dir): for name in files: if not name.endswith(.md): continue path os.path.join(root, name) with open(path, encodingutf-8) as f: content f.read() for m in re.finditer(r!\[.*?\]\((.*?)\), content): img m.group(1) if img.startswith(http): continue full os.path.normpath(os.path.join(os.path.dirname(path), img)) if not os.path.exists(full): missing.append((path, img)) print(缺失图片:, missing if missing else 无)这个脚本跑完如果输出“无”说明图片路径没问题可以进入下一步。如果有缺失先补齐再导出否则 docx 里会出现空白占位。3.2 中文字体PDF 方块字的根治方案PDF 里中文变方块是因为默认的 LaTeX 或 wkhtmltopdf 引擎没有加载中文字体。用pandoc生成 PDF 时如果走 LaTeX 路线需要在导言区指定 CJK 字体如果走 HTML 转 PDF 路线需要在 CSS 里指定font-family。我推荐用 HTML 中转的方式因为对中文字体控制更直接。先写一个 CSS 文件config/export.csspage { size: A4; margin: 2.2cm 2cm; bottom-center { content: counter(page); font-size: 9pt; color: #666; } } body { font-family: Noto Sans CJK SC, Source Han Sans SC, Microsoft YaHei, sans-serif; font-size: 11pt; line-height: 1.7; color: #222; } h1, h2, h3 { font-family: Noto Sans CJK SC, Source Han Sans SC, sans-serif; color: #2D5F8A; page-break-after: avoid; } img { max-width: 100%; display: block; margin: 1em auto; } figcaption { text-align: center; font-size: 9pt; color: #666; margin-top: 0.3em; } table { border-collapse: collapse; width: 100%; page-break-inside: avoid; } th, td { border: 1px solid #ccc; padding: 6px 10px; font-size: 10pt; } th { background: #2D5F8A; color: #fff; }关键在body和h1,h2,h3的font-family把Noto Sans CJK SC放在最前面。这个字体在大多数 Linux 服务器和 macOS 上都能装Windows 上如果没有会自动回退到Microsoft YaHei。page里的bottom-center是页码counter(page)会自动递增。然后导出 PDF 的命令pandoc docs/tutorial.md \ --resource-pathdocs:docs/images \ --cssconfig/export.css \ --pdf-engineweasyprint \ --toc --toc-depth3 \ -o output/tutorial.pdfweasyprint对 CSS 分页支持比较好--toc会自动生成目录。如果服务器上没装 weasyprintpip install weasyprint即可。它依赖一些系统库Ubuntu 上需要libpango和libcairo装的时候留意报错。3.3 分页样式目录页码对齐与章节不跨页目录页码对不上通常是因为目录本身占了一页但页码计数从目录页就开始了导致正文页码整体偏移。解决方式是在 CSS 里让目录页不参与正文页码计数或者让正文从新的一页开始并重置页码。在page里加一个命名页page toc { bottom-center { content: none; } } .toc { page: toc; page-break-after: always; }然后在生成的 HTML 里给目录容器加上classtoc。pandoc生成的目录默认没有这个 class所以更简单的做法是用--template自定义模板或者导出后用脚本给目录 div 加 class。另一个常见问题是章节标题跑到页面底部和正文分离。CSS 里的page-break-after: avoid就是干这个的加在h1,h2,h3上保证标题后面至少跟一行正文。表格跨页断裂也是高频问题page-break-inside: avoid加在table上可以避免。但如果表格本身超过一页这个属性会导致表格整体被推到下一页留出大片空白。这种情况需要权衡我的做法是给表格加page-break-inside: auto但给tr加page-break-inside: avoid保证单行不裂开。docx 的分页控制没有 CSS 这么灵活但pandoc支持--reference-doc可以拿一个预先设好样式的 docx 作为模板。模板里把标题样式、页眉页脚、目录样式都配好导出时直接套用pandoc docs/tutorial.md \ --resource-pathdocs:docs/images \ --reference-docconfig/reference.docx \ --toc --toc-depth3 \ -o output/tutorial.docxreference.docx的制作方法是先用pandoc -o reference.docx --print-default-data-file reference.docx导出一份默认模板然后在 Word 里改样式改完存回。重点改“标题 1/2/3”的字体和颜色、“正文”的行距、页脚的页码域。把这三块配置都落地之后导出脚本就可以批量跑了。下一节验证实际输出结果。4. 验证请求图片内嵌、目录页码与 docx/pdf 一致性配置写完不代表就对了必须逐项验证。我一般分三步先验证模型调用通道是否通再验证单篇导出结果最后批量跑并抽查。4.1 验证 TaoToken 通道在跑导出脚本之前先用一个最小请求确认 Key 和 base_url 没问题curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: kimi-k2.6, messages: [{role: user, content: 回复OK}], max_tokens: 10 }如果返回里有choices字段且内容是“OK”说明通道正常。如果返回 401检查.env里的 Key 是否加载成功如果返回local proxy failed之类的错误检查base_url是否写成了https://taotoken.net/api而不是别的路径。4.2 验证单篇导出拿一篇带图片的 Markdown 跑一遍python export.py --file docs/tutorial.md --formats docx,pdf导出后打开 docx重点看三处第一图片是否内嵌。把 docx 复制到另一个没有images/目录的地方再打开如果图片还在说明是内嵌的如果变红叉说明还是外链。pandoc默认会把图片嵌入 docx但如果用了--extract-media参数图片会被抽出来单独存反而变成外链注意别加这个参数。第二目录页码。在 Word 里右键目录选“更新域”看页码是否和正文一致。如果目录页码从 1 开始但正文从 3 开始说明目录页被计入了页码需要按 3.3 节的方式处理。第三标题层级。打开 Word 的导航窗格看 H1/H2/H3 是否正常嵌套。如果所有标题都变成正文样式说明reference.docx里的样式名和pandoc期望的不一致需要检查模板。PDF 的验证类似但多一项放大到 200% 看中文是否清晰、有没有方块。如果出现方块说明font-family里的字体在系统里没装需要fc-list | grep -i cjk确认一下。4.3 批量导出与一致性抽查单篇没问题后批量跑python export.py --all --formats docx,pdf跑完随机抽三篇把 docx 和 pdf 并排打开对比同一章节的标题、表格、图注。我实测下来不一致通常出现在两个地方一是 docx 里表格有边框但 pdf 里没有这是 CSS 没生效二是 docx 里图片居中但 pdf 里左对齐这是img的display: block; margin: auto在 weasyprint 里没被识别需要改成text-align: center包一层。一致性检查可以写个简单脚本对比两种格式的页数和标题数量from docx import Document import fitz # PyMuPDF doc Document(output/tutorial.docx) docx_headings [p.text for p in doc.paragraphs if p.style.name.startswith(Heading)] pdf fitz.open(output/tutorial.pdf) pdf_toc pdf.get_toc() print(docx 标题数:, len(docx_headings)) print(pdf 目录项数:, len(pdf_toc)) print(页数:, pdf.page_count)如果 docx 标题数和 pdf 目录项数差太多说明有一边的标题层级识别有问题回去检查 Markdown 里的标题写法是否规范比如#后面有没有空格。验证通过后这套链路就可以固化成定时任务或者 CI 步骤每次 Markdown 更新自动重新导出。5. 常见报错排查401、local proxy failed、reading choices、OAuth导出链路跑起来后报错基本集中在模型调用和转换引擎两块。我把踩过的坑按报错原文列出来对照排查。5.1 401 Unauthorized{error: {message: Invalid API key, type: invalid_request_error}}原因通常是.env没被加载或者 Key 复制时带了空格。排查步骤先echo $TAOTOKEN_API_KEY看环境变量是否为空如果为空检查脚本里有没有load_dotenv()如果不为空检查 Key 前后有没有多余字符。另外确认 Key 是在https://taotoken.net/api-keys页面生成的且没有过期或被删除。5.2 local proxy failedError: local proxy failed to connect这个报错一般出现在脚本里配置了本地代理但代理服务没启动。检查脚本里有没有http_proxy或https_proxy环境变量如果有先unset掉再跑。TaoToken 的 API 是直连的不需要经过任何本地代理。5.3 reading choicesTypeError: Cannot read properties of undefined (reading choices)这是脚本解析响应时响应体里没有choices字段。原因可能是请求根本没发出去网络问题、返回的是错误对象比如 401 的 JSON 里没有 choices、或者模型名写错了导致返回 404。排查时先把原始响应print出来看看到底返回了什么。如果是 404检查model字段的值是否在 TaoToken 支持的模型列表里。5.4 OAuth 相关报错OAuth token expired or invalid如果你用的是 Claude Code 或 Codex 这类工具它们可能走 OAuth 流程而不是 API Key。导出脚本里如果混用了 OAuth 凭据和 API Key会出现这个报错。解决方式是统一用 API Key在脚本里显式指定api_key不要依赖工具自动读取的 OAuth 配置。对于 Claude Code 的接入需要配全三件套Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你要用的模型名。这三个缺一个都会报错。Codex 的auth.json里同样要写全这三项格式参考官方文档。5.5 图片仍然丢失如果按 3.1 节配了--resource-path还是丢图检查 Markdown 里的图片路径有没有 URL 编码字符比如空格变成%20或者路径里有中文。pandoc对中文路径的支持取决于系统编码建议图片文件名统一用英文和数字。5.6 PDF 中文仍然是方块按 3.2 节配了 CSS 还是方块说明系统里确实没装 CJK 字体。Ubuntu 上装fonts-noto-cjkCentOS 上装google-noto-sans-cjk-fontsmacOS 上系统自带。装完用fc-cache -fv刷新字体缓存再重新导出。这些报错覆盖了 90% 的情况。如果遇到别的先把原始错误信息完整打印出来再对照 TaoToken 的接入文档排查。文档地址是https://taotoken.net/doc里面有各语言的调用示例和错误码说明。6. 把导出链路固化成可复用流程走到这里单篇和批量导出都验证过了报错也有对照表。最后说几个让这套流程更耐用的实践。第一把config/export.json和.env分开管理。export.json进版本库.env进.gitignore。团队协作时每个人本地建自己的.envKey 不共享但配置共享。第二导出脚本加一个--dry-run参数只检查图片路径和标题层级不实际调用模型和转换引擎。这样在 CI 里可以先跑 dry-run通过了再跑正式导出省额度也省时间。第三模型调用加缓存。同一篇 Markdown 的标题润色结果如果内容没变就不用重复调模型。用文件内容的 hash 做 key把结果存到.cache/目录下次直接读缓存。这样批量导出几十篇时只有改过的文件才会触发模型调用。第四PDF 封面生成单独走一个流程。封面文案和背景图不依赖正文内容可以提前生成好放在assets/cover/目录导出时用--include-before-body插入。这样正文导出和封面生成解耦互不影响。第五定期检查 TaoToken 的额度消耗。在控制台的用量页面可以看到每个 Key 的调用次数和 token 消耗。如果发现某个脚本消耗异常回去检查是不是缓存没生效导致重复调用。这套流程我用了大半年从最初每次导出都要手动修图片路径到现在一条命令批量产出 docx 和 pdf中间省下来的时间相当可观。核心就是把配置收敛、把验证自动化、把报错对照表建起来。你可以先从单篇跑通再逐步加批量、加缓存、加 CI不用一次到位。