企业官网建设流程全解析

1. 别急着关，先看清楚VSCode里那根小黄线到底是什么

如果你用VSCode写过Markdown，大概率碰到过这种情况：正文里莫名其妙出现黄色波浪线，或者整行文字下面压着一条黄色直线，光标移过去还弹出一行英文提示。很多人第一反应是编辑器坏了，或者干脆去设置里把所有检查项全关掉——结果问题没解决，真正有用的语法提示也没了。

先说结论：VSCode里Markdown相关的小黄线，来源通常不是同一个。最常见的有三类，处理方式完全不同。

1. markdownlint插件提示：这是黄色波浪线或黄色直线的主力来源。它按照一套Markdown规范规则检查文档，一旦发现你的写法不符合规范（比如行尾有多余空格、标题层级跳级、列表符号不统一），就在对应位置画线。

2. 内置拼写检查（cSpell插件）的拼写波浪线：如果你装了Code Spell Checker这类插件，它会把中文、英文混排文档里的“非词典词汇”全部标出来。写中文文档时，整篇几乎全是黄线，非常闹心。

3. VS Code自带的Markdown语法校验：这类线通常比较“克制”，只在真正语法错误时出现，比如代码围栏没闭合、引用块格式错乱。这种线其实不建议关，它能在渲染前帮你发现硬伤。

不同来源的小黄线，关闭方法完全不一样。如果一上来就乱关一气，往往是把真正有用的规则关掉了，该出现的线照样在。下面我按“先判断来源，再精准处理”的思路，把每一步讲透。

还有一类情况要提一下：有些人装的插件比较多，比如Markdown All in One、Markdown Preview Enhanced、markdownlint这些捆绑安装，各个插件都可能带自己的警告样式。你看到的“小黄线”可能是好几股势力叠加的结果。所以第一步一定是先定位，再动手。

鼠标点一下有黄线的那一行，看底部状态栏或悬停提示里显示的插件名，这是最快的判断方式。如果悬停提示里写了类似“MD009/no-trailing-spaces”这样的编号，那就是markdownlint；如果写着“Unknown word”或者一堆建议拼写，那就是拼写检查。定位清楚了，后面的操作才有意义。

2. 去掉markdownlint的小黄线：不同需求，不同切除方案

markdownlint是VSCode里给小黄线“贡献”最大的插件，它默认开启了绝大部分规则。很多人在网上搜“去掉小黄线”，搜到的教程基本都指向这个插件。但这里有个差异要说清楚：你是想彻底关闭所有规则，还是只想关掉某几条烦人的规则？

2.1 只想写文档，不想看到任何规则提示

如果你写Markdown纯粹是为了记录笔记、写README，不需要遵循严格的规范，那最省事的办法是在配置里把markdownlint整体关闭。

打开VSCode设置（快捷键Ctrl + ,），在搜索框里输入markdownlint，找到“Markdownlint: Enabled”这个选项，把勾去掉。这一步对当前用户全局生效，所有工作区的Markdown文档都不会再出现markdownlint的黄线。

如果你想对单个项目生效，不想影响全局设置，就在项目根目录建一个.vscode/settings.json文件，写入：

{ "markdownlint.enabled": false }

这样只有这个项目会关闭规则，换到别的项目时一切照旧。我的习惯是全局保持开启，只有个别很乱的历史文档项目里单独关掉，这样既能保持日常书写的规范意识，又不会被存量问题烦到。

2.2 只想关掉某几条规则，保留其他提示

大部分人对小黄线并不是深恶痛绝，只是觉得某些提示太“教条”。比如很多人写中文技术文档，喜欢在标题前后留空行、段落之间用一个空行分隔，但markdownlint的MD012（多个连续空行）规则会提示“Multiple consecutive blank lines”；再比如你用---做分隔线，它可能会提示MD013（行太长）或者MD022（标题前后需要空行）。

这种情况下，正确的做法是“定向关闭”，而不是全关。按Ctrl + ,打开设置，点击右上角的“打开设置(JSON)”图标，在settings.json里加一个配置块：

{ "markdownlint.config": { "MD012": false, "MD013": false, "MD022": false, "MD032": false } }

