如果你长期用 VSCode 写 Markdown，预览.md文件大概是每天重复最多的高频动作之一。Ctrl+Shift+V按下去，右边出来渲染结果，这几乎是肌肉记忆。但很多人其实只停留在“能用”的阶段：图片裂了不知道怎么排查，数学公式一直显示源码，导出 PDF 时找不到入口。这篇就专门聊 VSCode 里预览 Markdown 这件事，从内置功能到扩展选型，再到我实际踩过的坑，一次性梳理清楚。适合刚接触 VSCode 的新手，也适合写技术文档、博客草稿、项目 README 的老手。
1. VSCode 预览 Markdown 的原理：你看到的并不是文件本身
1.1 从 .md 到预览页面的三步转化
VSCode 的“显示预览”不需要额外插件，本质上是把 Markdown 文本解析成 HTML，再用内嵌浏览器内核渲染成一个 WebView 页面。你可以简单理解成三步：解析器按 CommonMark 和 GitHub Flavored Markdown 的规则，把标题、列表、代码块识别出来；随后生成一个临时 HTML 文档；最后套一层 CSS 显示在预览面板。这也是为什么你改动.md内容，预览会立刻刷新，因为解析是实时进行的。
理解这一点对排查问题非常有用。比如图片不显示，多半不是 VSCode 坏了，而是生成的 HTML 里<img src>路径不对，解析器只是原样把路径塞进去，并不会替你修正。又比如你自定义了样式不生效，那要先问自己：CSS 有没有被正确加载进 preview 页面？这套“Markdown → HTML → CSS”的心智模型，能覆盖 80% 的预览问题。剩下的 20%，多半是扩展配置或路径编码问题。
1.2 为什么同一份 md，在不同地方预览长得不一样
不同工具用的解析器不完全相同。VSCode 内置预览在不少组件上遵循 GitHub Flavored Markdown，支持表格和任务列表；但扩展或在线平台可能有差异。另外一个更大的变数是 CSS：GitHub 的页面整体样式有专门的开源样式表，VSCode 内置预览有自己的一套默认主题，Typora、语雀、Notion 又各有各的观感。所以同一份.md换一个地方看，字间距、代码块颜色、标题大小都会变。这是正常现象，不是文件坏了。
实际协作时，我一般不追求“本地预览和线上完全一样”，而是盯住结构性差异：表格是否错位、任务列表勾选是否生效、代码高亮是否正常。样式上的微小差异，只要自定义 CSS 可控，通常不会造成问题。如果你真的要跟 GitHub 渲染结果保持一致，后面我会讲几种方案，核心思路就是统一 CSS。
1.3 内置预览的能力边界
VSCode 内置预览能处理常规语法：标题、列表、任务列表、表格、代码块、行内代码、引用、链接、图片，也支持代码高亮。但默认不支持数学公式（$x$会原样显示），不支持 Mermaid 等图表代码块，也没有一键导出 PDF 或 HTML。这些不是缺陷，而是一个编辑器“内置功能”的合理边界，也给扩展留下了空间。
所以你的需求一旦超出“看个排版”，就要考虑扩展。我见过有人一上来就装一堆扩展，其实根本不知道自己需要什么。更理性的做法是：先用内置预览把基础流程跑通，遇到具体瓶颈再按需加扩展。这样既能保持编辑器的轻量，也能减少扩展之间的冲突。
2. 实操基础：4 种打开预览的方式与几条高频快捷键
2.1 打开预览的几种姿势，对比一下
VSCode 里打开 Markdown 预览，至少有四种方式：
| 方式 | 操作 | 适用场景 |
|---|---|---|
| 快捷键 A | Ctrl+Shift+V（macOS 是Cmd+Shift+V） | 在当前编辑器组打开预览，快速看渲染结果 |
| 快捷键 B | Ctrl+K V（macOS 是Cmd+K V） | 在侧边打开预览，一边编辑一边看效果 |
| 命令面板 | Ctrl+Shift+P搜Markdown: Open Preview | 鼠标不便操作时，或者快捷键被占用时 |
| 右键菜单 | 编辑器右键 → 打开预览 | 仅偶尔预览一次，不想记快捷键的人 |
我个人用Ctrl+K V最多，因为它默认分屏，左侧编辑右侧预览，改动立刻可见。Ctrl+Shift+V会覆盖当前编辑区域，如果你只是快速确认一份文档的最终渲染效果，用它更干净。需要注意，不同键盘布局下组合键可能有差异，但命令面板里搜到的命令名是稳定的。
2.2 分栏布局与调整预览宽度
预览打开后，VSCode 顶部会出现“向右侧打开预览”之类的图标，已经打开的预览窗口也可以直接拖拽到不同编辑器分组。想调整左右比例，直接拖动中间分隔条就行。如果你的屏幕足够宽，我建议把编辑区放 60%，预览区 40%，这样写长文时眼睛不会频繁跳动。
预览区太窄时，段落会频繁换行，看起来非常难受。这时可以去设置里调"editor.wordWrap": "on"或"editor.wordWrapColumn": 100，保证源码也不会横向滚动。很多人在“预览里觉得排版乱”时，第一反应是去改 Markdown 内容，其实先检查一下窗口宽度和字体大小，问题往往立刻消失。
2.3 跟随光标、锁定预览与同步滚动
预览面板右上角有一个控制“跟随光标”的图标。开启后，当你滚动 Markdown 源码时，预览会自动滚动到对应位置；关闭后，两边独立滚动，方便审阅长文。还有一个“锁定预览”功能，当你点击另一个 Markdown 文件时，锁定中的预览不会跟着切换文件，适合同时对照多份文档。这个功能藏在预览面板右上角的更多操作菜单里，命令面板搜Markdown: Toggle Preview Lock也可以。
我写多文件教程时经常用锁定预览：左侧打开文件 A，右侧锁定预览展示文件 A 的渲染结果，然后再去左侧打开文件 B 做对比。这个组合很冷门，但实际效率提升非常明显。
3. 扩展方案选型：内置不够时怎么选
3.1 日常写作首选：内置预览 + Markdown All in One
如果你只是写技术文档、README、课程笔记，不需要额外安装重量级渲染器。Markdown All in One可以补全编辑体验：一键生成目录、列表缩进合并、加粗斜体快捷键、表格格式化等。它不改变预览本身，但会减少你手动调格式的时间，预览仍然保持内置，整体很轻。这个组合是我给大多数人的默认推荐。
同时建议装一个markdownlint，它会在你写出不规范语法时给黄色波浪线。预览不关心你语法规不规范，但 lint 会提醒你，比如表格前后缺空行、标题层级跳级、列表符号不统一等。这些提醒能提前发现很多渲染问题，比出了问题再排查高效得多。
3.2 重装武器：Markdown Preview Enhanced（MPE）
当需求升级为“要渲染数学公式、画流程图、导出 PDF”时，我推荐Markdown Preview Enhanced，简称 MPE。它的核心能力包括 KaTeX 数学公式、Mermaid 图表、自定义预览主题、导出 HTML/PDF/PNG 等。安装后在命令面板搜Markdown Preview Enhanced: Open Preview to the Side，就能得到和内置预览完全不同的渲染效果。
MPE 功能多，配置项也多，第一次打开可能觉得有点重。我的经验是：不要一上来就调高级参数，先用默认配置跑通，确认公式和代码块渲染正常；再按需打开markdown-preview-enhanced.enableScriptExecution等选项。很多人的 MPE 要么不生效，要么把预览搞得很慢，往往是因为提前开了太多开关。
3.3 想跟 GitHub 保持一致：样式扩展怎么选
写完 README 放到 Git 仓库后，发现本地预览和线上不一致，主要原因是样式差异。有两个方向：一是安装Markdown Preview GitHub Styling这类样式扩展，让内置预览直接套 GitHub 风格；二是在 settings.json 里用markdown.styles引入github-markdown-css。我更推荐第二种，因为不引入额外扩展，只加一个 CSS 文件，团队里想统一也容易。
markdown.styles接受本地路径和 URL，路径要写对。如果你只是在本地自用，URL 直接填 CDN 地址最省事；如果团队处于内网环境，推荐把 CSS 文件放到仓库里，通过相对路径引用。这样每个成员打开仓库时，预览样式就能保持一致。
3.4 扩展不是越多越好
我见过有人同时装五六个 Markdown 相关扩展，结果预览又慢又乱，而且功能互相覆盖。比如 Markdown All in One 和 MPE 的某些快捷键是重合的，同时开可能会有冲突。建议最小组合：内置预览处理日常，MPE 处理公式图表和导出，再加一个markdownlint检查语法，就足够覆盖绝大多数场景。
等真正需要特定能力时再按需加。装完新扩展后，立刻禁用其它预览类扩展，确认当前环境是干净的。我踩过最典型的坑：图片一直不显示，排查半天才发现是某个预览扩展的脚本注入把图片路径拦截了。先把扩展减到最少，问题往往不攻自破。
4. 实操案例：写一篇带图片、公式、表格的文档
4.1 先配置一下 settings.json
我以一份“要发到内部知识库的 Markdown 文档”为例，它包含图片、行内代码、代码块、表格和一个数学公式。下面是我推荐的 settings.json 片段，你可以直接放进用户设置或工作区设置：
{ "editor.wordWrap": "on", "editor.wordWrapColumn": 100, "markdown.preview.fontFamily": "-apple-system, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif", "markdown.preview.fontSize": 16, "markdown.preview.lineHeight": 1.8, "markdown.styles": ["./styles/custom-preview.css"] }解释一下几个关键项：editor.wordWrap让源码不横向滚动，markdown.preview.fontFamily换成含中文字体的排列，避免标点挤压；markdown.preview.fontSize和lineHeight直接决定阅读舒适度，我用 16px 和 1.8 倍行距写长文档很舒服；markdown.styles是内置预览的自定义 CSS 入口。注意markdown.styles的路径是相对工作区根目录的，如果放不对，它不会报错，只是静默不生效。
4.2 图片路径：最常见的崩坏点
Markdown 图片语法是，相对路径是相对当前.md文件所在目录。如果你写成images\demo.png，Windows 风格反斜杠在解析时容易出问题，建议一律用/。VSCode 预览支持../images/demo.png往上级目录找图片，也支持/images/demo.png这种以工作区根为基准的绝对根路径。
我强烈建议你把图片放进仓库内的images目录，提交到 Git，用相对路径引用。比如当前文件在docs/a.md，图片在仓库根目录的images下，就应该写。从 VSCode 文件管理器复制出来的路径往往是file:///C:/...这种绝对路径，写进文档后换台电脑就裂，只能临时看图，不适合作为交付文档。
4.3 数学公式与图表渲染：上 MPE
内置预览默认不渲染$...$公式，安装 MPE 后就能看到。MPE 默认使用 KaTeX，速度比 MathJax 快，适合长文档。你只需要在 Markdown 正文里写标准 LaTeX 行内公式或独立公式，MPE 预览页会自动渲染。假如你之前用其它工具写了很多$$公式，MPE 基本能直接兼容。
Mermaid 图表同理，在文档里写一个语言标记为mermaid的围栏代码块，MPE 会把内部的节点和箭头绘制成流程图。图表不显示时，先确认你打开的是 MPE 预览而不是内置预览，这两个入口在命令面板里长得非常像，一个带 Enhanced，一个不带。我第一次用 MPE 时就犯过这个错，折腾了半天以为配置写错了。
4.4 自定义预览样式：让表格和代码块更好看
内置预览默认样式比较朴素，表格没有边框，代码块背景不够明显。用markdown.styles指向一个 CSS 文件后，你可以随意改预览效果。我常用的custom-preview.css大概是这样的：
.markdown-body table { border-collapse: collapse; width: 100%; } .markdown-body th, .markdown-body td { border: 1px solid #d0d7de; padding: 6px 12px; } .markdown-body pre { background: #f6f8fa; border-radius: 6px; } .markdown-body img { max-width: 100%; }由于 VSCode 内置预览的 HTML 结构带有.markdown-body容器，很多 GitHub 风格的 CSS 可以复用。改完 CSS 后，预览不一定会实时刷新，有时需要重新打开预览页，或者执行Ctrl+Shift+P里的Reload Window。遇到改了没效果时，先确认 CSS 文件路径没写错，再考虑缓存问题。
4.5 把预览变成可交付物：导出 HTML / PDF
MPE 的预览页面右键菜单里带有导出功能，支持 HTML、PDF、PNG、JPEG 等格式。导出 PDF 通常需要本机有 Chrome 浏览器，或者安装额外的文档转换工具，具体依赖在扩展文档里写得很清楚。我建议在导出 PDF 之前，先完整滚动一遍预览，因为有些格式问题在 HTML 里不明显，一到 PDF 分页就露馅，比如表格被切成两半，代码块跨页留白。
如果你只是要发给别人快速阅读，导出 HTML 更省事，单文件携带也方便。Markdown All in One 的打印功能也能走系统打印对话框，选一个系统内建的 PDF 打印机，同样能输出 PDF。不同方式各有取舍，我的原则是：轻量分享用 HTML，正式归档用 PDF。
5. 常见问题与排查技巧实录
5.1 图片裂开，首先查路径，其次查权限
| 现象 | 大概率原因 | 处理方式 |
|---|---|---|
| 预览里图片显示为裂图 | 相对路径错误 | 检查![]()里的路径是否相对于当前 md 文件 |
| 图片路径看着正确但偶尔不显示 | 文件名含中文或空格 | 改用相对路径，必要时做 URL 编码 |
| 换电脑后图片全裂 | 用了file:///C:/...绝对路径 | 改成仓库内相对路径 |
| 文档在子目录，图片在另个目录 | 路径层级没算对 | 用../逐级往上找 |
| 公司内网图片加载慢或显示不出来 | 外链图片被限制 | 下载到本地 images 目录再引用 |
如果你还是定位不了，VSCode 预览面板里右键选择“检查”，打开开发者工具，在 Elements 面板里看<img>标签的实际src值。这一步直接揭示真相：路径有没有被解析错、有没有被扩展改写、文件是否存在。我靠这个办法排掉了九成以上的图片问题。
5.2 数学公式一直显示源码
我遇到的原因主要有三种：打开的是内置预览而不是 MPE 预览；公式语法有误，比如$数量不匹配；KaTeX 不认某些复杂的 LaTeX 命令。处理顺序建议这样：先用一个最简单的$E=mc^2$测试，确认渲染通路正常；再检查是不是打开了错误入口；最后排查公式是否来自其它工具导出的特殊宏包。
还有一个隐蔽的问题：有些 Markdown 解析器会把数学公式里的反斜杠转义吞掉。如果公式写在列表或表格里，更容易触发这种边界问题。我的建议是把公式单独成段，不要嵌在复杂结构里，能避免不少玄学错误。
5.3 表格显示和 GitHub 不一致
VSCode 内置预览和 GitHub 都遵循 GFM，对表格支持差不多，差异通常来自样式而不是解析。比如表格边框、单元格间距在不同 CSS 下观感不同。真正会影响结构的问题有两个：单元格里的|没有转义，或者表格前后缺少空行。如果本地预览表格乱了，先检查源文件是不是符合规范：表头下面必须有---|---分隔行，表格前后留空行。
GitHub 上正常、本地不正常，优先怀疑自定义 CSS 把表格挤压了。我常用.markdown-body table { width: 100% }，但加了table-layout: fixed后，长文本会被挤得很难看。如果你也用了类似属性，改回默认布局往往就好了。
5.4 预览卡顿、同步滚动失效
几千行的大 Markdown 文件会让预览明显变慢，因为每次按键都触发重新渲染。缓解办法是拆文件，把大文档按章节拆分，再用索引目录串起来。另一种常见卡顿源是内嵌超大 base64 图片，一个文件塞几十张图，预览当然扛不住。图片应该作为独立文件放进目录，不要为了“单文件发布”把图片编码进 Markdown。
同步滚动失效时，先点击预览区域再滚动试试。如果彻底失效，执行Reload Window基本能恢复。我还遇到过预览面板右上角的控制图标消失，那通常是因为当前面板不是预览面板，而是终端或源码管理视图，重新用快捷键打开一次预览即可。
5.5 扩展冲突与配置不生效
装了 MPE 之后，内置预览的快捷键可能被覆盖，或者命令面板里出现两个入口，这时先看输出面板有没有扩展报错。配置不生效时，我建议做一个最小复现：禁用其它 Markdown 扩展，只保留目标扩展；把自定义 CSS 改成非常显眼的效果，比如body { background: red !important; }，能立刻判断是文件没加载还是被其它样式覆盖。
用!important可以压过一部分默认样式，但长期来看还是要找到正确选择器。VSCode 内置预览的页面结构相对稳定，.markdown-body这个类就是最好的切入点。CSS 没有生效时，先确认路径是相对工作区根目录，而不是相对当前 md 文件，这是很多人放错位置的原因。
6. 最后把几个使用心得留给你
预览这个功能看起来简单，真把它用顺了，能省下不少来回折腾的时间。我在实际使用中最深的体会是：不要过度依赖预览，写作时思路比排版重要。Ctrl+K V用习惯之后，预览更像一个实时校对窗口，而不是最终效果展示，心态会轻松很多。
还有一个建议：如果你跟团队协作，可以把自定义 CSS 和推荐扩展写进仓库。VSCode 支持在.vscode/extensions.json里声明团队推荐扩展，新人打开仓库时，VSCode 会提示安装。把预览经验沉淀到仓库配置里，比在群里发一长串“你按这个这个设置”高效得多。
最后分享一个小技巧：当你不确定当前预览到底是内置还是 MPE 时，直接看预览面板的标题区域，MPE 的界面通常更丰富，右键菜单里会有导出相关选项；内置预览则相对朴素。这个细节能帮你少走很多弯路。
