做技术写作这两年，我发现自己几乎每天都要跟 Markdown 打交道。写文档、记笔记、发博客、整理接口说明，甚至做项目周报，最后都会落到那一堆#、-、**符号上。可越是常用的东西，越容易在细节上翻车——你在 VS Code 里写得好好的 Markdown，换台电脑打开或者导出成 PDF 发给同事，排版全乱了，图片也不见了，表格对不齐，换行跟没换一样。这时候你才会意识到，真正需要搞清楚的不是“Markdown 怎么写”，而是“Markdown 怎么编译、怎么渲染、怎么导出”。这一整套链路，就是 VS Code 配置 Markdown 编译器的核心。
这篇文章我打算把整个配置过程掰开揉碎来讲：从要不要装编辑器、哪些插件真正有用、图片路径怎么规划，到导出 HTML/PDF 时常见的一堆幺蛾子，全部过一遍。适合正在用 VS Code 写文档但觉得预览效果不理想的人，也适合想把自己的 Markdown 工作流彻底理顺的开发者。
1. 为什么 VS Code 能成为 Markdown 的“编译器”平台
1.1 先搞清楚：编辑器、编译器、渲染器分别干了什么
很多人第一次搜“VS Code 配置 Markdown 编译器”时，脑子里想的是“装个插件然后让 Markdown 变成 HTML”，但这条路里其实藏着三个完全不同的角色。
编辑器负责的是你打字时的体验。语法高亮、自动补全、快捷键、文件树，这些是 VS Code 本身干的事。它只负责让你写起来舒服，不负责最终效果。
编译器干的是“格式转换”的活，严格说 Markdown 不是一个编译型语言，所谓的编译器是把 Markdown 源文件按语法规则解析成另一种结构，最常见的目标是 HTML。这个过程里包括标题层级识别、列表嵌套判断、代码块抽取、表格解析，一件件都有严格的规则。
渲染器则是把编译产物画到你屏幕上。VS Code 内置预览本质上就是“把 Markdown 编译成 HTML，然后在浏览器内核里渲染”。虽然这一整套跑起来就是一瞬间的事，但当你配置出问题时，只有搞清楚是语法解析错了、还是 CSS 没加载、还是浏览器内核版本太旧，才不至于手足无措。
我特别喜欢的一个类比是：Markdown 源文件就像菜谱的原料，编译器是厨师，渲染器是摆盘。VS Code 提供了厨房，插件是你请的帮厨。很多人以为“买了好厨房就能吃到好菜”，其实关键在帮厨怎么干活。
1.2 为什么不用 Typora、语雀，而是偏偏留在 VS Code
我不否认 Typora 那种 WYSIWYG（所见即所得）体验很好，也不用遮遮掩掩地说自己从来不用它——我在自己电脑上也装了，偶尔快速看个 md 文件确实方便。但你要让我把“正经写作和文档管理”完全交给它，我心里没底。
原因有几个。首先是“一套工具覆盖多种需求”的复用价值。我已经在用 VS Code 写代码了，如果文档写作也在同一个工具里完成，切换成本几乎为零。其次是 Markdown 文件本质上是纯文本，而我写代码时一直在用 Git 做版本管理，放在 VS Code 里可以顺理成章地做同一套版本管理。第三是 VS Code 的插件生态远比其他 Markdown 编辑器丰富，这意味着我可以按需定制——今天导出 PDF，明天加 Mermaid 图表，后天直接发布到博客平台，都有现成方案。
语雀这类在线文档的问题恰恰相反——它帮你做了太多事情，以至于数据被锁在平台里。Markdown 文件是开放格式，但语雀同步出来的内容未必 100% 保留原格式。VS Code 不解决“你用什么云服务”的问题，它保证“你手里永远有一个干净的、属于你自己的源文件”。
提示：我见过不少团队文档从语雀、Notion 迁回 Git 仓库管理的案例，核心原因就是“格式太封闭”。VS Code + Markdown 的组合天然更接近开发团队的工作流。
1.3 我的整体配置思路：源文件、预览、导出三层分离
配置之前先明确目标。我给自己定的原则是三层分离：源文件层、预览层、导出层。
源文件层是最基础的，只负责存放.md文件和图片资源。这里的关键是路径规划——文档放哪、图片放哪、命名规则是什么，直接决定后面导出时的成功率。
预览层解决的是“写得对不对”的问题。VS Code 内置预览加几个增强插件就够了，重点是把即时渲染做到位，让我在写的过程中就能看到标题层级对不对、代码块有没有识别、表格有没有对齐。
导出层解决的是“怎么交付”的问题。同一个 Markdown 文件，可能今天要发公众号，明天要做成 PDF 给客户，后天要转到 Word 里跟同事协同。每一类出口的需求都不一样，但源头只有一个.md文件，这就避免了“改一版内容要改三个文件”的灾难。
配置的本质，就是在每一层选好工具，然后把它们串起来。接下来的内容，就是围绕这三层逐步展开。
2. 环境准备：从安装 VS Code 到识别出第一个 Markdown 文件
2.1 安装 VS Code 时容易被跳过的三个选项
很多人在安装 VS Code 时一路 Next，最后装完发现打不开终端里的code .命令。其实安装向导里就有两个选项跟这个问题直接相关：“添加到 PATH”和“添加到右键菜单”。我建议这两个一定要勾上，前者让你能在任何终端里用code打开项目，后者让你在文件管理器里右键就能用 VS Code 打开目录，省去打开软件后再一层层找路径的麻烦。
另一个选项是“设置为 .md 和 .txt 文件的默认编辑器”，这个看个人习惯。如果你主要用它写文档，勾上也行；但我的经验是不要急着勾，先体验一段时间再决定，避免把 txt 的默认打开方式也改掉造成困扰。
装完以后，打开命令行验证一下：
code --version能输出版本号就说明安装正常。这一步排查了很多“为什么我双击 .md 文件打不开”的问题——不是 VS Code 没装好，而是文件关联和 PATH 没配对。
2.2 首次打开 Markdown 文件：认识内置预览
VS Code 对 Markdown 的支持是开箱即用的，不需要装任何插件就能看基础效果。新建一个test.md，写几行标题和列表，然后按：
Ctrl+Shift+V：在当前标签页打开预览Ctrl+K V（先按 Ctrl+K，再按 V）：在右侧分栏打开预览
右侧分栏模式我强烈建议养成习惯——左边写源文件，右边看渲染结果，实时对照，效率是最高的。
内置预览用的是 VS Code 自带的 Markdown 渲染器，支持标准语法、任务列表、代码高亮，对绝大多数日常写作足够了。它的局限主要体现在三方面：不能自定义 CSS 样式、不支持 Mermaid 等扩展图表、没有一键导出功能。
这就是为什么接下来的插件配置才是“编译器”工作流的重头戏。内置预览让你能用，插件配置让你用得好。
另外如果你习惯中文界面，直接去扩展市场搜“Chinese (Simplified) Language Pack”，这是微软官方中文语言包，安装后右下角会提示重启，重启就变中文了。不装也不影响使用，但装了对新手友好很多。
2.3 回应一个高频误解：VS Code 是编译器吗
在搜索关键词里有个很有意思的说法：“编译器未包含main类型”。这其实是 C/C++ 新手在 VS Code 里编译代码时遇到的报错，但它反映了一个很普遍的误解：把 VS Code 本身当成了编译器。
VS Code 本质上是一个编辑器，它自己不会把任何语言编译成机器码。C/C++ 代码能编译，是因为你装了 MinGW、MSVC 或 GCC，VS Code 只是负责调用这些外部工具并把结果展示给你。Markdown 的“编译”同理——它本身不自带将 Markdown 转成 PDF 的能力，而是通过插件、Pandoc 这类外部组件完成转换。
明白了这一点，你就不会被“VS Code 里配置编译器”这个表述带偏。你要做的不是找到某个开关让 VS Code 内置一个 Markdown 编译器，而是把正确的工具链装配到 VS Code 里。这就像组装电脑，VS Code 是机箱，CPU、内存、显卡得你自己配。
3. 插件与配置：把 Markdown 编译链路补齐
3.1 Markdown All in One：写作体验的加速器
这个插件之所以叫“All in One”，是因为它把 Markdown 写作里最常用的几个能力打包了：格式化表格、目录生成、快捷键、自动编号列表。
我最常用的是快捷键。
| 操作 | 快捷键（Windows/Linux） | macOS |
|---|---|---|
| 加粗 | Ctrl+B | Cmd+B |
| 斜体 | Ctrl+I | Cmd+I |
| 标题升降级 | Ctrl+Shift+]或Ctrl+Shift+[ | Cmd+Shift+]或Cmd+Shift+[ |
| 任务列表 | Option+C | Option+C |
| 生成目录 | Ctrl+Shift+P输入Add Table of Contents | 同上 |
标题升降级这个功能我天天用。写长文档时经常写着写着发现层级不对，以前要一个个改#的数量，现在光标停留在标题行，按快捷键直接升一级或降一级，效率提升非常明显。
另一个杀器是表格格式化。手写 Markdown 表格时总有人对着竖线对齐较劲，这个插件提供一个命令：Markdown All in One: Format Document，一键把表格列宽对齐，看起来整洁很多。这也为后面“把表格转成 Excel”打了基础，因为工整的表格复制到 Excel 里才有可能被正确分列识别。
目录生成同样值得一提。插件根据你文档里的#标题层级自动生成可跳转的目录，对长文档强烈建议加上。发布到博客、公众号后读者也能靠目录快速定位内容。
3.2 Markdown Preview Enhanced：真正的“编译器”核心
如果只允许我装一个 Markdown 相关插件，我会选 Markdown Preview Enhanced，以下简称 MPE。它的定位不是单纯预览，而是一套完整的“Markdown 编译工具链”。
安装后打开方式变了：
- 按
Ctrl+Shift+P输入Markdown Preview Enhanced: Open Preview - 或者直接右键然后选择
MPE: Open Preview
MPE 最大的价值在于它的渲染基于 markdown-it 解析器，比 VS Code 内置的渲染器更完整地支持 GFM 扩展语法和自定义容器，并且同步支持 MathJax 数学公式、Mermaid 图表、PlantUML 时序图、甚至 VEGA 图表。
举个例子，你想在文档里插入一个简单的流程图，只需要写 fenced code block：
```mermaid graph TD A[开始] --> B{判断} B -->|是| C[执行] B -->|否| D[退出] ```在 MPE 预览里它会被渲染成真正的图表，而在普通编辑器里你只能看到代码块。这个差距就是“能用”和“好用”之间的区别。
MPE 还支持自定义 CSS。它会自动读取项目根目录下的preview.css或通过设置指定路径，你可以在里面覆写字体、颜色、间距、代码块样式。我的做法是维护了三个主题文件：一个亮色主题用于白天写作，一个暗色主题用于夜班，一个专用于导出 PDF 的打印样式。
3.3 补充几个实战中出现率高的插件
除了上面两个主力，还有几个插件它们很少被当作“Markdown 编译器”相关插件推荐，但实际使用中能解决非常具体的问题。
第一个是Excel to Markdown table。它能把 Excel 表格直接转换成 Markdown 表格粘贴到文档里，也能反向把 Markdown 表格转回 Excel。运营同事做数据汇报时经常用到，很多人不知道 VS Code 插件市场里有这种东西，其实装了以后选中所要的区域复制，再到编辑器里用命令粘贴即可，比手动对齐省太多时间。
第二个是markdownlint。它不负责渲染，但会以波浪线提示语法问题——比如标题层级跳了、列表符号混用了、行尾多了空格。对长篇文档来说，这种“静默监管”非常值钱，它可以避免你写了上万字最后导出时才发现结构有问题。
第三个是Todo Tree。很多人用 Markdown 写个人任务清单，Todo Tree会在侧边栏把所有- [ ]和- [x]汇总成任务列表，点击直接跳转到对应的行。这个体验比在文档里翻靠谱多了。
注意：这些插件不是装得越多越好。我见过有人一口气装二十个 Markdown 相关插件，结果预览延迟明显、命令面板里搜一个功能出现五个重复项。我的建议是先从核心三个开始用，遇到具体痛点再补。
4. 实操记录：把一篇带图片、表格、图表的文章完整编译成可发布文件
4.1 目录结构和图片路径怎么规划，从源头避免 404
图片路径问题在 Markdown 使用频率排行榜里绝对排前三。一个很典型的场景：文档在自己电脑上预览正常，发给别人后图片全挂。大多数情况是路径写错了。
Markdown 图片引用有三种常见写法，我列个表格说明。
| 写法 | 含义 | 适用场景 |
|---|---|---|
 | 相对当前文档的路径 | 文档移动时相对位置不变即可 |
 | 网站根路径 | 部署到 Web 服务器时用 |
 | 绝对 URL | 图床或线上资源 |
我的建议：本地写作一律用相对路径。同时把整个文档项目按下面的结构组织：
project/ ├── docs/ # 存放 Markdown 文件 ├── assets/ │ └── images/ # 存放图片 └── README.md在文档中引用图片时写，这样无论项目目录怎么整体拷贝，只要相对结构不变图片就能正常显示。
还有两点细节容易被忽视：文件名不要出现中文和空格。这在 Windows 本地没问题，但一旦部署到 Linux 服务器或 GitHub Pages 上，URL 编码就会搞出一堆 %20 之类的东西，非常烦人。图片格式建议统一用 PNG 或 WebP，避免混合 jpg、gif 导致样式不一致。
4.2 换行问题：为什么预览正常但发布后不见了
“Markdown 换行”在热搜词里出现频率极高，可见踩坑的人真不少。Markdown 里换行分为软换行和硬换行：
- 输入一个回车，在渲染结果里通常只是加了个空格，不会真正换行。这叫软换行。
- 在行尾输入两个空格再回车，或者空出一整行再写下一段，才会产生真正的换行。这叫硬换行。
许多中文写作平台（比如公众号编辑器）对换行的处理和标准 Markdown 不同，你本地预览看着正常的段落，粘贴过去就挤成一团，就是因为软换行在目标平台没有被解析成换行。
我的习惯是：段落之间用空行分隔，保证“段落感”。如果确实需要在一段文字内强制换行，比如写地址、写诗词，就在行尾加两个空格再回车。
另外有个隐藏坑：VS Code 的默认行为会在保存时自动去除行尾多余空格。如果你用“两个空格 + 回车”作为硬换行，保存后空格被清掉，硬换行就变成了软换行。解决办法是在设置里搜索files.trimTrailingWhitespace，把该项设置为false，或者只在 Markdown 文件中禁用这个行为。
4.3 导出 HTML 与 PDF 的完整操作流程
MPE 的导出功能是整个工作流里最核心的一环。右键预览窗口，选择“Export”就会展开一大堆格式：HTML、PDF、PNG、JPEG、ePub、甚至 Reveal.js 幻灯片。
我平时用得最多的是 HTML 和 PDF。
导出 HTML 的操作很简单：右键预览 →Export→HTML。MPE 默认会生成一个带完整样式（内嵌 CSS 和 JS）的独立 HTML 文件，可以直接双击打开，也可以部署到任意静态服务器上。它会把图片以 base64 或相对路径形式打包，取决于你的配置。
要是想导出 PDF，建议先配置一下 Chrome 打印协议。在项目根目录创建一个pdf-config.json：
{ "printBackground": true, "displayHeaderFooter": true, "headerTemplate": "<div style='font-size:9px;margin-left:1cm;'>我的文档</div>", "footerTemplate": "<div style='font-size:9px;text-align:center;'><span class='pageNumber'></span> / <span class='totalPages'></span></div>" }然后在 MPE 的设置里指定：
"markdown-preview-enhanced.printOptions": "./pdf-config.json"这样导出 PDF 时，背景色、页码、页眉都会按配置生成，而不是一片白纸加干巴巴的内容。我见过很多人导出 PDF 后背景色全部丢失，代码块变成白底，就是忽略了printBackground这个选项。
4.4 工作流扩展：把 Markdown 转成 Word 或接入自动化
除了 MPE 自带的导出，还有一条更高阶的路线：Pandoc。如果你想转 Word（.docx），MPE 的导出列表里其实没有直接选项，但 Pandoc 可以完美解决。
安装 Pandoc 后，在终端里执行：
pandoc input.md -o output.docx它会根据 Markdown 里的标题层级自动生成 Word 大纲结构，表格转成 Word 表格，代码块转成带底色的样式，效果整体不错。加一个--reference-doc参数甚至可以指定你自定义的 Word 模板：
pandoc input.md -o output.docx --reference-doc=template.docx如果嫌命令行麻烦，也可以利用 VS Code 的任务功能，按Ctrl+Shift+B直接触发构建。在.vscode/tasks.json里配置一个任务：
{ "version": "2.0.0", "tasks": [ { "label": "md to docx", "type": "shell", "command": "pandoc docs/README.md -o dist/README.docx", "group": "build" } ] }这样你只需要一个快捷键，就能把当前的 Markdown 编译成 Word 文件，整个“手动复制粘贴调整格式”的流程被压缩成了几秒钟。
5. 常见问题与排查技巧实录
5.1 预览能渲染，但导出后样式丢失
这是非常典型的问题：MPE 预览里一切正常，导出 HTML 或 PDF 以后标题颜色、代码块背景、间距全变了。原因八成是自定义 CSS 只在预览时被加载，没有进入导出流程。
排查顺序：先确认你是不是在预览窗口 → 右键 → Preview Settings里设置了自定义样式。如果设置了，再看该 CSS 文件是否被放在项目目录内，且路径符合 MPE 的配置规则。如果是导出 PDF，还要额外确认printOptions里的 CSS 打印样式是否存在。
我要提醒的是：MPE 导出 HTML 时默认会把 CSS 内嵌进 HTML 文件，这个行为本身没问题，但如果你引用了项目外的本地绝对路径（比如C:/styles/style.css），导出的 HTML 在别人电脑上打开就会丢。正确做法是使用相对路径或将 CSS 内容写进preview.css。
5.2 Mermaid 图表在预览里不显示
MPE 对 Mermaid 的渲染依赖浏览器端的动态加载，偶尔会遇到“只显示代码块、图表渲染不出来”的问题。最常见的原因有两个：
一个是网络问题。MPE 默认会从 CDN 加载 Mermaid 相关 JS 资源，如果处于离线状态或者 CDN 被墙，整个图表会陷入长时间加载最终失败。解决办法是在 MPE 设置中把 mermaid 的 CDN 地址改成自己可访问的镜像源，或者下载 mermaid.min.js 放到本地项目目录中并指定本地路径。
另一个是版本兼容问题。Mermaid 升级频繁，老版本 MPE 可能和新版本语法不兼容。如果你在官网调试 Mermaid 语法正常，但在 MPE 里渲染不出来，先考虑 MPE 的版本和 Mermaid 的版本匹配问题，升级 MPE 试试。
我这里给一个最小可复现的模板：
```mermaid flowchart LR A[开始] --> B[处理] B --> C[结束] ```先把这个丢进 MPE 里看能否正常渲染，如果连这个都不行，那就是 MPE 或资源加载的问题；如果这个行，那大概率是你特定的图表语法存在兼容性差异。
5.3 图片在 GitHub 上正常，本地预览却看不到
这个坑我也踩过：用 VS Code 写作时图片路径写的是，GitHub 上能正常显示，但本地 MPE 预览打开就是一张坏图。
根源在于 MPE 的预览服务根目录设置。默认情况下，MPE 预览的根目录是以当前打开的文件夹为准的，如果你的 Markdown 文件在docs/子目录里，而图片路径从项目根目录写起（比如/assets/img/pic.png），本地就会去找根目录下的assets，跟文档实际所在位置对不上。
解决办法有两个方向。第一，在 MPE 设置里找到Preview Root选项，手动指定为当前文档所在目录。第二，统一使用相对路径，并确保文档和图片的相对关系固定。我个人后者的实战成功率高得多，因为它不依赖任何工具配置，且在任何环境（GitHub、语雀、本地）都能正确解析。
5.4 表格转换 Excel 的两种快捷方式
Markdown 表格想转成 Excel，网上教程一大堆，但直接在 VS Code 里完成的人不多。这里给两个方案。
方案一，用 Markdown All in One 先把表格格式化，然后全选表格内容复制，粘贴到 Excel 里。Excel 通常能自动识别竖线分隔的文本，但成功率取决于表格格式是否规范。规范格式长这样：
| 姓名 | 年龄 | 城市 | | ---- | ---- | ---- | | 张三 | 25 | 北京 | | 李四 | 30 | 上海 |方案二，安装Excel to Markdown table插件，它支持双向转换。在 VS Code 命令面板里搜索Markdown to Excel，把 Markdown 表格内容粘贴进去，它就能帮你生成一个 CSV，再拖进 Excel 就是规规矩矩的二维表格。
5.5 快捷键失效、插件不生效的通用排查思路
用得时间久了，难免遇到插件装了没反应、快捷键按了没动静的情况。别急着卸载重装，先按这个顺序排查。
第一步，确认插件是否被禁用。左侧扩展面板里看该插件有没有打开“启用”开关。
第二步，检查快捷键冲突。按Ctrl+Shift+P输入Preferences: Open Keyboard Shortcuts，在搜索框里输入快捷键，看看是不是被别的东西占用了。VS Code 的快捷键冲突会静默保留一个生效的，被覆盖的不会弹提示，这个很坑人。
第三步，更新或重装插件。MPE 这类大插件更新频率低，偶尔会有老版本与最新版 VS Code 不兼容的情况。去扩展市场看看有没有更新，或者直接把插件禁了再启用，很多时候就能解决“命令找不到”的诡异问题。
第四步，实在不行就重启 VS Code，或者用Developer: Reload Window重新加载整个窗口。这个操作会重载所有扩展，相当于“重启大法”，能解决不少状态残留类问题。
结尾
配置到今天这个程度，我对 Markdown 工作流的最大体会是：工具链不是越复杂越好，而是每一环都清楚自己在干什么。VS Code 负责编辑体验，MPE 负责人机交互，Pandoc 负责格式转换，Git 负责版本追踪。它们的职责边界清晰，组合起来才能成为一条可信赖的生产线。
最后分享一个小习惯——我会在项目仓库里放一个CHANGELOG.md，每次做配置调整都记一行：改了哪个插件、为什么改、效果怎么样。有时候过了几个月回头看，能帮你回想起来当时为什么放弃某个渲染方案，避免重复踩坑。Markdown 编译器配置是个长期演化的过程，今天这个方案可能半年后又有新插件挑战它的地位，但这套“源文件 + 预览 + 导出”的核心思路是稳定的，值得投入时间把它理顺。
