企业官网建设流程全解析

Markdown 这玩意儿，写起来是真舒服，纯文本、跨平台、版本控制友好，但第一次接触的人往往卡在同一个地方：文件写完了，怎么看到渲染后的效果？我见过太多人对着.md文件里的一堆#和*发愣，甚至有人直接双击用浏览器打开，结果看到的是源码而不是排版好的文档。VSCode 作为目前最主流的编辑器之一，内置的 Markdown 预览能力其实已经够用了，但很多人不知道入口在哪，或者只知道一个快捷键，遇到表格错位、图片不显示、Mermaid 图表渲染不出来就抓瞎。这篇内容就是把我这些年用 VSCode 写 Markdown 的完整经验拆开讲清楚，从最基础的预览入口，到插件选型、语法细节、图片路径处理、导出工作流，再到那些让人血压升高的踩坑现场。不管你是刚装好 VSCode 的新手，还是已经写了一段时间但总觉得哪里不对劲的老手，应该都能从里面找到能直接用的东西。

1. 先搞清楚 VSCode 预览 Markdown 的几种打开方式

很多人以为预览 Markdown 需要装插件，其实 VSCode 原生就支持，只是入口藏得不算深但也不够显眼。我刚开始用的时候也是找了半天，后来发现其实有好几种方式可以触发预览，各有各的适用场景。

1.1 最直接的快捷键与右键菜单

打开一个.md文件后，按Ctrl+Shift+V（macOS 上是Cmd+Shift+V），当前标签页会直接切换成预览视图。这个操作的本质是在同一个编辑器组里替换掉源码视图，适合你想专注看渲染效果的时候。但问题也很明显：改不了内容了，得再按一次快捷键切回来。

另一种更常用的方式是Ctrl+K然后按V，这个会在旁边新开一个预览标签页，左边源码右边预览，改一个字右边实时更新。我平时写文档基本都用这个模式，因为 Markdown 的语法虽然简单，但表格对齐、列表缩进这些东西，不看着渲染效果调很容易出问题。

右键菜单里也有入口。在编辑器里点右键，能看到"打开预览"和"打开侧边预览"两个选项，效果和上面两个快捷键一一对应。如果你记不住快捷键，右键是最稳妥的方式。

还有一种不太常用但偶尔有用的方式：在资源管理器里右键.md文件，选择"打开预览"，这样不用先打开源码就能直接看渲染结果。适合快速翻阅别人的文档。

1.2 命令面板里的隐藏选项

按Ctrl+Shift+P打开命令面板，输入markdown就能看到所有相关命令。除了上面说的两个预览命令，还有一个"打开锁定预览"值得说一下。锁定预览的意思是，当你切换到其他.md文件时，预览窗口不会跟着变，而是保持显示当前锁定的那个文件。这个功能在对比两个文档或者边写边参考另一份文档时特别有用。

命令面板里还能看到"在浏览器中打开预览"之类的选项，不过这个需要额外配置，后面讲插件的时候再说。

1.3 预览窗口的布局调整

侧边预览默认是在右边打开，但你可以把它拖到左边、上面或者下面。我个人的习惯是把预览放在右侧，因为中文阅读习惯是从左到右，源码在左、预览在右，视线移动比较自然。如果你用的是带鱼屏或者双屏，可以把预览标签页拖到另一个屏幕，这样源码和预览完全独立，写长文档的时候体验很好。

预览标签页的标题会显示文件名加上"预览"字样，方便区分。如果你同时开了多个预览，每个都会独立更新，不会互相干扰。

提示：预览窗口里的内容是可以选中和复制的，但默认不能编辑。如果你需要直接在预览里改内容，得装支持所见即所得编辑的插件，这个后面会讲。

2. 原生预览够用吗？聊聊内置能力的边界

VSCode 内置的 Markdown 预览基于 markdown-it 这个渲染引擎，支持 CommonMark 规范加上一些扩展语法。日常写文档、README、笔记完全够用，但有些场景下你会明显感觉到力不从心。

2.1 原生支持哪些语法

先列一下内置预览能直接渲染的东西，心里有个底：

表格这块要特别说一下，很多人写表格预览不出来，八成是分隔行写错了。正确的表格必须有三部分：表头行、分隔行、数据行。分隔行是用|---|这种形式，冒号控制对齐方式。少一行或者格式不对，整个表格就会变成普通文本。

2.2 原生预览的三个明显短板

