VSCode导出Markdown为PDF必须依赖扩展，推荐Markdown Preview Enhanced（MPE）或Pandoc+XeLaTeX；MPE需先打开预览窗（Ctrl+K V）、确认公式图表已渲染、配置YAML字体fallback，Pandoc则需手动安装并指定xelatex引擎。
VSCode 本身不提供文档导出格式的原生配置能力，所有「导出为 PDF/HTML/DOCX」行为都依赖扩展，且必须明确选择路径：用 Markdown Preview Enhanced（推荐）还是 Pandoc + XeLaTeX。其他插件如 Markdown PDF（yzane）在 2026 年已彻底失效，中文显示方框、公式不渲染、Mermaid 图空白——不是你配错了，是底层工具链（PhantomJS / wkhtmltopdf）已被淘汰。
必须先打开 MPE 预览窗，再导出
MPE 的 PDF 导出逻辑是「截取当前预览页 DOM 快照」，不是解析源码。没打开它自己的预览窗口，导出就是空页或纯文本：
- 用
Ctrl+K V（Windows/Linux）或Cmd+K V（macOS），不是 VS Code 原生的Ctrl+Shift+V - 确认预览地址含
preview-enhanced字样（如http://localhost:3000/preview-enhanced/...） - 肉眼检查：Mermaid 图是否已渲染成 SVG、
$$E=mc^2$$是否已转为数学符号、代码块是否有颜色 - 导出按钮只在预览窗口右上角（↓ 图标），编辑器右键菜单里的 “Export to PDF” 是旧插件残留，点它无效
YAML front matter 和 CSS 字体 fallback 缺一不可
即使预览正常，PDF 仍可能中文字体错位、段落挤在一起——因为 Puppeteer 渲染时默认字体不支持 CJK，且不加载 @font-face：
- 文档顶部加
---分隔的 YAML front matter，例如：---\npdf_options:\n format: 'A4'\n margin: {top: '20mm', right: '15mm', bottom: '20mm', left: '15mm'}\n stylesheet: ./style.css\n--- -
stylesheet路径必须是相对路径，且style.css文件得和 .md 在同一目录 -
style.css中至少声明两个中文字体 fallback：body { font-family: "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; } - 别写
font-family: "SimSun"—— Windows 默认无 SimSun，Mac/Linux 更找不到
Puppeteer Chromium 下载失败？手动指定路径更稳
首次导出时 MPE 默认调用 Puppeteer 下载 Chromium（约 150MB），但内网、杀毒软件、Gatekeeper 权限常导致卡在 Failed to launch chrome：
- 终端执行：
npx puppeteer install chromium（macOS/Linux）或npx puppeteer install chromium --platform=win64（Windows） - 安装完成后，在 VS Code 设置中填
markdown-preview-enhanced.puppeteerPath，值为绝对路径，例如：/Users/you/Library/Caches/puppeteer/chromium/mac-arm64-1234567/chrome-mac/Chromium - Windows 用户注意关闭杀毒软件实时扫描，否则 Chromium 二进制文件可能被误删
- 别指望“自动下载成功”——手动装完再配路径，才是 2026 年最稳的路径
需要真正分页、页眉页脚、自动编号？绕不开 Pandoc + XeLaTeX
Puppeteer 导出本质是网页截图，字体发虚、页边距不可控、无跨页表格支持；Pandoc + XeLaTeX 才能生成出版级 PDF：
- macOS 安装：
brew install pandoc && brew install --cask mactex；Windows 用scoop install pandoc && scoop install texlive，再手动安装思源宋体等中文字体到系统字体库 - VS Code 设置中填
mpe.exportPandocPath，值为绝对路径（如/opt/homebrew/bin/pandoc），不能用~或环境变量 - 导出命令需显式指定引擎：
pandoc input.md -o output.pdf --pdf-engine=xelatex，用pdflatex会报The font "SimSun" cannot be found - LaTeX 模板控制力更强，但 CSS 仅部分生效：
@page、font-family、margin可用，flex、grid、position: fixed全部被忽略
最易被忽略的一点：MPE 导出前必须人工确认三件事——预览窗已打开、Mermaid 和公式已渲染完成、CSS 字体 fallback 已生效。任何一步靠“应该没问题”跳过，PDF 就大概率残缺。这不是配置问题，是渲染链路本身的确定性约束。