这里的MD012、MD013、MD022、MD032都是规则编号。关闭之后，这几条规则不再画线，其他规则照常工作。

2.3 按场景自定义规则：推荐一份我常用的配置

如果上面的方式你还是觉得麻烦，或者想一步到位减少黄线，可以直接套用下面这份配置。这套配置是我根据自己写中文技术博客、README、项目文档的习惯踩坑后总结出来的，基本能消除90%以上的无意义黄线，同时保留真正有价值的提示。

{ "markdownlint.config": { "MD012": false, "MD013": false, "MD022": false, "MD024": false, "MD032": false, "MD033": false, "MD036": false, "MD041": false } }

各条规则的含义如下：

注意：这份配置只对markdownlint生效，其他插件产生的小黄线不归它管。如果你关掉这些之后还是有黄线，继续看下面第三节的内容。

这里再补充一个经验：建议不要一次性把所有规则全关掉。真正常见的、低风险的语法问题（比如代码围栏没闭合、引用块标记缺失）还是需要markdownlint帮你盯着的。按需关掉那几条让你觉得“烦”的规则，比一刀切更合理。

3. 直击另一大元凶：拼写检查插件的中文黄线困扰

很多人弄完markdownlint之后，发现黄线还在，而且分布非常密集——几乎每个中文字符下面都有。这种情况基本可以断定是拼写检查插件在“刷存在感”。

VSCode上最常见的拼写检查插件是Code Spell Checker。它的工作逻辑很简单：把文档里的每个单词拿去和内置词典比对，不在词典里的就标出来。对中文用户来说，问题很明显——整篇文档几乎全是“不在词典里”的词汇，于是全线飘黄。

3.1 判断是不是拼写检查插件的线

方法很简单：把光标移到黄线上，看悬停提示。如果显示的是类似“Unknown word: 你好”这样的内容，或者建议你“Add to dictionary”，那基本就是拼写检查没跑了。

还有一个判断技巧：看黄线的形状。markdownlint的黄线通常是直线或波浪线，而拼写检查插件的线一般是波浪线，而且密集度极高，几乎每个词下面都有一截。如果你写的是英文文档，这种提示是有用的；如果你写的是中文文档，这种提示就是纯粹的噪音。

3.2 关闭Code Spell Checker对中文的支持

不推荐直接卸载插件或全局禁用，因为你在写英文文档时它还是能帮你发现笔误的。正确的做法是让它“无视中文”。

打开设置，搜索cSpell，找到C Spell: Enabled Language Ids（或者直接编辑settings.json），把markdown从这个列表里移除。这样它在Markdown文档里就不会再做拼写检查，但你在写代码注释、纯英文文档时它仍然有效。

如果你用的不是Code Spell Checker，而是别的拼写检查插件，处理思路是一样的：找到插件的语言启用配置，把markdown排除掉，或者把中文加入“忽略语言”。

3.3 彻底解决中文文档的黄线：忽略中文场景的配置示例

如果上面的方式对你来说还是太麻烦，或者你希望一劳永逸，可以直接在settings.json里把中文相关的检查关掉：

{ "cSpell.ignoreWords": [ "的", "了", "是", "我", "你", "他", "这", "那" ], "cSpell.languageSettings": [ { "languageId": "markdown", "includeRegExpList": [ "/[一-龥]/" ], "enabled": false } ] }

这里的/[\u4e00-\u9fa5]/是中文Unicode范围，意思是“在Markdown文档里，如果匹配到中文字符，就不做拼写检查”。这样设置之后，中文内容不会再触发黄线，英文拼写错误依然会提示。

注意：这个方案关闭的是“拼写检查在Markdown文档中的中文检查”，不是关闭整篇文档的拼写检查。英文拼写错误还会提示，个人觉得这是比较合理的状态。

3.4 如果用的是其他检查插件，怎么处理

VSCode生态里还有不少带“检查”功能的插件，比如Markdown All in One、markdownlint会和一些Lint工具联动。有些人装了一整套“Markdown增强包”，导致黄线来源不止一个。