第一个短板是滚动同步。侧边预览默认是开启滚动同步的，源码滚到哪预览跟到哪。但这个同步有时候不太准，尤其是文档里有大段代码块或者图片的时候，两边的位置会对不上。你可以在预览窗口右上角找到同步滚动的开关，手动关掉。关掉之后就得自己控制位置了，但至少不会出现"我明明在看第三段，预览跳到第五段"这种糟心事。

第二个短板是图片路径处理。Markdown 里插入图片用![alt](path)，这个 path 可以是相对路径、绝对路径或者 URL。原生预览对相对路径的解析是基于当前.md文件所在目录的，但如果你用了工作区根目录的相对路径，或者路径里有空格、中文，就可能加载不出来。这个问题后面会专门讲。

第三个短板是不支持扩展语法。Mermaid 流程图、KaTeX 数学公式、脚注、定义列表这些，原生预览一律不认。如果你写技术文档需要画流程图，或者写学术笔记需要打公式，就必须装插件。

2.3 什么时候该考虑装插件

我的判断标准很简单：如果你只是写写 README、记记笔记、列列待办，原生预览完全够用，不用折腾插件。但如果你遇到以下任何一种情况，就该考虑装插件了：

• 需要在文档里画流程图、时序图、甘特图
• 需要写数学公式
• 需要导出 PDF 或 Word
• 需要自动生成目录
• 需要更精确的滚动同步
• 需要所见即所得编辑

插件这东西，装多了会拖慢 VSCode 启动速度，也会让界面变乱。我的建议是按需装，别一上来就装一堆。

3. 插件选型：Markdown All in One 与 Markdown Preview Enhanced 怎么选

VSCode 的 Markdown 插件生态里，有两个名字出现频率最高：Markdown All in One 和 Markdown Preview Enhanced。很多人纠结装哪个，其实这两个的定位完全不同，甚至可以同时装。

3.1 Markdown All in One：编辑辅助为主

Markdown All in One 的核心价值在编辑效率，不是预览增强。它提供的东西包括：

• 快捷键格式化：Ctrl+B加粗、Ctrl+I斜体，和 Word 的操作习惯一致
• 自动生成目录：命令面板里搜"Create Table of Contents"，一键生成带锚点的目录
• 列表自动续行：回车自动补-或1.
• 表格格式化：自动对齐表格的竖线
• 数学公式支持：用$包裹的公式能渲染
• 快捷键切换任务状态：Alt+C勾选/取消勾选

这个插件对预览的增强很有限，主要是让数学公式能显示。但它的编辑辅助功能是真的省时间，尤其是自动生成目录和表格格式化，写长文档的时候能省不少手动调整的功夫。

安装方式很简单，在扩展面板搜"Markdown All in One"，认准作者是 Yu Zhang 的那个，安装量最高的就是。

3.2 Markdown Preview Enhanced：预览能力拉满

Markdown Preview Enhanced（简称 MPE）走的是另一条路，它把预览能力做到了极致。装完之后，预览不再是 VSCode 原生的那个，而是 MPE 自己渲染的页面。它支持的东西包括：

• Mermaid 图表：流程图、时序图、类图、状态图、甘特图、饼图
• KaTeX 数学公式：行内和块级都支持
• 导出 PDF、PNG、JPEG、HTML
• 导出成幻灯片（基于 reveal.js）
• 代码块行号和高亮
• 目录侧边栏
• 滚动同步更精确
• 支持导入外部文件

MPE 的预览界面和原生预览不太一样，右上角有一排按钮，可以切换主题、导出、打开目录等。第一次用可能会觉得有点复杂，但习惯了之后会发现功能确实强。

3.3 两个插件的共存与冲突处理

这两个插件可以同时装，但要注意一点：装了 MPE 之后，默认的预览命令会被 MPE 接管。也就是说你按Ctrl+Shift+V打开的是 MPE 的预览，不是原生的。如果你还想用原生预览，可以在命令面板里搜"Markdown: Open Preview"（注意不是"Markdown Preview Enhanced: Open Preview"）。

我的实际用法是：日常写笔记用原生预览或者 Markdown All in One，写技术文档需要画图打公式的时候用 MPE。两个插件都装着，按需切换。

注意：MPE 的预览是基于 Webview 的，打开大文件时可能会比原生预览慢一些。如果你的文档超过几千行，建议还是用原生预览。

3.4 其他值得关注的插件

除了上面两个，还有几个插件在特定场景下很有用：

