VSCode怎么运行Markdown预览 VSCode查看MD文档效果方法

VSCode 的 Markdown 预览功能，其实一直是自带的基础能力，无需额外安装插件就能用。很多新用户打开一个 .md 文件，下意识按了 Ctrl+Shift+V 发现没反应，第一反应往往是“是不是哪里坏了”。其实不然，它只是默认不主动弹出预览窗口，也不会实时刷新——这套逻辑从设计之初就这脾气，没变过。

Ctrl+Shift+V 没反应？先排查这四处

快捷键不响应是最常见的误报场景，但问题往往不在预览功能本身，而是出在周围几个配置的“默契度”上。

• 配置项被关掉了：在设置里搜索 markdown.preview.enabled，确认它的值是 true。如果被人为改成 false，无论怎么按快捷键都不会有任何反应。
• 文件类型没被识别：右下角状态栏要显示“Markdown”才算数。如果显示成了“Plain Text”或其他格式，点一下，手动切换到 Markdown。另外，文件后缀必须是 .md 或 .markdown——单纯改成 .txt 或者干脆没后缀，VSCode 不会把它当 Markdown 处理。
• 快捷键被插件劫持了：Vim、Emacs 等键盘映射插件经常吞掉 Ctrl+Shift+V，因为它在那些模式下原本就有别的含义。临时禁用这类插件再试一次，就能判断是否冲突。
• 在错误的位置按了快捷键：这个快捷键只对当前打开的编辑器标签页生效。如果是在侧边栏文件列表上点的文件，然后直接在文件树上按快捷键，当然不会有预览弹出来——得先打开文件再说。

预览内容不更新？九成原因出在保存

VSCode 的预览机制比较特别：它读取的是磁盘上已保存的文件内容，而不是编辑器中未保存的缓冲区。也就是说，改完内容没按 Ctrl+S，预览窗口根本不会知道你动过什么。

• markdown.preview.autoRefresh 虽然默认是 true，但它只对“已保存”的文件生效。不改动保存，自动刷新就是个摆设。
• 想要接近“边写边看”的效果，最稳妥的办法是开启自动保存：把 files.autoSa ve 设为 onFocusChange 或 afterDelay。这样每次切换标签页或间隔一段时间，内容就会自动写入磁盘，预览随之刷新。
• 预览窗口右上角那个 ↻ 刷新按钮，很多人以为是“重载预览内容”用的——实际上它只重新载入 HTML 渲染，不会去磁盘重读文件内容。如果文件本身没保存，点多少次都没用。
• 有时候第三方插件（比如 Markdown Preview Enhanced）会接管刷新逻辑，导致原生预览行为异常。排查时建议先禁用所有第三方 Markdown 相关插件，看看能否恢复。

数学公式、Mermaid 图表不出来？得手动开开关

原生预览默认是“保守派”，不是不支持扩展语法，而是把它们默认关掉了。你需要主动到设置里打开对应的开关。

• LaTeX 公式：设置 markdown.math.enabled 为 true。文档中用 $$...$$ 或 \(...\) 包裹公式。需要注意的是，$...$ 这种行内写法在原生预览中是不支持的。
• Mermaid 图表：设置 markdown.mermaid.enabled 为 true。代码块必须声明语言为 mermaid，例如：

  graph LR
  A -> B

• 脚本和内联样式被拦截：检查 markdown.preview.security，如果它是 strict，那么脚本和内联样式都会被拦截。Mermaid 和 KaTeX 的正确渲染需要这部分权限，所以最好把 markdown.preview.enableScripts 也设为 true。
• 中文标题点击不跳转：原生预览在中文标题的锚点生成上兼容性确实差一些。安装 Markdown All in One 插件，并启用 githubCompatibilityMode，能有效解决这个问题。

图片路径错、导出失败？根源都在路径规则

VSCode 对路径解析非常“较真”，一个点标错就可能导致白屏或图片丢失。

• 本地图片引用路径：它是相对于当前 .md 文件所在目录的。假设文件在 docs/readme.md，图片在 docs/img/logo.png，那就应该写 ![logo](./img/logo.png)，而不是 ./src/img/logo.png。
• 自定义 CSS：通过 markdown.preview.styles 填写样式文件路径时，它是相对于工作区根目录的。比如 ["./styles/md.css"]。路径写错了不会报错，但预览窗口就会一片空白。
• 导出 PDF 或 HTML：这不在 VSCode 原生预览的功能范围内。如果需要导出，必须借助 Markdown Preview Enhanced 或 Markdown PDF 这类插件。值得注意的是，Markdown PDF 在 Linux 上经常因为缺少 libxss1 等系统包而报 Failed to launch browser 错误，这一点需要提前留意。
• 深色主题下文字发灰：别自己去改 CSS 了。直接在 workbench.colorCustomizations 里调整 markdownPreview.foreground 的颜色值即可。

话说回来，最容易被忽略的一个点其实是：预览呈现的样式，是否真正代表了你最终要发布的效果？原生预览能保证结构正确，GitHub 风格、表格对齐、任务列表渲染都还不错。但自定义 class、Front Matter、复杂的 Mermaid 子图、PDF 中文字体——这些全得靠扩展来补。而且每个扩展的路径规则、启用开关、冲突逻辑都不一样。所以，遇到问题最有效的排查方法就是：一步一验证，关掉所有插件，从原生能力开始测起。