1. 大纲不是“结构图”，而是长文档的导航仪
先聊一个我自己的场景：有一次要给团队写一份上万字的技术方案，文档里堆了几十个二级标题、上百个三级小标题。写到后半段的时候，我想回看开头某个章节的结论，要么用鼠标滚轮在长页面里滑半天，要么开两个编辑器来回找，效率低到让人抓狂。后来我养成一个习惯——写任何超过两屏的 Markdown 文档之前，先把左侧大纲打开，把它当成整个文档的导航地图。
vscode 对 Markdown 的支持其实是很“原生”的，大纲功能并不是某个插件单独提供的，而是编辑器自带的一部分。你只要把文件后缀存成.md或.markdown，再用 vscode 打开，大纲面板就会识别文档里的各级标题，把它们整理成树状结构。所谓大纲，本质就是文档里#、##、###等标题的索引列表，你点击任意一条，编辑器光标就跳到对应标题的位置。
这个功能最适合谁呢？我觉得是这么几类人：一个是像我这样爱写技术方案、接口文档、教学笔记的人，文档一长就找不到北；另一个是编辑、自媒体作者，在 vscode 里写 Markdown 文章，需要随时观察文章结构有没有断裂；还有一个是刚刚接触 vscode 和 Markdown 写作的新手，提纲挈领地理解“标题即结构”这个理念，比死记语法有用得多。
需要注意的一点是：大纲视图不负责“生成”任何新内容，它只是把文档中约定的标题结构可视化地呈现出来。如果你在文档里用了很多**加粗**或者- 列表项，却没有任何标题，那么大纲面板里基本是空的。理解了这一点，后面咱们聊的很多“为什么大纲不显示”“为什么大纲里少了某条”的问题，就都能顺着这条线索找到答案了。
2. VSCode 内置大纲视图：从打开面板到跟踪光标
2.1 打开大纲的三种姿势
第一种，菜单路径：顶部菜单栏点“查看（View）”，找到“打开视图（Open View...）”或“外观（Appearance）”下的“面板（Panel）”选项，展开后能看到“大纲（Outline）”列表项，点击即可调出大纲面板。不同版本的 vscode 菜单位置可能有细微差别，但关键词都是“大纲/Outline”，稍微找一下就能看到。
第二种，命令面板：按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS）呼出命令面板，输入“大纲”或者“Outline”，找到“视图：聚焦大纲视图（View: Focus on Outline View）”之类的命令。选中执行后，大纲面板会出现在侧边栏并且自动获得焦点。
第三种，快捷键直达：把视图菜单里的“大纲”拖到自己的快捷键方案里，或者直接在设置面板配置outline相关快捷键。我个人习惯把Ctrl+K Ctrl+O绑定为打开大纲视图，这样写文档的时候随时可以呼出，不需要把手从键盘移到鼠标上。
打开之后，大纲出现在左侧活动栏的次级面板里。文件结构视图和 Markdown 标题的大纲视图是两个不同的维度：前者展示的是目录和文件名，后者展示的是文档内部标题层级。刚开始用的时候很容易混淆，但只要记住“大纲只对当前打开的 Markdown 文档生效”就行了。
2.2 大纲面板上的几个关键按钮
大纲面板的标题栏右侧有一个...按钮（更多操作），展开后可以看到几个关键开关，我建议你逐个试一遍：
- 跟踪光标（Tracking）：打开后，编辑器光标所在的标题，会在大纲面板里高亮显示。这个对大文档特别友好，你滚动或跳转时，能一直知道自己“读到了哪里”。
- 自动折叠（Auto-collapse）：开启后，大纲面板会默认只展开当前层级路径，其他层级全部收起来。文档结构特别深的时候，这个开关能救你一命，否则几十个三级标题一次性摊开，视觉上又是一场灾难。
- 问题指示（Problems）：vscode 会把 Markdown 文档里的某些“问题”也映射到大纲中，比如引用失效、无效锚点等。默认是开启的，如果你觉得指示太吵，可以在设置里关掉。
- 图标（Icons）：决定大纲项前是否显示标题级别图标。我个人习惯保留，因为一眼就能看出
#和###的层级关系。
这些开关的背后是 vscode 的outline.*配置项，你可以直接在设置里搜索outline，会看到一整套参数。比如outline.showCursor、outline.followCursor、outline.collapseItems、outline.problems.enabled、outline.icons等。想精细化控制的人可以直接改设置 JSON，但我日常用下来，默认配置再手动打开“跟踪光标”就够了，不需要过度折腾。
2.3 配合快捷跳转符号（Ctrl+Shift+O）提高效率
大纲面板负责“看整体结构”，而快捷跳转负责“快速定位到具体某一条”。在 vscode 里，Ctrl+Shift+O（macOS 是Cmd+Shift+O）可以打开“转到文件中的符号（Go to Symbol in File）”弹窗，它会列出当前文档所有标题、函数名等符号。在 Markdown 文档里，这里显示的就是全部标题，而且支持模糊搜索。
我常用的套路是：先Ctrl+Shift+P呼出大纲面板，扫一眼当前结构的层级关系；然后Ctrl+Shift+O输入关键字跳转到具体章节。比如我在一篇两万字的方案里要找“容灾设计”这一节，只需要敲几个字，弹窗里立刻就能过滤出来，回车即达。这个体验比用鼠标滚轮翻页舒服太多了。
另外，vscode 的面包屑导航（Breadcrumb）也值得开一下。默认breadcrumbs.enabled是开启的，编辑器顶部会显示文件名 > 一级标题 > 二级标题的路径。借助这个路径，你可以快速看清当前光标所在的嵌套层级，也能通过点击面包屑中的某一层，直接跳回对应的上级标题。
3. 大纲认什么：Markdown 标题层级与解析规则
3.1 什么内容会出现在大纲里
大纲面板的内容来源是“符号（Symbol）”，而 Markdown 文件中的符号主要由标题构成。也就是说，你写的#到######这六级标题，都会按层级出现在大纲里。除此之外，markdown 中的某些特殊语法也可能被 vscode 识别为符号，比如这种带 alt 文字的图片？实际测试下来，vscode 对图片、链接、代码块的处理很保守，一般情况下它们不会出现在大纲里，避免干扰标题结构。
这里有个容易被忽略的点：标题必须另起一行并独占一行。像下面这样写：
# 这是一个标题 # 后缀 ## 这是一句混在段落里的“伪标题”第一种，标题和#在同一行，结尾的#只是纯文本，vscode 能正确识别为一级标题；第二种，如果##前面是普通文字，它就不是标题，而是一段文本里的井号字符。很多新手把“看起来像标题”的文字排进正文段落，结果大纲里怎么都找不到，原因就在这里。
另外，标题里如果用了代码片段的反引号，比如# 如何使用 \code` 功能，这在大纲里也能正常显示，因为标题结构本身是正确的。但要注意：某些插件会额外解析标题里的特殊字符（比如$` 数学公式、HTML 标签），一旦解析出错，标题可能就不会出现在大纲里。遇到这种情况时，我建议先临时把标题里的特殊字符删掉再测试，定位到具体是哪个符号触发的。
3.2 标题级别、代码块里的井号、段落符号
有些人在 Markdown 文档里有大段代码块，代码块里恰好也有以#开头的行。vscode 的 Markdown 解析器会正确处理被代码块包裹的内容，不会把它们当成标题。所以你在大纲里基本不会看到代码注释里的# 某某注释被错误识别。这个机制在大多数情况下是可靠的，但如果你用了一些非常规的 Markdown 扩展语法，比如“空白标记 + 标题”组合，解析器可能会出问题。
还有一种情况：标题里只有井号没有文字，比如#单独一行。vscode 会把它当作一个“空标题”显示在大纲里，点击跳转到那一行。虽然不报错，但建议别这么写，因为空标题在大纲里会显得很突兀，而且破坏了标题层级语义。
标题的层级关系还有一个排序逻辑：大纲面板默认按文档中出现顺序排列，不会自动按“级别大小”重排。也就是说，如果你先写## 二级标题，再写# 一级标题，大纲里会按实际出现顺序显示，一级标题并不会自动“跑”到二级标题前面。这点和目录生成插件的排序方式略有不同，别混淆。
3.3 中文标题、标题编号和锚点的处理
很多中文写作场景里，标题会自己带编号，比如“一、背景”“1.1 项目概述”。vscode 的大纲视图对中文标题支持很好，直接显示原样文字，不会因为编号格式乱掉。而且标题如果带了 HTML 锚点属性（比如## 背景 {#background}），大纲里显示的是背景 {#background}还是一般的背景，不同版本 vscode 处理方式略有差异。我自己一般不在标题里加锚点，因为普通 Markdown 的跳转够用，加锚点反而让大纲文字变啰嗦。
关于标题编号，vscode 内置大纲默认不会自动生成数字编号，但可以通过安装插件实现（下一章详细说）。这里强调一点：如果你用 Markdown All in One 这类插件给标题自动加了 “1.1”“1.2” 之类的编号，大纲里会显示这些编号，看起来很有条理；但一旦你删掉插件，这些编号会是纯文本留在标题里，大纲也会显示它们，并不会自动清除。
4. 不想装太多插件？先用好 Markdown All in One 的标题编排
4.1 插件到底给大纲做了什么
很多教程会把“显示大纲”归功于某个插件，这是不准确的。vscode 自带的大纲视图已经能显示标题树，插件更多是提供“辅助”作用。其中最常见的是Markdown All in One，安装量很大，功能包含自动编号、生成目录（TOC）、快捷键（加粗、斜体、跳转等）、列表缩进等。
从大纲视角看，这个插件最有用的能力是“给标题编号”和“生成文档内目录”。注意，这里的“目录”是插入到文章正文里的一段[TOC]或结构化列表，它和大纲侧边栏是两回事，但体验目标高度一致——都是让读者快速了解文档结构。
如果你既想用大纲面板看整体结构，又希望正文里有一个“可选中的目录页”，那么 Markdown All in One 很值得装。我个人最常用的是它的“更新目录（Create/Update Table of Contents）”命令：按下Ctrl+Shift+P，执行“Markdown All in One: Create Table of Contents”，插件会在文档顶部插入一个目录列表，自动根据标题层级生成嵌套项目。标题改动后，再执行一次命令就能刷新目录，非常方便。
4.2 用插件给标题编号，让大纲更有层次
Markdown All in One 有一个“Add/Update Section Numbers”命令，能自动把文档标题改成带序号的形式，比如：
# 1 Hello ## 1.1 引言 ## 1.2 环境准备 # 2 安装 ## 2.1 Windows加了编号后，大纲面板里自然也会显示这些带序号的标题，层级一目了然。这个功能适合需要保持正式文档风格的人，比如写技术方案、论文初稿、操作手册。
但这些编号是“写死在标题文字里的”，不是动态渲染。如果你调整了章节顺序，需要再次执行命令重新编号，否则序号会乱。我在一个大型 API 文档项目中用过一段时间，发现最大的好处是文档和侧边栏大纲保持一致，读者截图引用某个编号时不会找错；最大的麻烦是每次调整结构都要重新跑一遍编号，而且如果文档里有多个#一级标题，编号规则可能需要自定义。后来我干脆只在正式发布前跑一次编号，平时写作还是用无编号标题，结构清爽，改动灵活。
4.3 配合折叠区域的实操
Markdown All in One 还支持折叠选中的区域：选中几个段落，按Ctrl+Alt+[或执行命令，可以把当前区域折叠起来。这个折叠是“临时状态”，不会改变文档内容。配合大纲面板里的“自动折叠”开关，你可以在侧边栏只保留一级标题，正文区只看到当前章节内容，体验很像写代码时折叠函数体。
实操上，我通常这么配：左侧大纲打开、自动折叠开启，正文尾部只保留一个章节；写哪一章就把光标切到哪一章，大纲自动高亮当前位置。配合 Markdown All in One 的标题编号，整个编辑界面会非常清爽。这个组合我没发现明显的副作用，是日常写作的主力方案。
5. 预览区带目录：Markdown Preview Enhanced 的 TOC 与 Mermaid
5.1 给预览页生成可点击目录
vscode 自带 Markdown 预览（Ctrl+Shift+V）其实也能显示标题，但默认预览界面没有侧边目录，浏览长文档时需要在正文里上下滚动。想要更好的“阅读+导航”体验，我推荐装Markdown Preview Enhanced（MPE），它能在预览区里生成一个可点击的目录树（TOC），相当于把大纲从编辑器侧边栏“复制”了一份到预览页面。
使用方式很简单：在 Markdown 文档里写一行[TOC]，MPE 会在预览时把它渲染成一个目录列表，列出当前文档的所有标题。目录会放在文章里你写[TOC]的位置，点击任意目录项，预览页面就会滚动到对应标题。很多人在分享文档前会用这个功能生成一个“文章导读”，读者也能先看目录再决定读哪一部分。
需要注意的是，[TOC]是 MPE 的扩展语法，不是标准 Markdown 的一部分。如果换回普通 vscode 预览，这行代码只会显示为一行文本[TOC]，不会自动渲染成目录。所以“要不要把[TOC]写进文档”要跟团队统一口径，我自己的做法是：直接在文档里写<!-- @import "toc" -->或者干脆不写进正文，用 MPE 预览面板的“大纲”按钮（在预览区域右上角）来控制目录展示，这样不污染 Markdown 源文件。
5.2 同时启用 Mermaid 图表支持的体验
“markdown preview mermaid support”是目前搜索 Markdown 相关热词里出现频率很高的一个组合。MPE 插件支持 Mermaid 语法，可以在 Markdown 里嵌入各类图表，比如流程图、时序图、状态图。配合 TOC，一份文档既能看结构，也能看图，适合做技术方案、架构设计笔记和培训材料。
用法是在 Markdown 文档里写：
```mermaid graph TD A[开始] --> B{条件判断} B -- 是 --> C[执行] B -- 否 --> D[退出] ```MPE 预览时会把这段代码渲染成图形。由于它本身也是 Markdown 代码块，vscode 大纲不会把它识别成标题，所以不会干扰大纲视图。这里有个容易踩的坑：如果同时安装了多个 Markdown 预览插件（比如 Markdown Preview Enhanced 和 Markdown Preview Github Styling），它们的预览快捷键会互相冲突，导致 Mermaid 图表要么不渲染、要么显示成纯代码文本。解决方法是禁用不常用的预览插件，只保留一个，或者通过 MPE 自己的“打开预览”命令来启动预览。
5.3 TOC 配置参数：缩进、列表样式
MPE 的 TOC 不只是一个[TOC]占位符，它支持一系列配置参数，方便控制目录展示效果。你可以在文档的 YAML front-matter 里定义toc相关字段，也可以在预览面板的设置里调整。常见参数有：
depth：控制目录显示到第几级标题，我一般设置depth: 3，避免把六级标题都列出来。tight：是否紧凑显示，默认true，目录项间距小，更像一个侧边导航。ordered：是否生成有序数字列表（1. 1.1 这样的数字序号），看需求设置。
如果是用[TOC]占位符，还可以在下一行配合<!-- toc -->注释，让 MPE 在预览时自动把目录渲染在指定位置。实际使用中，我发现depth参数最实用——文档太长时，只显示前三级标题能让目录不至于过密。
6. 大纲不显示/显示不全的排查链路
6.1 第一反应：检查视图和文件类型
很多人在群里问“为什么我的 vscode 大纲不显示”，我第一个问题通常是：你的文件是 Markdown 格式吗？如果文件后缀是.txt或.md但被某个插件接管了语法高亮，vscode 可能没把它识别成 Markdown，自然不解析标题。
排查顺序我建议这样：先在编辑器右下角看当前语言模式，确认是 “Markdown”；如果没有，按下Ctrl+K M手动切换语言为 Markdown。然后再看大纲面板是否真的存在——如果左侧根本没有“大纲”这个面板，需要用上一章的方法把它调出来。最后，确认当前窗口是否只打开了一个 Markdown 文件，因为大纲面板默认只显示当前活动编辑器的大纲，你如果同时开了多个.md文件，必须点击目标文件让编辑器获焦，大纲才会刷新。
还有一个很容易踩的坑：大纲面板显示的是“符号大纲”，不是“文件大纲”。如果你打开的是一个.json或.js文件，面板里显示的可能是变量名、函数名，而不是标题。这不是bug，说明当前文件类型不匹配。
6.2 结构问题：标题被代码块或嵌套列表“吃掉”
文件类型没问题、大纲面板也开了，但大纲里只有一两行，其他标题都找不到，这时候基本可以断定是文档结构解析出了问题。常见原因有三类：
第一类，标题行前面有非空白字符。比如你写了这是说明 # 标题名，那么这个#只是普通文本，并不会被识别。检查一下标题行开头有没有不小心输入的缩进、空格以外的字符。
第二类，标题被错误地包进了代码块。比如你写了三个反引号但没闭合，或者某个缩进块刚好把# 标题吸进了列表或引用块。vscode 的 Markdown 解析器对“代码围栏”很敏感，只要反引号不配对，后续所有行都会被视为代码文本，大纲自然就丢失了。
第三类，嵌套列表下的“类标题”写法：
- 项目一 # 这里看起来像标题如果#前面有缩进且处于列表项内部，vscode 可能不会把它识别为一级标题，因为它不符合“标题行顶格开始”的规则。解决方法是把标题移出列表，或者用##作为列表内的同级标题（实际上也不靠谱）。我最推荐的做法：在 Markdown 里，标题应该独立成段，不要作为列表项的子内容，这样大纲、TOC、导出文档三个场景都不会出问题。
6.3 性能与大文件：几万行 Markdown 怎么办
另一个较少人遇到但一旦遇到就头疼的问题：文档行数特别多，比如几万行的技术手册，大纲可能变得非常卡顿，或者标题更新不及时。vscode 的符号解析是运行在后台的，大文件会占用内存和 CPU，某些低配机器上会出现“大纲转圈圈”的现象。
应对策略有几个：一是把过大的 Markdown 文档拆分，比如按章节拆成多个文件，用 MPE 的“文件合并”或导入功能在预览时组合；二是调整 vscode 的search.followSymlinks、files.watcherExclude等性能设置，减少后台文件监听负担；三是给大纲面板右侧的“自动折叠”打开，减少渲染节点数量。我自己测试过，单个 Markdown 文件超过 5000 行时，大纲仍然能用，但超过 10000 行后，每次切文件会有明显延迟，拆文件是更舒服的方案。
6.4 实在不行就重置窗口：常见插件冲突
如果结构检查都做了，文件也不大，大纲还是不显示，那么问题大概率出在插件冲突上。比如你同时安装了 Markdown All in One、MPE、某个“Markdown Edit”美化插件，不同插件可能会抢占 Markdown 文档的解析控制权，导致 vscode 内置大纲“失聪”。
排查方法是：按Ctrl+Shift+P，执行“开发人员：重新加载窗口（Developer: Reload Window）”，先看是否临时恢复；如果还不行，就禁用大部分第三方 Markdown 相关插件，只保留 vscode 内置功能，再一个个启用，找到冲突源头。这个方法繁琐，但非常有效，我靠它排查出过一次“MPE 和 vscode 内置预览互相抢占快捷键”的问题。
7. 我写长文和技术笔记时的大纲使用习惯
7.1 先列大纲再填充内容
现在写任何超过 2000 字的 Markdown 文档，我都习惯先只列标题，把所有需要覆盖的章节写在稿子里，形成一版“草稿大纲”。这时候左侧大纲面板会瞬间给我一种“文章骨架已经立起来了”的感觉。骨架稳定后，再逐章填充正文。这个习惯帮我避免了很多写作中途跑偏、写到最后发现漏掉关键章节的问题。
不要小看这一步：大纲其实是全文的逻辑地图。一旦地图画好，填充内容就变成了“按图索骥”，每写完一个标题，在大纲里把它折叠掉，视觉上就会形成一个“已完成清单”，特别有成就感。
7.2 固定标题层级规范
多人协作写文档时，大纲能不能用得顺畅，取决于大家是否遵守统一的标题层级规则。我们团队内部的约定是：
- 一个文档只允许有一个一级标题，作为文档总标题；
- 二级标题是“章节”，三级标题是“小节”，四级标题是“更细的内容块”；
- 不允许跳级，比如不能在
## 章节下直接写#### 四级标题，必须补三级标题； - 代码块、表格、图片不要作为标题的唯一内容，标题必须能表达“这一段讲什么”。
这些规则不写进任何官方文档，但执行起来之后，大纲视图、MPE 的目录、Word 导出时的标题层级都变得非常干净。
7.3 用大纲快速回到“上下文”
写作过程中，经常需要从一个章节跳到另一个章节去引用数据。如果只靠滚动，大概率会迷失。我一般会开着大纲面板，配合“跟踪光标”，跳到目标章节后再写几笔，然后又快速跳回来。这个过程中大纲面板一直充当“上下文切换器”，比文件标签页切换更直接。
人体对“位置感”的需求在文字工作里同样是存在的——光标所在位置在大纲树上的坐标变化，会帮助我们建立“当前写到哪一层”的认知。这比单纯靠滚动条判断进度要精确得多。
7.4 一个提升效率的小技巧：文本编辑器中的“大纲拖拽”
这是我自己摸索出来的，未必适合所有人：在某些版本的 vscode 中，大纲面板的标题项支持拖拽——把某个标题拖到另一个标题下方，正文中的标题位置也会随之改变，实现“结构化重排”。
听起来很好用，但实际体验有风险：拖拽后标题之间的正文不会跟着移动，也就是说如果你想把“第 3 章”挪到“第 2 章”前面，标题本身会移动，但段落内容不会联动。这导致我拖完标题后还得手工剪切粘贴正文，非常麻烦。所以我现在几乎不用拖拽功能，而是直接在文档里调整标题顺序，然后靠大纲面板确认调整结果。如果你想尝试，建议在小文档上先做测试，避免大文档被拖乱。
最后，如果你也在写 Markdown 长文档，我个人的建议就是：大纲面板永远开着，把“跟踪光标”打开，先用标题把骨架立起来。它不是花哨的功能，但往往是最快解决“长文档迷失症”的方法。等你养成了“先看大纲，再动笔”的习惯，会发现 Markdown 写作这层窗户纸，比想象中好捅破得多。