建议按这个顺序排查：先看悬停提示里的插件名，然后在VSCode的“扩展”面板里搜索这个插件名，进入插件的设置项，通常都会有一个enabled或者类似的总开关。如果你分不清是哪款插件，还有一个笨办法：在扩展面板里逐个禁用插件，每次禁用后回到Markdown文档看黄线是否消失，用二分法快速锁定来源。

这个方法虽然原始，但排查效率很高。我遇到过的情况是三个插件叠加：markdownlint提示了几条、cSpell提示了一大堆、还有一个表格格式化插件在表格里画线。逐一排查后才搞清楚每一根线的来源。

4. 编写Markdown时的其他“线”：格式校验和渲染效果

除了上面提到的两类主要来源，还有一些不常见但很迷惑的情况，也顺便说清楚。

4.1 VSCode内置的Markdown语法校验

VSCode本身对Markdown有一定的基础校验能力。当代码围栏没有闭合、列表缩进异常、引用块内容格式不对时，它会在对应位置画线。这类黄线我是不建议关闭的，因为它是Markdown渲染前的“语法警察”，能帮你发现真正的硬伤。

举个例子，如果你写了：

```python print("hello")

第二个代码围栏少写了一个反引号，VSCode内置校验会在这个位置画一条线，但Markdown渲染时可能不会报错——这就导致你的文档“看起来能用，渲染出来却乱了”。这种情况只有内置校验能帮你抓出来。

如果实在想关闭，可以在settings.json里加：

{ "markdown.validate.enabled": false }

不过真心不建议这么做，这条线出现的频率很低，而且每次出现都意味着文档有实际问题。

4.2 表格格式化插件引起的黄线

有些表格插件（比如Markdown Table Prettifier）会在表格格式不规范时画线。这类线的特征是集中在表格区域，提示内容一般是“列宽度不一致”或者“表格缺少分隔行”。

如果你担心格式化插件干扰表格编辑，可以在设置里关掉自动格式化，改成手动触发。我自己的做法是：写表格时让插件自动整理，但它画线时用Ctrl + Shift + P手动执行一次“Format Document”，让表格恢复正常格式，黄线自然消失。

4.3 还有一类“隐藏线”：编辑器自带的“波浪线”是来自语言服务

除了上面说的，还有一种线来自VSCode的“语言服务”。对Markdown来说，通常是链接引用或图片路径校验。比如你写了一行![图片](./images/foo.png)，但foo.png这个文件不存在，有些插件会画线提示。

这种提示在写文档时其实挺有用的，它能帮你提前发现图片路径写错的问题。如果你不需要这种提醒，可以在设置里搜索markdown相关的链接校验选项，把它关掉。但我个人强烈建议保留，图片路径错误是Markdown文档里非常隐蔽的错误，渲染时不报错，发布后图片全挂。

这里顺带说一下排查这类线的方法：点击有线的位置，看悬停提示里的内容。如果是关于“file not found”或“路径不存在”的提示，基本就是链接校验类插件；如果是语法错误，则是内置校验；如果是规范提示，就是markdownlint。每种提示都有自己的“性格”，多看一眼悬停提示，比乱猜省事得多。

4.4 黄线和红线的区别

这里再补充一个基本概念：VSCode里不同颜色的线代表不同的严重程度。通常来说：

• 红色波浪线：语法错误或致命问题，比如代码围栏不闭合
• 黄色波浪线：警告或规范问题，比如markdownlint的规范提示
• 蓝色/绿色线：信息提示，比如cSpell的拼写建议
• 紫色/灰色线：弃用或过时内容

很多人分不清红线和黄线，就把所有线都关掉了。其实红线是“必须处理的错误”，黄线是“建议优化的问题”。在关黄线的时候，最好保留红线提示，否则文档里存在真正的语法错误时你都不知道。

5. 常见问题排查速查表：10个典型场景一次性说清

这一节把实际使用中碰到的问题和对应解决方法整理成一张速查表，方便你按图索骥。

5.1 问题速查表

5.2 排查思路详解

如果你看到这里，发现自己的问题不在表里，那就按下面的思路自己排查：

第一步，用鼠标点击黄线所在位置。悬停提示会告诉你这条线的来源和具体原因。大部分情况下，提示内容里会带有规则编号或插件名称，这是最直接的线索。

第二步，根据提示内容判断来源。如果带“MD”前缀，就是markdownlint；提示“Unknown word”，就是拼写检查；提示“Cannot resolve file”，就是链接校验插件。

第三步，单点修复。针对单条规则，用前面说的markdownlint.config或插件设置做定向关闭，而不是全局关闭。

5.3 一个容易踩的坑：改完配置不生效

很多人按教程改完settings.json，发现黄线还在，以为方法没用。这里要注意：VSCode的部分配置修改后需要重新加载窗口才能生效。

配置保存后，按Ctrl + Shift + P，输入Reload Window，回车执行。VSCode会重新加载整个窗口，配置这时才会生效。另外，修改settings.json后，有时即使没重载窗口，新配置也会对后续打开的文件生效，但已经打开的文件可能不会立即刷新。这时候重载窗口是最稳妥的。

还有一个细节：如果你的项目根目录下有.vscode/settings.json，它和用户全局settings.json是叠加生效的，项目配置优先级更高。如果你在项目配置里开着某些规则，全局配置里关了，那项目里依然会画线。这种情况需要检查一下项目配置文件。

5.4 全局配置和项目配置怎么选

写到这儿，顺便聊聊全局配置和项目配置的取舍。

全局配置（按Ctrl + ,打开的设置）适合放一些你个人习惯相关的规则，比如行宽、语言风格、是否启用某些插件。项目配置（.vscode/settings.json）适合放项目特定的规则，比如团队统一要求的Markdown规范。

举个例子：如果你个人写博客时不喜欢MD013的行宽限制，但公司项目要求每行不超过80字符，那就在全局配置里关掉MD013，在项目配置里打开并设置80字符限制。这样互不干扰。

如果你的项目是团队协作项目，建议把配置提交到版本库。这样组员Clone下来之后，所有人在同一个Markdown规范下工作，黄线的标准也一致。这一点对开源项目尤其重要——我看过不少开源项目的PR，因为Markdown格式不统一，review时黄线满屏飞，非常影响效率。

6. 我的最终推荐配置与日常用法

说了这么多，最后给出一份我目前正在用的完整配置，以及日常书写Markdown时的一些习惯。你可以直接复制过去用，也可以根据个人偏好做微调。

{ "markdownlint.config": { "MD012": false, "MD013": false, "MD022": false, "MD024": false, "MD032": false, "MD033": false, "MD036": false, "MD041": false }, "cSpell.enabledLanguageIds": [ "typescript", "javascript", "python", "json", "yaml" ], "markdown.validate.enabled": true }

这份配置做的事很清晰：

• markdownlint：关闭8条最容易误报的规范，保留其他规则；
• cSpell：只对几种代码文件生效，不在Markdown里做拼写检查；
• markdown.validate：保持开启，保留VSCode内置的语法校验。

使用之后，写Markdown时的黄线数量会大幅下降，剩下的基本都是“真有语法问题”或者“规范确实需要调整”的情况。我个人用了这套配置大半年，写文档基本是干干净净的，偶尔出现的黄线基本都能一眼看出问题所在。

再说一个使用习惯：不要在文档写完之后一次性处理黄线，而是边写边看。写完一个段落，扫一眼有没有新增的黄线，有就顺手改掉。这样做的好处很明显：你始终知道当前文档的状态，不会出现写完全篇再回头改的大工程。

另外，有些人是“被迫”打开markdownlint的，因为在公司项目里，CI阶段会跑Markdown格式检查。这种情况下，建议在本地开发时就把规则打开，跟着黄线走，每写完一段就修正格式。这样做虽然前期麻烦一点，但提交代码时完全不会有格式报错，整体效率反而更高。

最后补充一个很多人忽略的点：VSCode的命令面板里，输入Markdown: Open Preview to the Side可以实时预览渲染效果。写文档时保持“编辑区+预览区”左右分屏，很多黄线你不需要看提示，光看预览就知道格式对不对。这个方法对新手特别友好，能直观理解每条规则存在的意义。