企业官网建设流程全解析

很多人第一次把 VS Code 当成 Markdown 阅读器，是被它的“顺手”骗进来的:编辑器里本来就有一堆 md 文件,何必再开一个专门的阅读软件。结果按下快捷键之后发现,能看到的东西和想象中不太一样——有时候是一屏渲染好的排版,有时候是一屏带着星号和井号的源码,图片还裂了几个,表格挤成一团。这篇就围绕VS Code（下称 VS Code）查看 .md 文件这件事,把“怎么打开”“为什么显示不对”“怎么读得舒服”这三件事一次讲透。

不管你是刚接手一个文档仓库的新人,还是日常要把别人写的 md 说明读一遍再改的技术同学,下面这些内容都能直接用。我踩过的坑基本都集中在两类:一类是路径,一类是渲染规则,搞清楚这两样,剩下都是调参。

1. 先分清“编辑态”和“预览态”：VS Code 打开 md 到底显示了什么

打开一个 md 文件,默认看到的是纯文本源码。这不是 VS Code 有问题,而是它的定位决定的:Markdown 本质上就是纯文本,编辑器先保证你能改,再谈能不能“看”。

1.1 源码视图与渲染视图是两条独立管线

源码视图走的是普通文本编辑器的渲染逻辑,语法高亮、括号匹配、折叠、查找替换全部可用,你改的是什么,存下去就是什么。渲染视图(官方叫 Markdown Preview)则是另一套东西:它把 md 文本交给一个 Markdown 解析器转成 HTML,再塞进一个内置的浏览器视图里显示。两条管线互不干扰,所以你在源码里打了一半的表格,预览里可能直接塌掉,这不代表文件坏了,只是解析器在那一刻拿到的文本不合法。

理解这一点很关键,因为后面所有的“显示异常”都可以归到两类原因:要么是文本本身不符合 Markdown 规范,要么是渲染视图拿不到它需要的资源(图片、样式、字体)。前者改文本,后者改配置,思路完全不一样。

顺带说一个细节:预览视图是只读的。你在预览里点不到光标,也改不了字,想编辑必须切回源码。这一点经常让刚上手的人困惑,以为预览卡住了,其实它本来就不接受输入。

1.2 三种打开预览的姿势，用错场景会很难受

打开预览有几个入口,差异不小,值得分开记:

我个人的习惯是永远用第二种。原因很实际:写文档时经常要一边调格式一边看效果,侧边预览能让你在一次视线移动内完成“改—看”循环,而第一种方式每次都要来回切标签,切几次就烦了。如果你只是读别人的文档,不打算改,那第一种更省屏幕空间。

还有一个容易被忽略的点:在预览视图里双击任意位置,会直接切回源码视图。这个行为由设置项markdown.preview.doubleClickToSwitchToEditor控制,默认开启。它读文档时有点碍事——手滑双击就跳走了,建议只在需要频繁改稿时保留。

1.3 预览标签的临时性：它不会记住你的阅读位置

VS Code 的编辑器标签分“普通标签”和“预览标签”,后者标签名是斜体的,特点是:你在侧边栏点另一个文件,它会直接被替换掉,不会新开一个。这个机制的本意是防止标签爆炸,但读文档时非常容易误伤——你正在看第 300 行的某段说明,手贱在资源管理器里点了一下别的文件,刚才那个预览标签就没了。

控制这个行为的设置是workbench.editor.enablePreview。我的建议是:如果你主要在 VS Code 里读长文档而不是写代码,把它关掉;如果你平时写代码多、只是偶尔看文档,保留默认值更清爽。这是个取舍,没有标准答案。

另外,预览视图本身的滚动位置在关闭重开后不会保留,长文档每次都要重新滚。这一点没有官方设置能改,后面第 4 节会讲怎么用大纲和折叠来缓解。

2. 预览空白、图片裂开、样式全丢：一条从浅到深的排查链路

“打开 md 预览是一片空白”是我被问得最多的一类问题。它看起来玄学,实际上排查路径非常固定,按下面四层往下走,基本能定位。

2.1 第一层：文件到底有没有被识别成 Markdown

这一步听起来废话,但真的有人栽在这里。VS Code 根据文件扩展名决定语言模式,如果某个扩展把.md的关联抢走了,或者你打开的是一个没有扩展名的文件,预览命令可能压根不出现。

判断方法很简单:看窗口右下角状态栏的语言标识,正常应该显示Markdown。如果显示的是Plain Text或者别的语言,点它,选择Markdown,再看预览能否打开。也可以按Ctrl+Shift+P搜Change Language Mode手动改。