• markdownlint：检查 Markdown 语法规范，帮你养成好习惯。比如标题层级不能跳级、列表缩进要一致、行尾不能有多余空格。写团队文档的时候特别有用，能避免因为格式问题产生的 diff 噪音。
• Markdown Table Prettifier：专门格式化表格，让竖线对齐。Markdown All in One 也有类似功能，但这个更专注。
• Paste Image：截图后直接粘贴到 Markdown 里，自动保存图片到指定目录并插入链接。写教程的时候效率翻倍。
• Markdown Preview Mermaid Support：如果你不想装 MPE 这么重的插件，只想让原生预览支持 Mermaid，装这个就够了。

4. 预览之外的刚需：语法细节与图片路径处理

预览能不能正常显示，很大程度上取决于你的 Markdown 语法写得对不对，以及图片路径有没有处理对。这两个问题在预览出问题的时候占了绝大多数。

4.1 换行这个坑，几乎每个人都踩过

Markdown 的换行规则和 Word 完全不一样。在 Word 里按回车就是换行，在 Markdown 里，单个回车会被渲染成空格，两个段落会连在一起。这是 CommonMark 规范定的，不是 VSCode 的 bug。

正确的换行方式有三种：

第一种是在行尾加两个空格，然后回车。这两个空格是"硬换行"的标记，渲染出来就是换行。但问题是空格在编辑器里看不见，很容易被格式化工具删掉，或者自己忘了加。

第二种是行尾加反斜杠\，然后回车。这个更直观一些，反斜杠是可见的，不容易丢。我平时用这种方式比较多。

第三种是直接空一行，形成新段落。这是最推荐的，因为语义清晰，渲染出来段落之间有间距，阅读体验更好。

如果你实在不习惯，可以在 VSCode 设置里搜"markdown.preview.breaks"，把它设成 true。这样单个回车就会被渲染成换行，和 Word 的习惯一致。但这个设置只影响预览，不影响源码，别人用其他工具打开你的文档可能还是连在一起的。所以我的建议是：改习惯，别改设置。

4.2 图片路径的三种写法和各自的坑

Markdown 插入图片的语法是![替代文字](图片路径)。路径的写法直接决定了预览能不能显示。

相对路径是最常用的，相对于当前.md文件的位置。比如.md文件在docs/目录下，图片在docs/images/目录下，就写![截图](images/screenshot.png)。这种写法在 VSCode 预览里能正常显示，推到代码托管平台也能正常显示。

但相对路径有两个坑。第一个坑是路径里有空格或中文。有些渲染引擎对空格的处理不一致，建议把空格换成%20或者干脆用英文命名。中文路径在 VSCode 预览里一般没问题，但推到某些平台可能会挂。

第二个坑是大小写敏感。Windows 的文件系统不区分大小写，但 Linux 和代码托管平台区分。你在 Windows 上写Images/screenshot.png能显示，推到平台上就挂了，因为实际目录是images。这个坑我踩过不止一次，后来养成了所有目录和文件名都用小写的习惯。

绝对路径是从根目录开始的完整路径，比如/Users/name/project/docs/images/screenshot.png。这种写法在本地预览没问题，但换台机器就挂了，推到平台上更挂。除非是个人笔记不打算分享，否则不建议用。

