如何使用VSCode将Markdown文档一键导出为PDF格式

如何使用VSCode将Markdown文档一键导出为PDF格式

想把VSCode里的Markdown笔记变成一份规整的PDF文件？这个需求很常见，但实现过程里藏着几个“坑”。下面就来拆解一下，如何绕过这些坑，顺利完成导出。

VSCode 本身不支持直接导出 PDF，必须依赖扩展

首先得明确一点：VSCode原生并没有“导出PDF”这个按钮。所有看似便捷的“一键导出”功能，背后都依赖于第三方扩展。目前，社区里最常用、维护也最活跃的扩展是 Markdown PDF（作者yzane）。它的工作原理很直观：调用 puppeteer 工具，在后台启动一个Chromium浏览器，将Markdown渲染成HTML页面，最后再把这个页面“打印”成PDF。所以，整个过程高度依赖本地的浏览器环境是否可用。

安装扩展只是第一步，关键在配置。Markdown PDF 默认会去系统的PATH环境变量里寻找 chromium 或 chrome 可执行文件。如果没找到，就会报出那个经典的 Failed to launch chrome 错误。这事儿在Windows和macOS上各有各的麻烦：Windows用户可能装了Chrome但没将其加入PATH；macOS用户则可能因为新版Chrome不再默认注册为命令行程序而遇到 Cannot find Chrome。

• 稳妥起见，建议先在终端里运行 which chromium 或 which google-chrome 命令，确认系统能找到浏览器。
• 如果命令没有输出，那就需要手动配置了。在VSCode设置里，找到 markdown-pdf.executablePath 项，直接指向你本地Chrome或Chromium的完整路径（例如macOS上可能是 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome）。
• 对于Linux用户，如果使用的是 chromium-browser 这个包，记得先用 sudo apt install chromium-browser 确保它已安装。

导出前必须保存 .md 文件，且不能是临时未命名文档

这是最容易踩坑的地方。Markdown PDF 扩展在工作时，需要根据Markdown文件的真实路径来生成临时的HTML和CSS文件。如果你当前编辑的标签页还叫 Untitled-1 这类临时名字，那么点击右键菜单里的 Markdown PDF: Export (pdf)，很大概率会静默失败——控制台甚至可能不报错，让你无从下手。

正确的操作顺序至关重要：务必先按 Ctrl+S（Windows/Linux）或 Cmd+S（macOS），将文件保存为一个实实在在的、带 .md 后缀的文件，然后再触发导出操作。成功的话，生成的PDF会直接放在Markdown文件的同级目录下，文件名也保持一致（比如 readme.md 会导出为 readme.pdf）。

• 另外要注意，如果Markdown文档里引用了相对路径的图片（比如 ![](assets/logo.png)），请确保这个路径是相对于当前 .md 文件位置有效的。
• 不支持从Markdown预览窗口直接导出，操作必须在编辑器的源代码窗口进行。
• 除了右键菜单，使用快捷键 Ctrl+Shift+P 调出命令面板，输入 Markdown PDF: Export (pdf) 来执行，有时会更稳定。

中文乱码和样式错乱？重点检查 font-family 和 CSS 注入

默认设置下导出的PDF，中文经常变成一堆小方块，这几乎是每个中文用户都会遇到的问题。根源在于，Puppeteer在渲染页面时，没有加载到合适的中文字体。扩展虽然提供了 markdown-pdf.fontFamily 这个配置项，但它只能影响部分内联样式，如果遇到主题CSS里硬编码了像 "Helvetica" 这样的西文字体，它也无能为力。

真正一劳永逸的解决方案，是通过自定义CSS来全局声明字体：

• 新建一个CSS文件，比如就叫 pdf.css，放在项目根目录下。文件内容核心就是强制指定中文字体族：

  body { font-family: "Noto Sans CJK SC", "Microsoft YaHei", sans-serif !important; }

• 接着，在VSCode设置中，配置 markdown-pdf.cssPath 项，指向你刚创建的 pdf.css 文件（填写绝对路径或相对于工作区的相对路径均可）。
• 这里有个关键细节：避免在CSS中使用 @import 在线导入Google Fonts等网络字体，因为Puppeteer是在离线环境下工作的，根本加载不了。
• 如果你为了追求完全自定义样式，将 markdown-pdf.includeDefaultStyles 设为了 false