顺带提一个容易忽略的场景:文件名大小写。.MD、.Md在多数系统上没问题,但如果你在配置里写过files.associations的自定义映射,又只写了小写,那就可能匹配不上。

2.2 第二层：图片相对路径的解析基准是文件所在目录

图片裂开是第二大高频问题。原因几乎都是一个:预览器解析相对路径时,基准是 md 文件自己所在的目录,不是工作区根目录,也不是当前打开的第一个文件夹。

举例,假设结构是这样:

docs/ guide/ intro.md images/ step1.png

在intro.md里写![步骤](images/step1.png),预览能正常显示。但如果写成![步骤](/docs/guide/images/step1.png),那就是另一套规则了——以/开头的路径,预览会把它当成相对工作区根目录的路径去解析。工作区根目录是docs还是它的上一层,结果完全不同。

这里有个非常实用的判断技巧:先把图片路径改成相对路径试一次。相对路径能显示,说明是路径基准问题;相对路径也不显示,说明是文件真的不存在、文件名拼错(尤其是大小写)、或者图片本身损坏。Linux 和 macOS 默认文件系统对大小写敏感,Step1.png和step1.png是两个文件,从 Windows 迁移过来的文档经常在这里翻车。

还有一种情况是带空格和中文的路径。Markdown 语法里,路径含空格时需要用尖括号包起来或者做 URL 编码:

![截图](<images/首页 截图.png>)

不处理的话,解析器会在空格处截断,剩下半截路径当然找不到文件。

2.3 第三层：markdown.styles 的路径基准却是工作区根目录

这一条是最容易让人怀疑人生的。前面说图片是相对 md 文件所在目录,但自定义样式表markdown.styles的路径是相对工作区根目录的。两个东西在同一个设置文件里,基准却不一样。

一个典型配置长这样:

{ "markdown.styles": [".vscode/preview.css"] }

这个路径的含义是“工作区根目录下的.vscode/preview.css”,不是“当前 md 文件旁边的.vscode/preview.css”。如果你的 md 文件在docs/guide/下,而样式放在docs/guide/.vscode/preview.css,那这个配置是不会生效的,而且不会报任何错——样式静默失效,你只会觉得“怎么没变化”。

更麻烦的是,如果你压根没有打开文件夹,只是单独打开了一个 md 文件,那就不存在“工作区根目录”,相对路径的基准会退化。稳妥的做法有两个:一是确保样式文件放在工作区根目录下;二是用绝对路径或者可访问的远程地址,但后者对离线环境不友好,看你的场景。

样式文件本身给个最小可用的例子,主要解决“行太长看不过来”的问题:

body { max-width: 860px; margin: 0 auto; padding: 0 24px 64px; } img { max-width: 100%; height: auto; }

改完设置记得保存,并且重新打开一次预览。已经打开的预览视图不会热更新样式表内容,这是个很容易漏的细节。

2.4 第四层：内联 style 标签被过滤，别指望它救场

有人为了不改设置,直接在 md 文件顶部写一段<style>把样式塞进去。这招在浏览器里有效,在 VS Code 预览里基本无效。

预览视图对 md 中嵌入的 HTML 做了安全过滤,<script>标签、<style>标签、on*系列事件属性都会被剥掉。一部分结构标签比如<details>、<summary>、<br>、<kbd>是可以正常渲染的,但所有涉及“执行”和“全局样式注入”的东西都会被清理。这不是 bug,是设计如此——预览视图本质上在一个受限环境里跑,不允许任意 HTML 修改宿主样式。

所以如果你发现“我明明写了 style 但预览没反应”,不用怀疑语法,这条路本身就走不通,老老实实用markdown.styles。

3. 单换行不生效、表格塌了、任务列表不渲染：语法层面的硬规则

排除了资源加载问题,剩下的基本都是 Markdown 语法本身的硬性规定。这些东西在文档里写得很清楚,但实际写文档时没几个人会去翻。

3.1 单换行要不要变<br>：breaks 开关的取舍

最常见的一个困惑:在源码里明明回车换行了,预览里两句话还是黏在一起。

原因是标准 Markdown 规范里,单个换行不等于换行,必须空一行才算新段落。想强制换行得在行尾加两个空格,或者用<br>。VS Code 提供了开关markdown.preview.breaks,打开后单个换行会被渲染成换行。配置:

{ "markdown.preview.breaks": true }