URL 路径是直接写图片的在线地址，比如![logo](https://example.com/logo.png)。这种写法最省事，但依赖网络，离线环境下显示不出来。而且如果图片源挂了，文档里的图就全没了。重要文档建议把图片下载到本地，用相对路径引用。

4.3 表格对齐与转义字符

表格是 Markdown 里比较容易写错的部分。一个标准的表格长这样：

| 姓名 | 年龄 | 城市 | |:-----|:----:|-----:| | 张三 | 28 | 北京 | | 李四 | 32 | 上海 |

分隔行里的冒号控制对齐：左边加冒号左对齐，两边都加居中对齐，右边加冒号右对齐。不加冒号默认左对齐。

常见的错误包括：分隔行的竖线数量和表头不一致、分隔行用了--而不是---、表格前后没有空行。这些都会导致表格渲染失败，变成一堆带竖线的普通文本。

转义字符也值得说一下。Markdown 里有些字符有特殊含义，比如*、_、#、[、]。如果你想显示这些字符本身，需要在前面加反斜杠。比如想显示*星号*而不是斜体的"星号"，就写\*星号\*。这个在写技术文档的时候经常遇到，比如写正则表达式或者命令行参数。

4.4 代码块的语言标注

代码块用三个反引号包裹，后面可以跟语言标识，用于语法高亮：

def hello(): print("Hello, Markdown")

语言标识写对了，预览里就会有对应的颜色高亮。写错了或者不写，就是灰底黑字，没有高亮。常用的标识有python、javascript、bash、json、yaml、html、css、sql等。

有个小技巧：如果代码块里本身包含三个反引号，可以用四个反引号包裹外层，这样就不会冲突。这个在写 Markdown 教程的时候特别有用。

5. 从预览到导出：PDF、Word、HTML 的完整工作流

预览只是第一步，很多时候我们需要把 Markdown 导出成其他格式分享给别人。VSCode 本身没有内置导出功能，但通过插件可以搞定。

5.1 用 Markdown Preview Enhanced 导出 PDF

MPE 的导出功能是最全的。在 MPE 预览界面右键，选择"Chrome (Puppeteer)"下的"PDF"，就能导出 PDF。第一次导出会下载一个 Chromium，大概一百多兆，需要等一会儿。

导出的 PDF 样式取决于你选的预览主题。MPE 内置了好几个主题，比如 github-light、github-dark、vue 等。我一般用 github-light，导出效果比较干净。

导出 PDF 有几个注意点。第一，中文字体需要确认系统里有，否则可能显示成方块。第二，代码块如果太长，可能会被截断，需要在设置里调整页边距。第三，Mermaid 图表在 PDF 里的渲染质量取决于导出时的分辨率设置。

5.2 导出 Word 的曲线方案

MPE 不直接支持导出 Word，但可以导出 HTML，然后用 Word 打开 HTML 再另存为 docx。这个流程虽然绕，但效果还行。具体操作是：MPE 预览右键，选择"HTML"下的"HTML (offline)"，导出后用 Word 打开，再另存为 docx。

另一种方案是用 Pandoc 这个命令行工具。Pandoc 支持 Markdown 转 docx，效果比 HTML 中转好很多。安装 Pandoc 后，在终端里运行：

pandoc input.md -o output.docx

如果需要自定义样式，可以加--reference-doc=template.docx参数，用一个预先做好的 Word 模板控制字体、行距、标题样式。这个方案适合需要批量转换的场景。

5.3 导出 HTML 的两种模式

MPE 导出 HTML 有两种模式：online 和 offline。online 模式的 HTML 会引用 CDN 上的 CSS 和 JS，文件小但需要联网才能正常显示。offline 模式会把所有资源打包进去，文件大但可以离线打开。

如果是发给别人看，建议用 offline 模式，避免对方网络环境不好导致样式丢失。如果是自己存档，online 模式就够了。

导出的 HTML 默认是带 MPE 的样式的，如果你想要更干净的输出，可以在 MPE 设置里关掉一些增强功能，或者用 Pandoc 导出：

pandoc input.md -o output.html --standalone --css=style.css

5.4 导出时的图片处理

导出 PDF 或 HTML 时，图片路径是个大问题。如果图片是相对路径，导出后的文件如果不在原目录下，图片就显示不出来。MPE 在导出时会尝试把图片嵌入，但有时候会失败。

我的做法是：导出前先把所有图片转成 base64 嵌入，或者确保导出文件和图片的相对位置不变。MPE 的设置里有一个"Image Upload"选项，可以配置图片上传到图床，但涉及外部服务，这里就不展开了。

6. 踩坑实录：预览不显示、乱码、性能问题的排查链路

这一节记录几个我实际遇到过的问题和排查过程，都是预览相关的典型故障。

6.1 预览一片空白，源码明明有内容

有一次我打开一个.md文件，按Ctrl+Shift+V，预览窗口一片空白。源码里明明有几千字，但预览就是什么都不显示。

排查过程是这样的：先看预览窗口右上角有没有报错图标，没有。然后试着滚动源码，预览也不跟着动。接着我把文件内容复制到一个新建的.md文件里，预览正常。这说明问题出在原文件本身。

用十六进制查看器打开原文件，发现文件开头有几个不可见字符（BOM 头）。这个文件是从 Windows 系统传过来的，可能用了带 BOM 的 UTF-8 编码。VSCode 的 Markdown 预览对 BOM 头处理有问题，导致整个文档渲染失败。

解决办法很简单：在 VSCode 右下角点击编码格式，选择"通过编码保存"，选"UTF-8"（不带 BOM），保存后预览就正常了。

这个坑的教训是：跨平台传文件时，注意编码格式。UTF-8 带 BOM 在 Windows 上常见，但在很多工具里会出问题。

6.2 图片显示成裂图，路径明明是对的

另一个常见问题是图片不显示，预览里出现一个裂图图标。路径检查了好几遍，确实是对的。

这种情况通常有几个原因。第一，路径里有特殊字符没有转义，比如空格、括号、中文。第二，路径的大小写和实际文件不一致。第三，图片文件本身损坏或者格式不支持。

排查的时候，我会先把路径复制出来，在终端里用ls或者dir命令确认文件确实存在。如果存在，再检查路径里有没有需要转义的字符。VSCode 预览对空格的处理有时候不太稳定，把空格换成%20通常能解决。

还有一个容易被忽略的点：如果.md文件是通过符号链接打开的，相对路径的基准目录可能会变。这种情况比较少见，但遇到了会很难排查。

6.3 大文件预览卡顿甚至崩溃

Markdown 文件超过一万行之后，预览会明显变卡。滚动的时候有延迟，输入的时候预览更新不及时，严重的时候 VSCode 会直接卡死。

这是因为原生预览每次更新都要重新渲染整个文档，文档越大，渲染耗时越长。MPE 的 Webview 方案在大文件下反而更卡。

我的应对策略是：写长文档的时候，把内容拆成多个.md文件，用一个索引文件链接起来。这样每个文件都不大，预览流畅。如果必须在一个文件里写，可以临时关掉预览，写完一段再打开看一次。

另外，文档里如果有大量图片或者 Mermaid 图表，也会拖慢预览。图片建议压缩后再引用，Mermaid 图表不要放太多。

6.4 Mermaid 图表渲染失败的各种原因

用 MPE 渲染 Mermaid 图表时，失败的原因五花八门。最常见的是语法错误，比如箭头写错、节点名称有特殊字符、缩进不对。Mermaid 的语法比较严格，一个字符错了整个图就渲染不出来。

排查的时候，我会先把图表代码单独拿出来，在 Mermaid 的在线编辑器里测试。确认语法没问题后，再放回文档里。如果在线能渲染但 MPE 里不行，可能是 MPE 的 Mermaid 版本比较旧，不支持某些新语法。

还有一种情况是图表太复杂，节点太多，渲染超时。这种只能简化图表，或者拆成多个小图。

7. 让预览更顺手的几个配置与习惯

最后分享一些我长期使用下来觉得能提升体验的配置和习惯，都是实际验证过的。

7.1 值得改的几个 VSCode 设置

在settings.json里加这几项，预览体验会好很多：

{ "markdown.preview.fontSize": 15, "markdown.preview.lineHeight": 1.7, "markdown.preview.breaks": false, "markdown.preview.typographer": true, "editor.wordWrap": "on", "editor.quickSuggestions": { "other": true, "comments": false, "strings": true } }

fontSize和lineHeight控制预览的字体大小和行高，默认值偏小，中文阅读起来有点累。breaks设成 false 是保持标准换行行为，前面解释过了。typographer开启后会做一些排版优化，比如把直引号转成弯引号。wordWrap让源码也自动换行，避免横向滚动。

7.2 工作区级别的配置隔离

如果你同时维护多个项目，不同项目对 Markdown 的要求可能不一样。比如技术文档项目需要 Mermaid 支持，个人笔记项目不需要。这时候可以用工作区级别的配置，在项目根目录建一个.vscode/settings.json，只对当前项目生效。

这样切换项目的时候，预览行为会自动跟着变，不用手动改来改去。

7.3 用任务自动化预览流程

VSCode 的任务系统可以自动化一些操作。比如你可以建一个任务，一键打开预览并启动一个本地服务器，用于预览带外部资源的文档。不过这个配置比较复杂，日常用不太上，这里就不展开了。

7.4 预览窗口的快捷键自定义

如果你觉得默认的Ctrl+K V按起来别扭，可以在键盘快捷方式设置里改成自己顺手的组合。我改成了Ctrl+Alt+P，因为按起来更顺手，而且不容易和其他快捷键冲突。

改的方法是：打开键盘快捷方式设置，搜markdown.showPreviewToSide，双击绑定新的快捷键。

7.5 一个容易被忽略的细节：预览的滚动位置记忆

VSCode 的预览窗口在关闭再打开后，滚动位置会重置到顶部。如果你在写长文档，每次打开预览都要重新滚到刚才的位置，很烦。

目前没有原生设置能解决这个问题，但有个变通方法：用 MPE 的预览，它会在一定程度上记住滚动位置。或者你可以用书签插件，在源码里标记位置，预览时快速跳转。

这个细节虽然小，但在写长文档的时候影响挺大的。希望 VSCode 后续版本能加上这个功能。

写 Markdown 这件事，工具只是辅助，核心还是内容本身。但好的工具配置能让你少花时间在格式调整上，多花时间在内容创作上。VSCode 的 Markdown 预览能力，原生够用，插件能补强，关键是搞清楚自己的需求，别为了折腾而折腾。我见过有人装了一堆插件，结果每次打开 VSCode 都要等半分钟，反而降低了效率。按需配置，够用就好。