两年前我接过一个内部知识库的搭建任务要在比较紧的周期里产出四十多篇技术方案和复盘文档。那时的典型工作台长这样Word 里写初稿ProcessOn 上画流程图XMind 搭脑图Draw.io 画架构图写完再把图一张张截图贴回文档。最崩溃的不是来回切窗口而是文档里的图一旦要改就得重新打开对应的绘图工具改完再重新截图而且源文件经常散落在不同目录同事改了一版我拿到的还是旧图。后来我把整个工作台统一到了 VS Code 里用 Markdown 写正文用 PlantUML 和 Mermaid 画 UML 图用 Markdown 大纲直接生成脑图用 Draw.io 画界面原型和部署架构再配合用户代码模板snippet把重复劳动压到最低。所有内容都以文本形式存在同一个项目目录下拷贝一个文件夹就等于拷走了全套知识资产。这篇就把我在搭建这套工作台时踩过的坑、做过的取舍、最后沉淀下来的配置方式完整写出来。1. 为什么是 VS Code文档生产工具的碎片化困境1.1 文档生产工具的碎片化困境我调查过团队里绝大多数人的文档生产方式基本绕不开几个问题不同格式之间没法互相引用同一个图标在 Word 里是这个样式、在 ProcessOn 里又是另一个样式链接失效没人发现版本管理靠文件名带日期图表源文件和最终成稿离得很远改一个数字可能得来回倒腾半小时。这不是某一个人的问题而是工具链天然分裂造成的。Word 适合排版但不适合版本 diffProcessOn 和 XMind 的输出物是图片丢进文档之后就失去了可编辑性Draw.io 虽然能存 XML但如果没人强制把源文件放进同一个目录很快就会找不到。碎片化的本质是“内容”被锁死在了“工具”里。VS Code 作为解决方案的切入点不是它某一个功能多强而是它把内容的承载方式统一成了“纯文本”。Markdown 本身就是文本PlantUML 和 Mermaid 的图是文本脑图可以用 Markdown 大纲表示Draw.io 也可以存成基于 SVG 的纯文本文件。当所有东西都变成文本版本管理、diff、批量替换、脚本处理就全部解锁了。1.2 以 VS Code 为中心的选型逻辑选定 VS Code 作为唯一工作台我当时的判断标准有四条启动速度和编辑体验要碾压 Electron 类的重型文档工具扩展生态必须覆盖 Markdown、UML、脑图、画图、模板五个方向所有文件都要能够放进 Git 仓库历史记录和多人协作自然而然解决学习成本不能高于工具本身带来的效率提升最终落地的扩展组合其实不多我列在下面这张表里后面每个模块再细说。扩展用途说明Markdown All in One编辑增强、目录、快捷键写正文的底座markdownlint语法规范检查需要关掉几个默认规则Markdown Preview Enhanced预览、导出 PDF/HTML、内嵌 Mermaid核心中的核心Paste Image粘贴截图自动存文件图片路径管理的关键PlantUMLUML 图需要 Java 和 GraphvizDraw.io Integration画架构图、流程图、原型支持 .drawio.svg 纯文本保存markmapMarkdown 大纲转脑图用文本结构生成可视化脑图内置 Snippets代码模板不用装扩展配置 JSON 即可1.3 基础环境与扩展清单安装 VS Code 之后我的习惯是先统一三件套中文界面按需安装但建议中文插件和英文原版共存以方便搜索报错设置里打开editor.minimap: false以免干扰 Markdown 阅读关闭workbench.startupEditor: none启动速度会快不少。然后是扩展安装。我不建议一口气从网上复制一份“全家桶”清单很多插件之间功能重叠装多了反而互相干扰。就上面那七个插件已经能覆盖 95% 的文档生产场景剩下的按需再补。2. Markdown 写作环境从编辑器设置到图片路径管理2.1 编辑体验的三个关键设置Markdown 写作的体验好坏往往不是语法高亮的问题而是几个容易被忽略的设置。第一是自动保存。我默认打开files.autoSave: onFocusChange光标离开当前文件就保存配合 Git 的自动 diff基本不会丢失内容。第二是格式化。写完一段 Markdown 表格ShiftAltF直接对齐理顺这依赖 Markdown All in One 的“格式化表格”能力。第三是快捷键。Markdown All in One 把常见的操作都绑定了快捷键比如CtrlB加粗、CtrlShiftI斜体CtrlShiftP呼出命令面板后输入 “Toggle Checklist” 可以快速切换任务列表。还有一个很容易踩的坑VS Code 内置的 Markdown 预览和 Markdown Preview EnhancedMPE的预览不是一回事。内置预览的快捷键是CtrlShiftVMPE 的预览快捷键默认是CtrlK V两者都能出效果但 MPE 支持 Mermaid、PlantUML、导出 PDF 等一系列功能如果发现某个语法在内置预览里渲染不对先确认你打开的是不是 MPE 的预览。2.2 图片路径管理被忽略的工程化问题写带截图的技术文档最大的隐患不是排版是图片路径。默认情况下截图粘贴进来会跑到工作区根目录或者乱七八糟的位置时间一长图片找不到、链接断掉文档就变成了“图裂纯文本”。我的做法是利用 Paste Image 插件统一规则。安装 Paste Image 后在设置里配置{ pasteImage.path: ${currentFileDir}/images, pasteImage.namePrefix: ${currentFileNameWithoutExt}-, pasteImage.insertPattern:  }这样每篇文档的图片都存到本文档目录下的images子目录文件名前缀是当前文档名避免不同文档的图片重名互相覆盖。插入的 Markdown 链接自动是相对路径整个文件夹拷到任何地方、任何电脑上图片都不会断。配合 Git图片也会跟着代码一起进历史版本评审时能看到某个 commit 里文档和图片的对应关系这对团队协作价值非常大。2.3 导出 PDF 与 Word 的差异化方案Markdown 写完之后最终经常还是要交付 PDF 或者 Word。网上大量教程会告诉你 MPE 导出 PDF 需要下载 princexml这个路径我实测过对于中文文档来说prince的字体处理会让人抓狂很容易出现中文乱码或者样式错乱。MPE 右键菜单里的导出选项有一个“Export to PDF (Chrome (Puppeteer))”这个方案本质是调用本机 Chrome 无头模式打印当前预览页面。只要电脑上装了 ChromeMPE 会自动找到浏览器路径导出效果和你在浏览器里按打印基本一致中文、代码高亮、Mermaid 图全部正常。如果它找不到 Chrome可以在设置里手动指定markdown-preview-enhanced.chromePath: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe。导出 Word 的建议用 Pandoc 方案。先安装 Pandoc然后在 MPE 里右键选择“Pandoc”导出 docx。Pandoc 对标准的 Markdown 语法支持很好表格、代码块、标题层级都能正确转过去。需要注意导出前先把图片路径确认无误因为 Pandoc 转换时会解析 Markdown 里的相对路径路径断了图片就丢。3. UML 与流程图的文本化改造PlantUML、Mermaid 与 Draw.io 的取舍3.1 文本化绘图为什么值得投入很多人第一次看到“用代码画图”会觉得多此一举但等你在团队里做过一次方案评审就明白了图里一个类名写错了用鼠标改起来要选中、删除、重新输入而文本化之后直接搜索替换两个版本之间改了哪些关系文本 diff 里一目了然甚至可以跑脚本批量校验规范。文本化绘图的核心价值不是“省去鼠标”而是让图形从不可追溯的像素变成可以被计算、被检索、被版本管理的结构化数据。我在这套工作台里实际上保留了两种文本化工具PlantUML 和 Mermaid以及一个保留鼠标操作习惯的 Draw.io。它们各自解决的问题并不重叠。3.2 PlantUML类图、用例图与包图的落地写法PlantUML 是我画 UML 类图的首选类图在描述领域模型、数据库关系、系统模块边界时是刚需。下面这个例子来自我写一个资源预订系统方案时画的类图startuml skinparam classAttributeIconSize 0 skinparam defaultFontName Microsoft YaHei class User { -id: int -name: string -email: string login(): bool logout(): void } class Order { -orderNo: string -amount: decimal create(): void cancel(): void } class Resource { -resourceId: int -resourceName: string -status: string } User 1 -- 0..* Order Order 1 -- 0..* Resource enduml在 VS Code 里装了 PlantUML 扩展后AltD可以直接预览当前文件。第一次使用时会提醒你安装 Java 和 Graphviz这一步很多人卡住我单独说明Graphviz 是负责布局计算的不装的话简单时序图可能能出来但类图的连线布局往往会报错Dot executable does not exist。Windows 上安装 Graphviz 时务必勾选“Add to PATH”装完之后重启 VS Code 才生效。再给一个用例图的例子这类图适合描述系统角色和功能边界startuml left to right direction skinparam defaultFontName Microsoft YaHei actor 访客 actor 注册用户 actor 管理员 rectangle 资源预订系统 { usecase 浏览资源列表 usecase 预订资源 usecase 管理资源 usecase 审核订单 } 访客 -- 浏览资源列表 注册用户 -- 预订资源 管理员 -- 管理资源 管理员 -- 审核订单 enduml包图同理只是把class换成package用来表达模块依赖关系非常直观startuml package 基础设施层 { [统一认证] as AUTH [消息队列] as MQ } package 业务层 { [订单服务] as ORDER [资源服务] as RES } ORDER -- AUTH ORDER -- MQ RES -- MQ enduml3.3 Mermaid 与 PlantUML 的选型对比如果只学一种我的建议是先学 Mermaid因为它语法更轻而且可以直接写在 Markdown 代码块里连额外的渲染插件都不需要。比如graph LR A[前端] -- B[网关] B -- C[订单服务] B -- D[用户服务]这段代码在 MPE 预览里直接变成流程图适合描述调用链、流程步骤这些轻量场景。但 Mermaid 的 UML 语义没有 PlantUML 完整画类图时对于关联方向、多重性这类细节支持不够顺手。两者的选型边界我在项目里是这样划分的场景工具理由领域模型、数据库关系、模块依赖PlantUMLUML 语义完整类图/包图/用例图表达力强流程、时序、轻量架构图Mermaid语法简单可直接嵌入 Markdown团队上手成本低复杂的可视化架构图、原型图Draw.io鼠标拖拽效率更高适合不规则布局脑图markmap直接用 Markdown 大纲生成3.4 Draw.io Integration把桌面画图工具收进 VS CodeDraw.io 桌面客户端确实很好用但它的文件通常存在本地某个文件夹里和项目文档割裂。Draw.io Integration 插件解决的就是这个问题在 VS Code 工程目录里右键新建.drawio.svg文件双击就在编辑器内打开绘图画布快捷键与桌面端基本一致。选择.drawio.svg而不是.drawio是关键判断。.drawio.svg本质是一个含 SVG 内容的文本文件Git 可以直接 diffGitHub 网页端也能直接预览.drawio虽然也是 XML但在 GitHub 上不能原生渲染。团队协作时评审人不需要安装插件也能在网页上看到图这是一个体验层面的优势。我在用这个插件时配置了两项{ drawio.offline: true, drawio.theme: minimal }drawio.offline设为 true 可以避免每次打开文件时插件去请求远程资源这是很多教程没提到但实际体验差异很大的一个配置项。4. 脑图与代码模板把构思和复用变成肌肉记忆4.1 Markdown 脑图从大纲到可视化的桥脑图软件的问题有两个一是输出物是图片进了文档就不好改了二是很多人其实不会画脑图最后画出来就是一张“带颜色的树形目录”。我对团队的要求是先列大纲再谈可视化。Markdown 无序列表天然就是大纲结构把这份大纲丢给 markmap一秒钟生成可交互的脑图。使用方法特别简单在 VS Code 里新建一个.md文件用无序列表组织层级CtrlShiftP输入markmap选择预览即可。我通常在项目里建一个brainstorm/目录里面放《方案构思》《问题拆解》《会议纪要》这类前置思考文档先用大纲脑图把思路展开等结构稳定了再转成正式文档。这套打法的好处是大纲和正式文档之间没有转换成本同一份 Markdown 既可以在初期当脑图看又可以直接作为正式文档的目录骨架。以前用 XMind 画完再手动整理文档结构的环节彻底省掉了。4.2 snippet 模板写文档时自动生成结构代码模板snippet是提升写作效率最被低估的功能。VS Code 支持用户级 snippet定义一次所有项目通用。打开方式是CtrlShiftP→ “Snippets: Configure User Snippets”可以按语言配置比如给 Markdown 配置一套写文章的模板给 Java、Python 配置代码骨架。snippet 的核心变量要理解清楚$1、$2是 Tab 键跳转的光标位置$0是最终停留位置${1:默认值}可以预填内容$TM_FILENAME是当前文件名$CURRENT_YEAR是当前年份。利用这些变量可以做出非常灵活的模板。4.3 几个我常用的代码模板这是我用于技术博客的 Markdown snippet 配置每次新建文章只要输入post再加 Tab就能自动生成带 YAML 头部的文档骨架{ 技术文章 Front Matter 模板: { prefix: post, body: [ ---, title: \${1:文章标题}\, date: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE, tags: [${2:标签}], categories: [${3:分类}], ---, , # ${1:文章标题}, , ## 背景, , $0 ], description: 插入带 YAML Front Matter 的技术文章头 } }Java 代码模板同样很实用。项目里写新类时输入entity回车自动生成带注解的实体类骨架{ JPA Entity 模板: { prefix: entity, body: [ import lombok.Data;, import javax.persistence.*;, , Data, Entity, Table(name \${1:table_name}\), public class ${2:ClassName} {, , Id, GeneratedValue(strategy GenerationType.IDENTITY), private Long id;, , $0, } ], description: 生成 JPA 实体类 } }你可能发现snippet 不只是给“代码”用的它真正解决的是“一切高频重复输入的文本”。只要你发现自己每隔两天就要敲一遍同样的文档头、免责声明、项目代号、评审结论都应该抽象成 snippet。5. 一套完整的知识生产工作流从零散笔记到交付文档5.1 以“系统重构技术方案”为例的完整流程单点的工具配置讲完了这一节串起来跑一遍以我最近写的一份“资源预订系统重构技术方案”为例。第一步在brainstorm/rework-brainstorm.md里用无序列表把想到的问题、目标、风险全部列出来然后打开 markmap 预览看整个方案的骨架是否清晰。这个阶段不追求措辞只追求结构和覆盖度。第二步目录结构稳定后在docs/下新建resource-booking-rework.md输入post加 Tab模板自动生成 front matter、标题和背景小节。第三步把脑图中的大纲复制进来逐节扩写。涉及模块关系时粘贴入 PlantUML 类图代码块涉及请求链路时用 Mermaid 的时序图涉及部署拓扑时直接右键创建.drawio.svg画图。第四步全部写完后在 MPE 预览里通读一遍确认代码块、图形、表格渲染正常。第五步导出 PDF 用于评审会议导出 docx 用于需要批注的场景有些同事确实只习惯 Word 批注那就尊重这个习惯但源头始终是 Markdown。整套流程下来所有中间产物都在同一个仓库的同一棵目录树里没有一张图是孤岛。5.2 版本管理与多人协作的约定多人协作时最大的坑是“文档和图片不同步”。由于图片是二进制两个人同时改一个文档图片冲突解决起来比文本麻烦得多。我的约定是同一篇文档的图片放在对应的images/子目录文件名带文档名前缀每次修改文档只允许 append 或者小范围替换涉及大范围重排列时在 commit 信息里说明对应的图片变化。另一个约定是任何图都必须在文档里保留源文件路径的注释。比如 PlantUML 的startuml下面一行写 source: docs/resource-booking-rework/class-diagram.pumlDraw.io 直接就是以.svg文件存在的天然满足这个约定。这样再过半年任何人看到文档里的图都能顺着路径打开源文件编辑而不是对着截图猜当初是怎么画的。6. 踩坑与调优插件冲突、预览差异和导出样式问题6.1 markdownlint 的默认规则让人抓狂markdownlint 的本意是规范 Markdown 语法但它的默认规则里有一条 MD013行宽限制 80 字符、一条 MD033不允许内联 HTML在中文技术文档场景下简直添乱。中文一句话往往就超过 80 字符MD013 报一整页黄线内联 HTML 在文档里写个居中 div 也会被标红。我的做法是在项目根目录放一个.markdownlint.json{ MD013: false, MD033: false, MD024: false }MD024是“同一文件里多个相同标题”的警告这道默认规则在写常见问题 FAQ 时几乎必触发。规范的目的是辅助不是制造噪音能判断哪些规则要关掉比照抄规范更重要。6.2 预览与导出样式不一致MPE 预览里看着很舒服的文档导出 PDF 后可能出现表格被截断、代码块换行乱掉、Mermaid 图超出页面边界。这些问题的根源是 CSS 打印样式没有为 A4 页面优化。一个见效最快的操作是在文档开头插入 MPE 支持的 front-matter 配置指定导出时的 CSS 样式--- export_on_save: html: true print_background: true ---然后在 MPE 的预览面板右键 → “Open in Browser”再在浏览器里CtrlP打印为 PDF。这个方案比直接右键导出更可控因为你可以临时修改浏览器打印设置里的边距和缩放比例。遇到代码块过长时我建议手动换行或者在代码块前加一行!-- pagebreak --MPE 会识别这个注释并强制分页避免图表被截断。6.3 我的最终插件清单与取舍理由这篇文章写到这里我把最终留在生产环境里的插件清单再完整列一次并且说一下为什么是这些而不是市面上更流行的替代品插件替代方案我选它的原因Markdown All in One无表格格式化、目录生成、快捷键覆盖最全markdownlint无能自己关规则保留了语法提醒价值Markdown Preview Enhanced内置预览、Typora唯一同时解决预览、Mermaid、导出三个诉求的插件Paste Image手动拖拽图片配合路径配置后粘贴即工程化PlantUML在线 PlantUML 服务本地渲染代码可进 GitDraw.io Integration桌面客户端文件与项目文档同库SVG 可 diffmarkmapXMind、MindMaster大纲即脑图零转换成本这个清单保持了 7 个插件的最小规模每个插件解决的都是一个不可替代的独立问题。实际用了大半年没有出现插件互相抢占快捷键的情况唯一需要留意的是 Markdown All in One 的CtrlB在部分编辑器主题里会和“切换侧边栏”冲突如果发现按了没反应到键盘快捷键设置里搜索toggle bold改一个你自己顺手的键位即可。之前也提过搜索热词里“亿图脑图离线注册机”这类下载即翻车的操作我向来不推荐脑图用 markmap 生成的是.html或.svg文件不依赖任何注册机和破解版跨平台、可版本控制还不必担心哪天软件不能用了图就全丢了。这也是整套工作台最核心的逻辑你的知识资产不该被任何一家工具的格式绑架。