打开它确实符合中文写作习惯,但代价是:你从别处复制过来的、按标准规范写的文档,显示效果会发生变化;某些列表项和多段引用里的排版可能变得比预期松散。我的建议是分场景——自己写的个人笔记仓库,打开它更省心;维护多人协作、要发到别的平台的文档,保持关闭,老老实实空行分段。因为你本地打开开关看到的效果,到别的渲染器里就不成立了,改稿时会来回打脸。

3.2 表格必须有的那一行分隔符

表格不渲染,九成是因为少了分隔行,或者分隔行的列数对不上。

| 项目 | 说明 | | --- | --- | | A | 第一项 | | B | 第二项 |

第二行| --- | --- |是必须的,它告诉解析器“上面那行是表头”。没有这一行,整块内容会被当成普通段落输出,竖线原样显示。

另一个坑是列数不匹配。如果表头定义了两列,但某一行的数据写了三列,预览时多出来的那一格会被直接丢弃,而且不报错。你只会发现某个数据莫名其妙不见了,来回找半天。写完表格后扫一眼每行的竖线数量,能省掉大量排查时间。

对齐方式靠冒号控制::---左对齐、:---:居中、---:右对齐。中文表格里数字列用右对齐会整齐很多,值得养成习惯。

3.3 列表缩进与全角空格：中文写作最容易踩的坑

任务列表写法是- [ ]和- [x],方括号里必须有内容(空格或 x),-后面必须有半角空格。少一个空格,整行就退化成普通文本,预览里看不到那个小方框。

更隐蔽的问题是缩进。中文输入法下按 Tab 或者连续空格,很容易打出全角空格。渲染器不认全角空格,嵌套列表的层级关系直接断掉,本来应该是子项的内容变成同级段落。这个问题肉眼几乎看不出来,只能靠编辑器把不可见字符显示出来:

{ "editor.renderWhitespace": "all", "editor.renderControlCharacters": true }

打开之后,半角空格显示为小点,全角空格会显示成另一种样式,一眼就能区分。这个设置我建议常开,写 md 时收益极大。

顺带说,列表嵌套建议统一用 2 个或 4 个空格,不要混用 Tab 和空格。同一份文档里混着来,不同层级的对齐会看起来“差一点点”,实际渲染出来就错位了。

3.4 代码块的语言标注与围栏长度

围栏代码块用三个反引号开头结尾,后面跟语言名可以启用高亮。不写语言名也能渲染成等宽字体,只是没有高亮。

真正容易出问题的是内容里本身包含反引号。比如你要展示一段带三反引号的示例,直接写会导致围栏提前闭合,后面的内容全部变成代码块。解决办法是用四个反引号包住:

````markdown ```js console.log(1) ```

