Markdown PDF插件导出失败主因是wkhtmltopdf未安装或配置不当；需手动安装对应平台二进制包并确保命令行可用，同时配置中文字体CSS、启用HTML导出选项，并对大文档优化wkhtmltopdf参数或改用命令行直导。
Markdown PDF 插件导出失败：找不到 wkhtmltopdf
VSCode 的 Markdown PDF 插件默认依赖系统级命令行工具 wkhtmltopdf，不是纯前端方案。装完插件直接点导出却弹错：Cannot find wkhtmltopdf——这是最常见卡点。
- 必须手动下载并安装
wkhtmltopdf（官网提供各平台二进制包），不能靠 npm 或插件自动带 - Windows 用户要选
installer版（如wkhtmltopdf-0.12.6-installer.exe），别下 zip 包后忘了配环境变量 - macOS 用
brew install wkhtmltopdf最稳；M1/M2 芯片注意选 arm64 架构版本，否则运行时报Bad CPU type - Linux 用户确认
wkhtmltopdf --version能在终端执行成功，否则插件完全无法调用
导出样式乱、中文不显示：CSS 和字体配置不到位
默认导出的 PDF 经常出现中文字体缺失（显示为方块）、代码块排版错位、标题缩进异常——问题不在 Markdown 写法，而在渲染链路里字体和 CSS 没兜住。
- 插件会读取工作区根目录下的
markdown-pdf.css文件（需手动创建），优先级高于内置样式 - 中文必须显式指定字体族，例如在 CSS 中加：
body { font-family: "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei", sans-serif; } - 避免用
@import引入网络字体（PDF 导出时无法加载），所有字体文件建议本地化或用系统已安装字体 - 若用 VSCode Remote-SSH，
wkhtmltopdf实际运行在远端服务器，远端也得装好中文字体（如 Ubuntu 装fonts-wqy-zenhei）
导出 HTML 比 PDF 更快更可控，但默认不生成
Markdown PDF 插件主攻 PDF，HTML 是副产物，需要手动开启开关，否则右键菜单里根本看不到「Export to HTML」选项。
- 打开 VSCode 设置（
Cmd+,/Ctrl+,），搜markdown-pdf.convertOnSave，把它关掉——否则每次保存都强制 PDF，干扰调试 - 在设置里搜
markdown-pdf.type，改成["html"]（注意是数组格式，不是字符串） - 改完后右键 Markdown 文件，菜单会出现「Export to HTML」；生成的 HTML 可直接浏览器打开，也方便后续用
pandoc或其他工具再加工 - HTML 导出不依赖
wkhtmltopdf，适合快速预览样式或集成到 CI 流程中
大文档导出卡死或内存溢出：不是插件问题，是 wkhtmltopdf 的限制
超过 500 行、含大量表格/数学公式/嵌入图片的 Markdown，导出 PDF 时可能无响应或报 Exit with code -9——这通常是系统 kill 掉了超内存的 wkhtmltopdf 进程。
立即学习“前端免费学习笔记（深入）”；
- 先试简化内容：删掉图片、注释掉
$$...$$公式块，看是否能导出，确认是否真由内容复杂度引发 - 插件本身不提供
wkhtmltopdf参数透传，但你可以改插件源码：找到node_modules/markdown-pdf/index.js，在args数组里加--no-stop-slow-scripts和--javascript-delay 5000 - 更稳妥的替代方案是绕过插件，用命令行直跑：
wkhtmltopdf --enable-local-file-access input.html output.pdf，配合marked或md2html先转 HTML - 长期写技术文档，建议把导出逻辑抽成脚本，而不是依赖 GUI 插件点击
真正麻烦的从来不是点哪个按钮，而是你不知道 wkhtmltopdf 在哪一层悄悄失败，以及它对字体、路径、内存的隐性要求。
