当前位置：首页 > news >正文

VSCode 中 Markdown 转 PDF

news 2026/7/9 16:38:01

VSCode 中 Markdown 转 PDF 完全指南（含 Prince XML 丢失修复）

优雅地生成带书签的 PDF 文档，告别排版烦恼

引言

在日常写作、技术文档编写或笔记整理中，我们经常需要将 Markdown 文件导出为 PDF 格式。VSCode 凭借丰富的插件生态，成为许多人的首选编辑器。本文将详细介绍如何利用两款核心插件——Markdown Preview Enhanced和Markdown PDF，实现高质量的 PDF 导出，并重点解决一个常见但令人头疼的问题：Prince XML 丢失导致导出失败。

读完本文，您将能够：

一键生成带书签（目录层级）的 PDF
修复prince引擎缺失的错误
掌握两种 PDF 导出方式（Prince 与 Chrome）

必备插件

首先，在 VSCode 扩展商店中安装以下两款插件：

插件名称	作用
Markdown Preview Enhanced	提供强大的预览功能，支持多种导出格式（PDF、HTML、PNG 等），并支持 Prince 引擎生成带书签的 PDF
Markdown PDF	轻量级插件，基于 Chromium 内核直接转换，适合无特殊书签需求的快速导出

安装完成后，您会在.md文件右键菜单中看到Markdown Preview Enhanced: Open Preview to the Side以及Markdown PDF: Export (pdf)等选项。

常见问题：Prince XML 丢失

当您使用Markdown Preview Enhanced的PDF (Prince)导出功能时，可能会遇到如下错误提示：

prince: command not found

或

Failed to export PDF. Please install PrinceXML.

这是因为 MPE 插件依赖Prince引擎来生成带书签的 PDF，而该引擎并未随插件自动安装，需要您手动下载并配置环境变量。

修复步骤（详细图解）

第 1 步：下载 Prince

前往 Prince 官网下载对应操作系统的安装包：

官网地址：https://www.princexml.com/download/
选择适合您系统的版本（Windows / macOS / Linux）

💡 Windows 用户建议下载.msi安装包，一路默认安装即可。

第 2 步：配置环境变量（Windows 示例）

安装完成后，需要将 Prince 的bin目录添加到系统Path中，以便 VSCode 能够调用prince命令。

打开环境变量设置
- 右键点击“此电脑” → 属性 → 高级系统设置 → 高级 → 环境变量
编辑系统变量 Path
- 在“系统变量”区域找到Path，双击打开编辑窗口
新增 Prince 路径
- 点击“新建”，输入 Prince 的bin文件夹路径
- 默认路径：C:\Program Files (x86)\Prince\engine\bin
- 如果安装时修改了路径，请替换为您的实际路径
确认保存
- 依次点击“确定”关闭所有窗口

🍎 macOS / Linux 用户请编辑~/.bash_profile或~/.zshrc，添加：
exportPATH="/usr/local/prince/bin:$PATH"

第 3 步：验证环境变量

打开一个新的终端（CMD 或 PowerShell），输入：

prince--version

如果正确显示版本号，说明环境变量配置成功。

第 4 步：重启 VSCode

务必完全关闭并重新启动 VSCode，否则环境变量不会生效。

使用方法

方法一：Markdown Preview Enhanced（推荐，带书签）

在 VSCode 中打开您的.md文件
右键 → 选择“Markdown Preview Enhanced: Open Preview to the Side”（或使用快捷键Ctrl+K V）
在右侧预览窗口内右键单击→ 选择“Export”→“PDF (Prince)”

等待几秒钟，PDF 文件将自动保存在当前 Markdown 文件同目录下

✅优点：生成的 PDF 会自动包含章节目录书签，方便读者导航，适合长文档（如论文、手册）。

方法二：Markdown PDF（快速无书签）

打开.md文件
右键 → 选择“Markdown PDF: Export (pdf)”
同样会在同目录生成 PDF 文件

✅优点：无需额外配置，基于 Chrome 渲染，样式与预览基本一致
❌缺点：无书签，且对某些自定义 CSS 支持不如 MPE 灵活

常见问题与技巧

问题	解决方案
导出 PDF 中文乱码	在 Markdown 文件头添加`---`元数据，指定字体： `pdf_options: { "font": "Microsoft YaHei" }`
想要调整页面边距/尺寸	在 MPE 的预览界面右键 → “打开配置文件” → 修改`pdf`相关参数
Prince 导出速度慢	首次导出会下载额外字体，后续会变快；若仍慢，可改用 Chrome 方式
环境变量配置后仍无效	检查是否将路径添加到了“用户变量”而非“系统变量”；重启 VSCode必做