这个技巧写技术文档时很常用,尤其是写“如何写 Markdown”类的内容时,不用它几乎必踩。 还有一个细节:代码块内部的内容**不会**做任何转义处理,原样保留。所以你在代码块里贴报错日志、贴配置片段都很安全,不用担心星号或下划线被吃掉。这也是排查排版问题时的一个好用手段——不确定某段文本会不会被误解析,先扔进代码块里对比一下。 ## 4. 长文档怎么读：滚动同步、行宽、大纲与折叠的组合拳 前面解决的是“能不能正常显示”,这一节解决“读起来累不累”。几百行的技术文档,光靠滚轮翻是很低效的。 ### 4.1 双向滚动同步失灵的真实原因 侧边预览的好处是能双向滚动同步:左边源码滚到哪,右边预览跟到哪,反之亦然。控制它的设置有两个: ```json { "markdown.preview.scrollPreviewWithEditor": true, "markdown.preview.scrollEditorWithPreview": true } ``` 这两个默认都是 true,但实际使用中经常出现“不同步”的现象。原因通常不是设置,而是**文档结构导致的锚点对不上**:预览里一个图片占了半屏高度,源码里只有一行,两边的行号映射自然就错位了。文档里图片、长表格越多,同步偏差越大。 还有一个已知现象:文档特别大(几 MB)时,同步会明显滞后甚至失灵,因为同步依赖一套行号映射计算,文本量超过一定规模后计算本身就很吃力。 实用建议:读长文档时,不要依赖滚动同步来定位,改用“源码里点一下光标,预览自动定位到对应位置”这个方向——它的准确率比反方向高,而且更适合“我看到了这段源码,想看看渲染效果”的场景。 ### 4.2 行宽和字号：把阅读宽容度调到舒适区 预览默认没有最大宽度限制,窗口拉满时一行能到 200 多个字符,眼睛在长行上来回找下一行的开头非常痛苦。这是最影响阅读体验的一个点,也是最容易解决的。 两个层次调整:一是字号和行高,内置设置就能改: ```json { "markdown.preview.fontSize": 15, "markdown.preview.lineHeight": 1.7 } ``` 字号默认 14,行高默认 1.6。中文字形比拉丁字母更高更宽,同样的字号下中文看起来更挤,所以行高往上调一点是值得的,1.7 到 1.8 之间比较舒服。字号看个人,屏幕小时 14 就够,高分屏可以到 16。 二是最大宽度,必须靠 `markdown.styles` 引入 CSS,就是第 2.3 节那段 `max-width` 的写法。中文单行的舒适宽度大概在 35 到 45 个汉字之间,换算成像素大约 700 到 900。设置成 860px 居中,配合行高 1.7,基本能做到“眼睛不用大幅摆动就能读完一行”。 ### 4.3 大纲视图当目录用，比手动翻快得多 长文档必备的功能是大纲。资源管理器面板底部有一个可折叠的 `Outline` 区域,展开后会按标题层级列出整篇文档的结构,点哪跳哪。如果面板被关了,命令面板搜 `Outline` 或者 `Focus on Outline View` 都能叫出来。 另一个更快的入口是 `Ctrl+Shift+O`,直接在文件内按符号跳转。它会列出所有标题,支持模糊输入筛选。我读长文档的固定手法是:先 `Ctrl+Shift+O` 打两个关键字跳到目标章节,再在大纲里看一眼这一章还有几个小节,判断要不要通读。 要让大纲好用,前提是**标题层级写得规范**。如果整篇文档全是 `#` 一级标题,大纲会变成平铺的一长串,失去意义。正常情况下应该是:H1 只用一个(或者干脆不用,让文件名当标题),章节用 H2,小节用 H3,再往下慎重使用。层级混乱的文档,大纲基本没法用。 ### 4.4 搜索只能在源码里做，这是预览的硬伤 不得不说一个体验缺陷:在预览视图里按 `Ctrl+F`,焦点会跳回源码编辑器,搜索的是原始文本,不是渲染后的内容。 这个设计有它的道理(源码才是数据源),但对阅读者不友好:你想在渲染后的文档里找“配置”这个词,搜出来的是带各种符号的源码行,而且定位高亮在左边,右边预览要自己找对应位置。 我的处理办法是:读长文档时不留预览,直接读源码,靠语法高亮和折叠来区分布局。源码里的 `##` 一眼就能看出是章节,反引号包起来的也一眼能认出是代码。对于不是特别依赖渲染效果的文档(纯文字、少图片),直接读源码反而更快。 配合折叠功能就更顺了:`Ctrl+K` `Ctrl+0` 折叠所有层级,文档瞬间变成一页目录;`Ctrl+K` `Ctrl+1` 只保留一级折叠,展开到章节级别;`Ctrl+K` `Ctrl+J` 全部展开。这套组合键熟练之后,读几千行的文档和读一页纸的体验差不多。 ## 5. 扩展装不装：三类需求分开判断，别一上来就装一堆 围绕 md 的扩展非常多,新手最常见的操作是把搜索结果前几名全装上,然后开始遇到各种“预览莫名其妙变了”的问题。合理的做法是先想清楚缺什么。 ### 5.1 只读浏览：内置功能基本够用 如果你的需求就是“把 md 打开看清楚”,内置功能已经覆盖了:预览、双向同步、大纲、折叠、跨文件搜索、自定义样式。不需要装任何东西。 真正需要额外能力的场景是另外几类:要把 md 导出成 PDF 或图片、要渲染数学公式和流程图、要自动生成或更新目录、要做跨文件链接检查。这些内置功能确实做不到,再考虑装。 判断标准可以更简单一点:先按默认配置用一周,遇到具体卡点再去找扩展。带着明确目标去找,比装完再研究它能干什么,效率高得多。 ### 5.2 需要导出、公式、目录：再考虑装 如果有导出需求,要注意一点:不同扩展导出的样式差异很大,而且往往和你在预览里看到的不一致。导出前先导一页看看效果,别等几十页全导完才发现页边距不对。 公式渲染方面,内置预览不支持公式语法,需要扩展补上。装了之后要注意它会接管预览渲染流程,原来能正常显示的表格、图片可能需要重新验证一遍。 目录生成类扩展通常是往文件里插入一段锚点链接列表。这类操作会**修改源文件**,用之前确认文件在版本管理里,或者至少先备份。我见过有人对着一个几百页的文档点了一下“生成目录”,插进去的内容格式不对,回滚很麻烦。 跨文件链接检查类的扩展对维护文档仓库很有价值:md 之间互相引用的相对链接,一旦文件改名或移动,链接就断了,肉眼很难发现。这类工具能批量扫出来,属于“平时用不上,用上就救命”的类型。 ### 5.3 装多了预览冲突，怎么快速定位 多个扩展同时想接管 Markdown 预览时,表现通常是:预览样式突然变了、某些语法不渲染了、或者干脆打开是空白。排查方法有个固定的套路: 先禁用最近安装的那个扩展,重开预览看是否恢复。恢复了就锁定嫌疑,再去查它的设置项。没恢复就继续往前倒,直到找到为止。 批量排查时更快的方式是用“扩展配置文件”机制:创建一个只启用核心扩展的配置,对比默认配置下的预览表现,能快速缩小区间。如果实在找不到,还有一个兜底手段:命令面板搜 `Developer: Reload Window` 重载窗口,有些扩展的状态是加载时才初始化的,不重载看不出问题。 需要提醒的是,预览变空白时不要第一时间怀疑“文件坏了”。先随便新建一个只有一行 `# 标题` 的 md 文件试试预览——新文件正常,问题就在原文件的语法或路径;新文件也不正常,问题就在扩展或全局设置。这个对照实验能省掉大量瞎猜。 ## 6. 一次读一堆 md：只读模式、多标签与跨文件检索 实际工作里很少有“只读一个 md”的情况,更常见的是接手一个文档目录,几十个文件要快速过一遍。这时候的操作策略和读单文件完全不同。 ### 6.1 防误改：只读与预览标签的区别 读别人文档时最怕手滑改了一个字符还保存了。两层防护: 一层是编辑器层面的“预览标签”(斜体标签,`workbench.editor.enablePreview`),它防的是标签爆炸,不是误改,别混淆。另一层是文件系统层面的只读属性,给文件加上只读位之后,VS Code 里编辑会提示“文件是只读的”,保存会被拦下。这个更可靠,尤其适合那种“必须看一眼但不能动”的归档文档。 如果只是临时读,不想改文件属性,还有个轻量办法:打开文件后不要保存。听起来废话,但配合 `files.autoSave` 关闭,误改的风险会小很多。自动保存默认在一些配置下是开启的,读文档前扫一眼设置,别等改坏了才发现。 ### 6.2 跨文件检索比逐个打开高效 几十个文件逐个打开看标题,是最低效的方式。正确姿势是先全局搜索: `Ctrl+Shift+F` 打开搜索面板,输入关键词,右边会列出所有命中位置和所在文件,点结果直接跳到对应行列。这个操作比“打开文件—翻找—返回”快一个数量级。 搜索时有个实用技巧:开启“仅搜索 md 文件”的过滤,在搜索框下方的 `files to include` 里填 `*.md`。文档仓库里往往混着代码、配置、日志,不过滤的话噪音很大。 另一个高频需求是找“哪些文件提到了某个接口或某个配置项”。这种情况用正则更准,搜索面板支持正则模式,比如匹配被反引号包起来的词,能大幅减少误命中。不过正则别写太复杂,排查成本会超过收益。 ### 6.3 超大文件的性能边界 最后说个容易被忽略的情况:单个 md 文件大到几 MB 时,预览会明显卡顿,滚动掉帧,甚至出现渲染不完整。 原因是预览要把整篇文本一次性解析成 HTML 再交给视图渲染,节点数量上去之后,浏览器的排版压力会很大。表格特别多、图片特别多的文档,这个门槛会更低。 应对办法有两个方向。一是拆文件:把几 MB 的文档按章节拆成多个文件,用一个索引文件链接起来,既解决性能问题,也让后续维护更容易。二是读的时候不打开预览:纯源码视图的性能瓶颈低得多,配合折叠把不关心的章节折起来,几千行也能流畅滚动。 如果确实需要在大文件里定位,用大纲或者 `Ctrl+Shift+O` 跳转,比滚轮快,也不受渲染性能影响。这是我处理超大文档时的默认手法——不打开预览,只在大纲和源码之间跳。 再补一个实际操作中的体会:md 文件的阅读体验,八成取决于文档作者写不写空行、标题层级规不规范、图片路径是不是相对路径。作为读者,你能调的只有字号、行宽和折叠;作为作者,你多写一个空行,后面所有人的阅读成本都会降低一点。我改别人文档时有个习惯,顺手把缺的空行和错位的标题层级补上,花不了几分钟,但下次自己再打开会舒服很多。