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

vscode本身不支持直接导出pdf，必须依赖扩展；最常用的是markdown pdf（yzane），它通过puppeteer调用chromium渲染html再转pdf，需确保浏览器可用、文件已保存、路径正确，并配置中文字体和css以避免乱码与样式错乱。

如何使用vscode将markdown文档一键导出为pdf格式

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

VSCode 原生没有 Export to PDF 功能，所有“一键导出”方案都基于第三方扩展实现。最常用、维护活跃且支持中文排版的是 Markdown PDF（作者：yzane）。它底层调用 puppeteer 启动 Chromium 渲染 HTML 再转 PDF，因此对本地是否有可用浏览器环境敏感。

安装后需注意：Markdown PDF 默认使用系统 PATH 中的 chromium 或 chrome，若未安装或路径异常，会报错 Failed to launch chrome。Windows 用户常见问题是装了 Chrome 但没加到 PATH；macOS 用户可能遇到 Cannot find Chrome，因新版 Chrome 不再默认注册为命令行可执行程序。

推荐先在终端运行 which chromium 或 which google-chrome 确认路径存在
若无输出，可手动配置 markdown-pdf.executablePath 指向本地 Chrome/Chromium 可执行文件（如 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome）
Linux 用户若用 chromium-browser 包，需确保已安装（sudo apt install chromium-browser）

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

Markdown PDF 扩展导出逻辑依赖文件路径生成临时 HTML 和 CSS，如果当前编辑的是 Untitled-1 这类无名标签页，点击右键菜单 Markdown PDF: Export (pdf) 会静默失败，控制台也不报错——这是最常被忽略的卡点。

正确操作顺序是：先按 Ctrl+S（Windows/Linux）或 Cmd+S（macOS）保存为带 .md 后缀的真实文件，再触发导出。扩展会将生成的 PDF 放在同目录下，文件名与 Markdown 同名（如 readme.md → readme.pdf）。

Markdown-UI DSL: Zero-Hallucination UI Generation

使用 Markdown-UI DSL 创建低保真文本线框图。

下载

导出时若 Markdown 中含相对图片路径（如 ![](assets/logo.png)），确保路径相对于当前 .md 文件位置有效
不支持从预览窗口（Preview）直接导出，必须在编辑器中打开源文件
快捷键 Ctrl+Shift+P → 输入 Markdown PDF: Export (pdf) 可快速调用，比右键更稳定

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

默认导出的 PDF 中文常显示为方块，根本原因是 Puppeteer 渲染时未加载中文字体。扩展提供 markdown-pdf.fontFamily 配置项，但仅影响内联样式，无法覆盖部分 CSS 规则中的硬编码字体（比如某些主题 CSS 强制设为 "Helvetica"）。

真正可靠的解法是通过自定义 CSS 注入全局字体声明：

新建一个 pdf.css 文件（如放在项目根目录），内容包含：

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

在 VSCode 设置中配置 markdown-pdf.cssPath 指向该文件（路径填绝对路径或相对于工作区的相对路径）
避免使用 @import 在 CSS 中引入 Google Fonts —— Puppeteer 离线环境下无法加载网络字体
若用 markdown-pdf.includeDefaultStyles 设为 false，需自行补全基础排版样式（如 h1, code, blockquote 的 margin/padding）

导出失败时看 Output 面板的 markdown-pdf 日志，不是 Problems 或 Terminal

VSCode 多个面板都会输出日志，但 Markdown PDF 的关键错误只出现在专用的 Output 面板里，且需手动切换通道：右下角状态栏点击 Output → 下拉选择 markdown-pdf。常见线索包括：

TimeoutError: waiting for function failed: timeout 30000ms exceeded：页面渲染超时，多因 CSS 过大、含远程资源或本地字体加载慢，可尝试增大 markdown-pdf.timeout（单位毫秒）
Error: ENOENT: no such file or directory, open '/xxx/xxx.md'：文件已被删除或移动，但编辑器仍保持打开状态
Failed to load resource: net::ERR_CONNECTION_REFUSED：Markdown 中引用了本地启动的 dev server 地址（如 http://localhost:3000/foo.png），Puppeteer 无法访问

PDF 导出本质是「用浏览器截图」，任何影响网页正常渲染的因素都会传导到最终结果。调试时不要只盯着 Markdown 写法，更要检查渲染链路上的字体、CSS、图片路径和网络可达性。