vscode 里写 markdown效率差距往往不在编辑器本身而在你装了哪几个 vscode 插件、有没有把它们串成一条顺手的流水线。我从最早用 Typora 单机写稿到后来在在线 markdown 编辑器里排版再到现在把写作、预览、校验、导出整条链路全部搬回 vscode前后折腾过七八套插件组合也踩过不少坑预览里排得好好的表格导出后错位成一片、图片路径一换电脑就全挂、mermaid 流程图在预览窗口里只显示一块白板。这篇就把我长期保留的那几个插件摊开讲清楚每个插件解决什么问题、关键配置怎么写、什么场景下别用它顺带把 markdown 语法、换行、图片路径、导出 PDF 这些高频困惑一起说明白。不管你是刚装完 vscode 的新手还是写了几年技术文档的老手都能从里面挑到可以直接抄走的配置。1. 先把需求拆清楚Markdown 写作到底卡在哪很多人一上来就问装哪个插件最好这个问题本身就问偏了。插件没有绝对的好坏只有匹配不匹配你的写作场景。你如果只是偶尔记几条笔记装一堆插件纯属给自己添负担但如果你每天要产出几千字的技术文档还要交付 PDF 和 Word 版本那插件就是生产力工具值得花半小时认真配一遍。我习惯先把痛点列出来再按痛点去找工具这样选出来的东西才用得长久。1.1 三种最常见的卡点第一种是输入效率。markdown 语法本身不难但天天手打井号、星号、竖线手指是真的累。尤其是表格和列表写十个空行、对齐一堆竖线写完之后还得回头数符号有没有少一个。这类问题的解法是键盘流插件把高频语法操作绑到快捷键或者自动补全上让你写内容的时候不用分心管符号。第二种是实时反馈。markdown 是纯文本写完之前你看不到最终长什么样。预览窗口的价值不只是好看而是让你在写的过程中就发现标题层级错了、列表缩进乱了、表格列数不齐。这里还有个隐藏需求很多技术文档需要画流程图、时序图用 mermaid 语法写在代码块里如果预览器不支持那就是一堆看不懂的字符写完根本不知道对不对。第三种是交付环节。写好的 .md 文件最终往往要变成别的东西——发给同事的 Word、发给客户的 PDF、发到博客的 HTML。这一步是最容易出事的中文字体丢失、代码块不换行、图片打包不进去、目录页码对不上随便一个都能让你返工。所以导出类插件不是可选项而是必须提前配好并测试过的。1.2 我筛插件的四个硬指标市面上 markdown 相关的 vscode 插件少说上百个我一般用四个标准筛能过三关的才会长期留在插件列表里。第一看维护活跃度。打开插件页面看最近一次更新时间和 issue 的响应情况一个两年没更新的插件很可能在新版 vscode 里就已经有兼容问题了。这不是说老插件不能用而是别把核心流程押在上面。第二看有没有引入重依赖。有些插件为了导出 PDF 会自带一整套浏览器内核装完之后插件目录几百兆启动明显变慢。这类插件不是不能用而是我会把它标记成按需启用平时在扩展面板里直接禁用只在需要导出的时候打开。第三看配置能不能跟着项目走。团队协作场景下我希望规则配置存在仓库里而不是存在我个人的用户设置里。一个插件如果支持工作区级别的配置文件我会给它加很多分因为它让我的习惯变成了团队的标准。第四看和远程开发的兼容性。现在很多人是 SSH 连到服务器上写代码或者用容器、WSL 环境。有些插件依赖本地图形界面或者本地文件系统在远程环境里直接罢工。装之前想一下你的主要工作环境能省掉后面很多排查时间。提示装插件之前先执行一次扩展显示已安装扩展把用不上的先禁用。markdown 插件的功能重叠度非常高三个插件同时接管格式化最后的结果往往是互相打架。2. 写作增强类插件把键盘流打通这一类的目标很单纯让你打字的时候少抬手、少回头检查。判断标准也很简单装上之后你写同样一段内容敲键盘的次数是不是明显变少了。如果没变少说明它没击中你的真实操作习惯果断卸掉。2.1 Markdown All in One一个插件顶半个工具箱如果只能装一个 markdown 插件我会选它。这个插件把快捷键、自动补全、目录生成、格式化、数学公式支持整合在一个包里覆盖了日常写作八成的需求而且配置项清晰不需要你去翻一堆文档。它最值钱的部分是快捷键体系。下面这几个是我用得最多的快捷键实际作用使用频率CtrlB选中文字加粗极高CtrlI选中文字斜体高CtrlShift] / CtrlShift[标题层级升 / 降高AltShiftF格式化表格自动对齐竖线极高CtrlShiftP 后输入 Create Table of Contents生成目录中CtrlShiftP 后输入 Toggle List切换列表符号类型中这里面我要特别说表格格式化。手写表格的时候列宽对不齐是常态读源码的时候非常难受。选中整张表格按一次 AltShiftF插件会按每列最宽的内容重新排布竖线位置源码立刻变得像样了。这个动作我一天要做几十次。目录生成也值得单独提。插件会根据文档里的标题层级自动生成一份带锚点链接的目录标题改动之后重新执行一次即可刷新。这里有个实用配置markdown.extension.toc.levels可以控制纳入目录的标题层级范围我一般设成2..4也就是二级到四级标题进目录一级标题当文档大标题不进目录五级以下太细碎也不进。这样生成的目录长度刚好贴在文档开头很清爽。还有一个容易被忽略的功能是列表自动续写。你在一个列表项末尾按回车插件会自动补上下一项的符号缩进也对齐。写完列表按两次回车它会自动退出列表状态不会让你莫名其妙一直待在列表里。注意这个插件默认会接管 markdown 文件的格式化。如果你同时还装了别的格式化类插件一定要在设置里通过editor.defaultFormatter指定唯一一个否则保存时会出现格式化结果来回跳的诡异现象。2.2 Markdown Table 类插件把表格当成表单来填Markdown All in One 的格式化解决的是对齐但没解决建表。手写一张八列十行的表格光是敲分隔行就够烦的。这时候可以再配一个专门管表格的插件它提供的是一次性生成指定行列数的表格骨架以及行列的增删、左右移动、上下移动。我个人更看重的是行列移动这个能力。写文档的时候经常是先把内容一股脑塞进去回头再调整列的顺序纯手工剪贴很容易剪错行。有了移动命令光标停在某一列上按一下快捷键整列跟着走出错概率直线下降。再配上前面说的格式化一张表格从无到有再到整齐基本两三分钟就能搞定。表格还有一个高频需求是复制到 Excel。markdown 表格本质是竖线分隔的文本直接粘到 Excel 里会全挤在一列。靠谱的做法是先借助插件把表格导出成 CSV再用 Excel 或者表格软件打开 CSV。如果你不想装额外工具也可以在编辑器里把竖线替换成制表符存成 .csv 后缀再打开效果是一样的。这条路径我在做数据整理的时候经常用比手动一格一格填快太多。2.3 Paste Image 类插件截图直接落盘写技术文档绕不开截图而截图最烦的是存哪、叫什么名、路径怎么写这三连问。手动操作一遍截屏、粘贴到画图工具、另存为、选目录、起名字、回到文档里手打一段图片语法。一套下来半分钟没了写十张图就是五分钟纯消耗。图片粘贴类插件把这一串动作压成一步你在剪贴板里有图片的状态下按下快捷键插件会按你预设的目录和命名规则把图片存成文件同时在光标处插入正确的图片引用语法。我常用的配置方向是按文档名建子目录 时间戳命名这样每篇文档的配图都集中在自己旁边不会混成一坨。提示命名规则尽量包含时间戳或递增序号不要用截图1、截图2这种。一旦你重命名或者移动文档重名覆盖是会真实发生的而且发现的时候通常已经晚了。3. 预览类插件所见即所得的那一层预览的定位是把写完才知道长什么样变成边写边知道。vscode 内置的 markdown 预览其实已经够用支持同步滚动、支持基本的 HTML 标签。但它对数学公式、流程图、脚注、自定义容器的支持比较有限这就是第三方预览插件存在的理由。3.1 Markdown Preview Enhanced功能最全的那个这个插件可以理解成一个markdown 渲染全家桶。除了标准语法它还支持数学公式、mermaid 流程图、脚注、自定义容器、代码行号、目录侧边栏甚至能调用外部工具导出 PDF、PNG、eBook 等一堆格式。我第一次用它的时候最直观的感受是预览窗口终于和最终效果对得上了。它值得重点说的地方有三个。第一是代码块的处理它会给代码块加上语言标签、行号、复制按钮做技术文档的时候体验非常好。第二是导出能力它支持多种导出引擎具体选哪个后面第 5 节会展开讲。第三是它的配置粒度很细比如是否开启扩展表格语法、是否给标题自动编号、是否在预览里显示 toc都可以单独开关。要注意的是功能越多、配置项越多出问题的可能性也越多。我的做法是先按默认配置用一周遇到不顺手的地方再去改配置不要一上来就把整份配置文档抄一遍那样你根本不知道自己改了什么。3.2 Markdown Preview Mermaid Support流程图直接预览如果你的文档里有架构图、流程图、时序图光靠内置预览是不够的代码块里的 mermaid 语法会被当成普通文本原样显示。这个插件的作用就是让内置预览也能渲染 mermaid 图表装完之后不需要额外的独立预览窗口CtrlShiftV 打开的内置预览里就能看到图形。用 mermaid 写图的好处是它是文本可以进版本管理改一个方框只要改一行字不像图片那样要重新画、重新截图、重新插入。我现在的架构文档基本都是 mermaid 写的评审的时候直接看源码就知道改了哪条连线。写的时候有几个实际的坑要提前知道节点文本里如果有特殊符号需要加引号包起来中文标签在部分渲染器下会出现字宽计算不准、方框和文字对不齐的情况连线太多的时候图形会横向拉得很长可读性下降。所以复杂的图我还是会拆成几张简单的图宁可多画两张也不要画一张谁都看不清的巨型图。3.3 预览快捷键与同步滚动预览相关的高频操作就那么几个记住就够用。CtrlShiftV 是在当前标签页打开预览CtrlK 然后按 V 是在右侧分栏打开预览后者更适合宽屏左写右看。分栏预览默认开启同步滚动滚动左边右边跟着走如果没跟着走去设置里确认 markdown 的预览滚动同步选项是不是被关掉了。多屏场景下还有一个技巧把预览标签拖到第二个显示器主屏写源码副屏看效果这样分栏占用的横向空间就省下来了。我在写长文档的时候一直是这么用的眼睛不用在左右两边来回扫。4. 规范校验类插件让文档不返工预览解决看得见校验解决看得对。markdown 文件最大的特点是它对格式很宽容你怎么写它都能渲染但渲染出来是不是你想要的样子就不一定了。标题跳级、列表符号混用、行尾多余空格、代码块没写语言这些问题在单个文件里影响不大但文档一多、人一多就会变成灾难。4.1 markdownlint把规则交给机器这个插件做的事情是把一套约定俗成的 markdown 写作规范变成实时检查。你写的时候编辑器左侧会出现波浪线面板里会列出所有问题鼠标悬停能看到规则编号和解释。每条规则都有一个 MD 开头的编号比如 MD013 是行长度、MD009 是行尾空格、MD012 是连续空行、MD033 是内联 HTML、MD041 是首行必须是标题。用它的关键不是全部遵守而是有意识地关掉不合适的。默认规则有几十条其中相当一部分是为英文写作设计的直接套在中文文档上会很别扭。比如行长度限制中文字符宽度是英文的两倍同样的字符数限制中文一行放的文字量少一半强行限制会导致大量无意义的换行。我的做法是把行长度规则放宽到 120 并且对表格和代码块豁免或者干脆关掉这条规则。4.2 规则裁剪与团队统一规则配置我强烈建议放在项目里而不是放在个人用户设置里。做法是在仓库根目录放一个.markdownlint.json内容大概长这样{ default: true, MD013: { line_length: 120, tables: false, code_blocks: false }, MD033: false, MD041: false, MD024: { siblings_only: true } }这样配置的意义在于团队里每个人打开同一个仓库看到的波浪线是一样的评审的时候也不会因为格式问题来回拉扯。default: true表示先启用全部规则再用下面的条目做例外这种先严后松的写法比反过来更容易维护因为你只需要记录自己关掉了什么、为什么关。MD024这条我要单独说一下。它检查的是标题重复默认情况下同一篇文档里不能出现两个同名标题。但实际写作中配置示例注意事项这种小标题在不同章节下重复是很正常的所以用siblings_only让它只在同一层级下检查重复就合理多了。4.3 中文写作场景下的规则取舍中文 markdown 有几条规则是经常需要调整的。MD013 行长度前面说过放宽或者关掉。MD033 内联 HTML如果文档里要用br做强制换行、用details做折叠块这条就得关掉因为这些都是合法的扩展用法。MD034 裸链接中文写作里贴一个完整的网址很常见强制加尖括号反而累赘。反过来有几条规则我建议一定要留着。MD009 行尾空格因为它和换行直接相关行尾多两个空格在某些渲染器里意味着强制换行多一个少一个结果完全不同。MD010 制表符制表符在不同编辑器里显示的宽度不一样混用会让所有对齐全部失效。MD040 代码块语言要求你在代码块开头写明语言这个习惯一旦养成后面做高亮、做代码统计、做文档检索都会方便很多。注意校验类插件不要设成保存即自动修复全部问题。自动修复在处理列表缩进和标题层级时偶尔会改出你不想要的结果。我的做法是让它在编辑器里提示修复动作由我手动触发改完看一眼 diff 再提交。5. 导出与格式转换从 .md 到 PDF / Word / HTML写完的 markdown 最终要交付出去这一步的坑最多。导出失败、样式丢失、中文变方块、代码块超出页面宽度这些都是真实会遇到的问题。我的经验是不同目标格式走不同路径不要指望一个插件通吃。5.1 Markdown PDF 类插件的工作方式与依赖这类插件的原理基本都是把你的 markdown 渲染成 HTML再调用一个浏览器内核把它打印成 PDF。所以它第一次运行的时候通常需要下载一份 Chromium几百兆的体积下载慢的时候会卡很久看起来像卡死了其实是在下载。国内网络环境下这一步经常需要多试几次或者把下载地址换成镜像。它支持的配置里最有用的是页边距、纸张尺寸、页眉页脚、以及是否显示背景色。写西文文档基本开箱可用写中文文档需要注意字体配置——如果不显式指定中文字体某些环境下中文会渲染成方框或者乱码。我的做法是在设置里显式指定一个系统里确定存在的中文字体比如思源宋体或者系统自带的宋体黑体这样跨机器导出时结果才稳定。另一个高价值功能是导出时自动生成目录和页码。这个对正式文档特别重要但要注意页码是从正文开始算还是从封面开始算不同插件的默认行为不一样交付前一定要打开 PDF 翻一遍。5.2 Markdown Preview Enhanced 的多引擎导出这个插件提供了多个导出引擎各自的适用场景不太一样。基于浏览器内核的引擎适合大多数场景渲染效果和预览基本一致。还有一个引擎依赖外部的排版工具排版质量更高支持更精细的分页控制、交叉引用、脚注编号适合正式出版物代价是你得先在系统里单独安装这个外部工具并且要保证命令行里能直接调用到它。我的选择逻辑是这样内部交流文档、结构简单的走浏览器内核引擎快、依赖少需要正式打印、有复杂分页和交叉引用的才去装外部工具走高质量引擎。不要为了看起来更专业就给所有文档都上重依赖维护成本会慢慢拖垮你。它的导出菜单里还有一个很实用的选项是导出成 PNG 图片。当你只想把一小段内容分享到聊天窗口导出整篇 PDF 再截图是很蠢的做法直接导出图片更快。5.3 Pandoc 工作流转 Word 最稳的一条路如果目标是 Word我会绕开所有编辑器插件直接用命令行工具做转换。这个工具是文档格式转换领域的老牌选择输入 markdown 输出 docx一行命令搞定pandoc input.md -o output.docx --reference-docreference.docx这里的关键是--reference-doc参数。它让你先准备一个样式模板文档里面定义好标题几号字、正文行距多少、代码块用什么字体、表格边框什么样转换的时候这些样式会被套用到输出文件上。没有这个模板输出的 Word 会是最朴素的默认样式交付前你还得手动调一遍格式等于白转。实际操作步骤是这样的先用 pandoc 生成一份默认样式的 docx打开它进样式编辑器把标题、正文、代码、引用这几个样式按你的要求改好另存为reference.docx之后所有转换都带上它。这一套配一次可以用很久团队里所有人共用一份模板输出的文档风格就是统一的。如果表格比较多转换后记得检查一遍。markdown 表格的列宽是自适应的转成 Word 之后列宽会由内容撑开遇到长内容会出现很难看的换行。稳妥的做法是把宽表格改成横向页面或者拆成两张窄表。6. 常见问题与排查实录下面这些问题都是我实际遇到过并且解决掉的整理成一张速查表遇到类似现象可以先对着排查。现象常见原因处理方式预览窗口一片空白插件冲突或预览服务未启动禁用其他预览类插件后重开或重启编辑器中文显示成方块导出字体未指定在导出配置里显式指定系统中文字体换行不生效单回车不构成换行行尾留两个空格、或改用空行分段图片显示不出来路径为绝对路径或已移动改成相对路径统一放在文档同级目录代码块超出页面导出页宽小于代码行宽减小字号、开启自动换行、或改为横向页表格导出后错位表格列数不一致用格式化功能重新对齐检查分隔行保存时反复格式化多个插件争抢格式化权指定唯一默认格式化插件编辑器启动变慢插件引入大体量运行时禁用不常用插件改为按需启用6.1 预览空白与样式丢失预览空白最常见的原因不是文档有问题而是预览进程没起来。先试一次彻底重启编辑器再试一次把光标放在 markdown 文件里重新打开预览。如果还不出来八成是两个预览类插件同时在抢同一个预览窗口把不常用的那个禁用就好了。样式丢失多数和主题有关。有些插件提供了自己的预览主题如果你在设置里换了主题但没生效先检查是哪个插件在管样式。多插件环境下样式表是按加载顺序覆盖的后加载的会盖掉前面的所以改了没反应往往不是没生效而是被另一个插件盖回去了。6.2 换行不生效这件事这是新手问得最多的一个问题。markdown 的规则是单个换行符在渲染时会被当成空格连续的文字会被合并进同一个段落。想要真正换行有三种做法。第一种是行尾留两个空格再回车这是标准语法缺点是空格看不见容易被编辑器的自动去空格功能干掉。第二种是在行尾加一个反斜杠再回车效果一样但可见我个人更推荐这种。第三种是直接空一行让它们变成两个段落段落之间有间距视觉上最清楚。第三种不是严格意义的换行但大多数写作场景下这才是你真正想要的效果。如果你的行尾两个空格总被自动删掉去检查是不是开启了保存时删除行尾空白。这两个功能是天然矛盾的必须二选一。6.3 图片路径失效图片路径是文档搬家时最容易出问题的部分。绝对路径写起来最省事但一换电脑就全挂。稳妥的做法是统一用相对路径并且把图片放在文档同级目录或者同级的images子目录里整个文件夹一起搬走。这个习惯一旦养成文档分享出去基本不会有丢图的情况。另外注意路径里的空格和中文。路径带空格的时候某些渲染器会解析失败建议目录名用英文加短横线。中文路径在大多数现代工具里没问题但在跨平台、跨工具传递的时候偶尔会出意外能避就避。6.4 插件冲突与卡顿插件装多了之后编辑器启动变慢、输入延迟变高是很常见的。判断方法很简单禁用全部 markdown 相关插件感受一下速度然后一个一个启用看哪个启用之后明显变卡。找到之后要么去它的设置里关掉耗性能的功能要么干脆换一个轻量的替代品。我的经验是把重度导出类插件和日常写作类插件分开管理。日常写作时只开写作和预览导出的时候再临时把导出插件打开。扩展面板支持按工作区启用可以给不同的项目配不同的插件集合用起来非常舒服。7. 我长期在用的两套组合与完整配置讲了这么多插件最后落到组合上。不同场景需要的组合完全不同我目前稳定在用两套一套轻量、一套完整按项目类型切换。7.1 轻量写作组合适合写笔记、写博客草稿、写会议纪要。这套组合只留三个插件写作增强类一个负责快捷键和目录预览类一个负责边写边看校验类一个只开最基础的几条规则。不装导出插件需要导出的时候再临时开。这套组合的优点是启动快、干扰少注意力全在内容上。我写初稿的时候基本都用这套因为初稿阶段最重要的是把想法倒出来排版和交付都是后面的事。7.2 技术文档组合适合写需要交付的文档比如接口说明、部署手册、方案设计。在轻量组合的基础上加上 mermaid 预览支持、表格增强、导出插件。校验规则收紧把行尾空格、代码块语言这些和最终呈现强相关的规则全部打开。这套组合我一般会为项目单独建一个工作区配置把规则文件和导出模板都放进仓库。新同事拉下代码之后格式规范、导出样式直接就有了不需要口头传达。7.3 可以直接抄的配置片段下面是我用户设置里和 markdown 相关的那部分去掉注释之后可以直接粘进settings.json{ [markdown]: { editor.wordWrap: on, editor.formatOnSave: true, editor.defaultFormatter: yzhang.markdown-all-in-one, editor.quickSuggestions: { other: true, comments: false, strings: true } }, markdown.extension.toc.levels: 2..4, markdown.extension.toc.updateOnSave: false, markdown.extension.list.indentationSize: adaptive, markdown.extension.italic.indicator: *, markdownlint.config: { MD013: false, MD033: false, MD034: false } }几个配置项的解释免得你抄完不知道为什么这么写。editor.wordWrap设成on是让长行自动折行显示注意这只是显示层的折行不会真的往文件里插入换行符所以不影响渲染结果。editor.formatOnSave让保存时自动整理表格和列表配合前面指定的默认格式化插件就不会出现多个插件打架的情况。toc.updateOnSave我设成false因为目录自动更新会导致每次保存都产生 diff评审的时候噪音太大我更喜欢手动触发更新。italic.indicator设成星号因为下划线在某些渲染器里会被当成强调标记星号更安全。工作区级别的.markdownlint.json我在 4.2 节已经给过了这里就不重复。这两个文件配好之后一套 markdown 写作环境基本就成型了。最后分享一个我自己摸索出来的小习惯在项目里放一份template.md里面预置好标题结构、元信息区块、常用的几个章节骨架。写新文档的时候直接复制这份模板比从空白文件开始写要快得多而且能保证同一批文档的结构是一致的。这个习惯比装任何插件都管用因为它管的是结构而插件管的是操作结构上的偷懒才是真正的效率提升。