VSCode预览分内置与插件两类,不更新、导出模糊、Mermaid不渲染的主因是解析逻辑与文件关联未对齐:需确认.md后缀、Markdown语言模式、安装Markdown Preview Enhanced插件并正确标注`mermaid代码块,导出PDF推荐用Chrome引擎配合style.less强制宽度。

VSCode 的预览功能分两类:一类是内置的 Markdown 实时预览,另一类是插件提供的增强能力(比如 Mermaid 图表、数学公式、自定义样式)。默认开箱即用,但多数人卡在“为什么预览不更新”“导出 PDF 模糊”“Mermaid 不渲染”这类问题上——根本原因不是没装插件,而是没对齐解析逻辑和文件关联。
Markdown 预览打不开?检查文件后缀和语言模式
VSCode 只对 .md 文件自动启用原生预览。如果你用的是 .markdown 或其他后缀,即使内容是标准 Markdown,也不会触发预览。
- 右键编辑器标签 → “Change Language Mode”,手动选
Markdown - 或在
settings.json中加配置:"files.associations": { "*.markdown": "markdown", "*.mdx": "markdown" } - 验证是否生效:打开一个
.md文件,按Ctrl+Shift+V,如果弹出空白页,说明语言模式未识别成功
预览不实时更新?别只靠保存触发
VSCode 原生预览默认是“保存后刷新”,不是“键入即刷新”。你改了一行文字,不按 Ctrl+S 就看不到变化。这不是 bug,是设计选择——避免高频重绘拖慢编辑器。
- 想开启自动更新:安装扩展
Markdown Preview Enhanced,它支持 Typora 风格的“所见即所得”滚动同步 - 或改用
vscode-mermaid-preview插件处理含 Mermaid 的文档,它对.mmd文件强制监听变更,无需保存也能预览图表 - 注意冲突:同时启用多个 Markdown 预览插件可能导致右键菜单混乱,建议禁用原生预览(设
"markdown.preview.doubleClickToSwitchToEditor": false)再启用增强版
导出 PDF 清晰度低?根源在 CSS 渲染链
VSCode 本身不导出 PDF,依赖插件如 Markdown PDF。它本质是把预览 HTML 转成 PDF,所以清晰度取决于三件事:字体嵌入、图片分辨率、CSS 中的 zoom 或 transform 缩放。
- 导出前先在预览页按
Ctrl+P→ 输入 “Toggle Developer Tools”,检查控制台有没有CORS报错(本地图片路径没加file://协议会导致图片丢失) - 在
settings.json中加配置:"markdown-pdf.displayHeaderFooter": true和"markdown-pdf.scale": 1.2提升输出 DPI - 更稳的做法:用
markdown-preview-enhanced导出为 HTML,再用浏览器“打印 → 保存为 PDF”,能完全控制页边距、字体和背景
Mermaid 图表不显示?重点看文件扩展名和语法块包裹
vscode-mermaid-preview 插件只认 .mmd 或 .mermaid 后缀的独立文件,不解析 Markdown 内嵌的 ```mermaid``` 代码块——那是 Markdown Preview Enhanced 或 Markdown All in One 的职责。
- 新建文件 → 保存为
flow.mmd→ 输入graph TD; A-->B;→ 按Ctrl+Shift+V即可预览 - 如果坚持在
.md里写 Mermaid,请卸载vscode-mermaid-preview,改用Markdown Preview Enhanced,并确保代码块标记严格为```mermaid(不能多空格、不能写成```mermaid-js) - 常见报错
Parse error on line 1:多半是缩进不一致或用了中文标点,Mermaid 对空格和换行极其敏感
最常被忽略的一点:VSCode 的预览是基于当前工作区根目录解析相对路径的。图片、CSS、Mermaid 引用的外部主题,路径写错一格,预览就静默失败——它不会报错,只会留白。调试时先确认预览窗口地址栏是不是以 vscode-resource: 开头,如果不是,说明压根没走 VSCode 的资源代理机制。











