PDF 导出失败

常见原因

• Pandoc 没装（症状："pandoc not found"）
• LaTeX 引擎缺失（症状："pdflatex / xelatex not found"）
• PATH 里没有 Pandoc / LaTeX 的 bin 目录（装了但 Kition 看不到）
• 文档里有需要 CJK 字体的字符，但用的是默认 pdflatex（不支持 Unicode）
• 图片路径包含空格 / 中文，pandoc 找不到
• 导出目录无写权限（如 macOS 上选了 /）

一次性安装

macOS — 用 Homebrew 装最省事：

# macOS: pandoc + a minimal TeX distribution
brew install pandoc
brew install --cask basictex

# After basictex installs, refresh PATH in current shell:
eval "$(/usr/libexec/path_helper)"

# Verify
pandoc --version
which xelatex

# If you write Chinese / Japanese / Korean, also install CJK fonts:
sudo tlmgr update --self
sudo tlmgr install collection-langchinese collection-fontsrecommended

Windows 安装

• 从 pandoc.org/installing.html 下 Windows MSI 安装包
• 从 miktex.org/download 装 MiKTeX（推荐 basic installer，按需自动装包）
• 安装完后重启 Kition（不重启它会复用旧的 PATH）
• 在 PowerShell 跑 pandoc --version 确认能找到

逐步诊断

• 终端跑 which pandoc / where.exe pandoc，看是否能找到
• 终端跑 which xelatex，确认 LaTeX 引擎也在 PATH
• 试着用命令行直接转一个最小文档：pandoc test.md -o test.pdf --pdf-engine=xelatex
• 在 Settings → Export → Engine 里把引擎从 pdflatex 改成 xelatex（支持 Unicode）
• 查 Kition 日志：grep -i "pandoc\|xelatex" ~/Library/Logs/Kition/main.log | tail -20
• 导出失败后看 Kition 的临时目录有没有 .log 文件 — LaTeX 的真错误在那里

修复

• 装好后重启 Kition（PATH 需要被新进程继承）
• 中文 / 日文丢失：把 engine 切到 xelatex，并在 Settings → Export → "Main font" 里选系统已装的 CJK 字体
• 图片找不到：把图片移到 vault 内、用相对路径，避免空格和中文路径名
• PATH 看不到：Settings → Export → "Custom binary path" 手动指 /Library/TeX/texbin/xelatex
• 无写权限：换个导出目录，比如 ~/Downloads/

应急方案

如果你只是临时需要一个 PDF、不想为这一次装整套 LaTeX：File → Export → HTML，然后浏览器打开 → 打印 → "另存为 PDF"。视觉上接近 90%，足够做大多数分享场景。

如果是大批量文档要导出，可以在终端跑批：for f in *.md; do pandoc "$f" -o "${f%.md}.pdf" --pdf-engine=xelatex; done。

什么时候该提 bug

• 命令行 pandoc 能成功导出同一文档、Kition 里失败
• 日志里看不到调用 pandoc 的那行（说明 UI 没真的触发导出）
• xelatex 在中等文档（10 页内）上耗时 > 60 秒
• 导出成功但 PDF 中所有 emoji 显示成豆腐块（应自动 fallback 字体）