如何在VSCode中使用Markdown插件实现实时预览及导出PDF

如何在VSCode中使用Markdown插件实现实时预览及导出PDF

Markdown预览窗口打不开或不自动刷新

VSCode内置的Markdown实时预览功能，用起来本该很顺手，但不少朋友都卡在了第一步：按下Ctrl+Shift+V（Windows/Linux）或Cmd+Shift+V（macOS），预览窗口却毫无反应。别急着怀疑插件，先检查两个最基础的条件：第一，确认你的文件后缀是.md或.markdown；第二，看看编辑器右上角有没有那个表示“未保存”的圆点——文件必须保存后，VSCode才会把它识别为Markdown文档。

如果这两点都满足了，预览还是出不来，那问题很可能出在扩展上。去扩展视图里搜一下，确保Markdown Language Features和Markdown Preview这两个内置扩展是启用状态。有时候，第三方插件也会“抢活儿”。比如你装了Markdown All in One，它一般会兼容原生预览，影响不大。但如果你用的是功能更强大的Markdown Preview Enhanced，情况就不同了：它会直接接管Ctrl+Shift+V这个快捷键。这时候，要么你习惯用它的专属快捷键Ctrl+K V来呼出预览，要么就得考虑卸载它，把预览权交还给VSCode原生功能。

导出PDF时中文乱码或排版错乱

想把写好的Markdown导出成PDF？VSCode本身可没这个本事，必须借助插件。过去很多人会用Markdown PDF（作者yzane），但这里得提个醒：这个插件底层依赖的phantomjs渲染引擎已经停止维护，对中文的支持非常糟糕，导出后动不动就是乱码方框、字体缺失或者排版错位，简直让人头疼。

那有没有更靠谱的方案？当然有。目前社区里更推荐Markdown Preview Enhanced（作者shd101wyy）。它改用Puppeteer（基于Chromium内核）来渲染，对中文和现代CSS的支持要稳定得多。使用方法也简单：安装插件后，在编辑器里右键，选择Export to PDF就行。不过，第一次导出时会自动下载一个约150MB的Chromium，需要保持网络通畅，稍等片刻。

为了确保万无一失，建议在文档开头通过YAML front matter指定一下字体。比如加上：

---
stylesheet: ./style.css
---

然后在同一目录下放一个style.css文件，里面写上body { font-family: "Microsoft YaHei", sans-serif; }这样的规则。如果导出结果是一片空白，先别慌，这通常是因为文档里包含了未闭合的HTML标签，或者MathJax数学公式的语法有错误。可以尝试暂时删掉有问题的部分，先导出一版看看。

自定义PDF样式时CSS不生效

想给导出的PDF换个漂亮的样式？Markdown Preview Enhanced支持通过custom.css文件注入自定义样式，但路径和用法上有些门道，踩坑的人不少。

首先，这个CSS文件必须放在VSCode当前工作区的根目录下，并且名字必须叫custom.css，改成其他名字插件是认不出来的。其次，这个文件里的样式只对最终导出的PDF生效，并不会影响你在编辑器里的实时预览窗口。如果想调整预览窗口的样式，需要另外配置previewTheme。

还有几个技术细节需要注意：避免使用@import语句来引入外部CSS，因为在Puppeteer的导出阶段，这个语法可能不被支持。为了防止样式被内置规则覆盖，关键的选择器后面可以加上!important，比如h1 { font-size: 28px !important; }。如果想设置页眉页脚，得用@page规则，而且它只在导出PDF时才起作用，可以这样写：

@page {
  @top-center {
    content: "My Doc";
  }
}

导出PDF后代码块字体太小或无高亮

导出PDF后，发现里面的代码块字体小得可怜，或者完全没有语法高亮？这其实不是Markdown的错，问题出在渲染环节。

默认情况下，导出的代码块虽然使用了等宽字体，但往往缺少高亮，字号也偏小。解决之道，在于正确配置Puppeteer的渲染行为。第一步，请确保你在文档中为代码块正确标注了语言，比如用```python，而不是光秃秃的```，这样插件才能知道该应用哪种高亮方案。

接着，在custom.css文件里，可以强制调整代码块的样式：

pre code {
  font-size: 14px !important;
  line-height: 1.5 !important;
}

如果还是没有高亮，就去检查一下插件的设置。确保markdown-preview-enhanced.enableExtendedSyntax这个选项是打开的（设为true），并且markdown-preview-enhanced.codeBlockTheme选择了一个有效的主题，比如github-dark。这里有个小陷阱：有些主题（像atom-light）在PDF里的颜色对比度很低，乍一看好像没高亮，其实只是颜色太浅。换成vs2015或a11y-dark这类对比度高的主题，效果就立马清晰了。

说到底，导出PDF本质上就是给渲染好的网页拍一张“快照”。整个过程牵涉到样式加载、字体渲染、语法高亮引擎等一系列环节，任何一个环节掉了链子，最终效果都会大打折扣。所以，当PDF不符合预期时，先别急着重装插件，不妨打开输出面板，看看Markdown Preview Enhanced的日志里有没有Puppeteer相关的报错信息，那往往是问题的根源。

立即进入“夸克AI手把手教你，操作像呼吸一样简单！☜☜☜☜☜点击进入”；