直接用markdown pdf插件导出常失败，因默认依赖已停更的phantomjs或vscode 1.80+禁用未签名插件，导致报错“spawn phantomjs enoent”或卡在“exporting…”；需改用基于puppeteer的markdown-pdf（支持latex、css）或轻量export-markdown-pdf，并正确配置type为chrome、关闭页眉页脚、启用相对路径。
为什么直接用 Markdown PDF 插件导出经常失败
因为 Markdown PDF 插件默认依赖本地 PhantomJS 或 Chromium，而 PhantomJS 已停止维护，VSCode 1.80+ 又默认禁用不签名插件，很多用户点导出没反应、报 Error: spawn phantomjs ENOENT 或卡在“Exporting…”。它不是“一键”就能跑通的工具，得先切到现代渲染引擎。
替换为 markdown-pdf（推荐）或 export-markdown-pdf
两个更可靠的替代方案：markdown-pdf（基于 Puppeteer + Chromium）和 export-markdown-pdf（轻量、纯前端、无需额外安装）。前者功能全但需 Node.js；后者开箱即用但不支持 LaTeX 公式和自定义 CSS。
-
markdown-pdf：装完后首次导出会自动下载 Chromium（约 150MB），之后快且稳定；支持markdown-pdf.convertOnSave配置、页眉页脚、mathjax渲染 -
export-markdown-pdf：不依赖 Node，右键菜单直接导出，适合临时快速生成；但无法处理$$...$$块级公式，也不读取工作区.vscode/settings.json中的样式配置 - 别同时装多个 PDF 导出插件——它们的右键菜单项会冲突，导出行为不可预测
导出前必须检查的三个配置项
即使插件装对了，导出仍可能空白或乱码，问题常出在这三处：
-
markdown-pdf.type：设为chrome（不是phantomjs），否则仍走废弃路径 -
markdown-pdf.displayHeaderFooter：设为false，Chrome 的页眉页脚在无 GUI 环境下容易触发渲染异常 -
markdown-pdf.preprocess：如果文档含相对路径图片（如），确保路径相对于当前 .md 文件，且markdown-pdf.relativePath设为true
这些配置可写进用户设置或工作区 .vscode/settings.json，例如：
{
"markdown-pdf.type": "chrome",
"markdown-pdf.displayHeaderFooter": false,
"markdown-pdf.relativePath": true
}
中文导出乱码？重点看字体和编码
PDF 中中文显示为方框，大概率不是插件问题，而是 Chromium 渲染时找不到中文字体。Windows 和 macOS 通常自带宋体/黑体，Linux（尤其 Docker 或最小化系统）常缺失。
- Linux 下运行
fc-list :lang=zh查是否有中文字体；没有就装fonts-wqy-zenhei或noto-fonts-cjk - macOS 若用 M1/M2 芯片，确认 VSCode 是原生 ARM64 版本，x86_64 模拟运行时字体路径可能错乱
- 不要试图改
markdown-pdf.css里font-family写“微软雅黑”，Chromium 在 headless 模式下不认 Windows 字体名，应写通用族名如system-ui, -apple-system, sans-serif
导出命令始终用右键菜单的 Markdown PDF: Export (pdf)，别用快捷键 Ctrl+Shift+P → Markdown PDF: Export —— 后者有时会忽略当前编辑器焦点，导出空文件。
最麻烦的其实是带 Mermaid 图表或复杂表格的文档，这类内容在 PDF 渲染中容易截断或错位，需要手动加 <div style="page-break-inside: avoid"> 包裹，或者导出后用 Acrobat 调整——这点很多人导出失败后才意识到。</div>
