做内容的人基本绕不开 Markdown尤其是我这种既写技术文档、又写团队博客、还经常临时记需求的一天到晚都在跟.md文件打交道。我以前的主力编辑器是 Typora但后来换了工作环境在 Windows 和 Linux 之间来回切再加上个人电脑、公司电脑轮着用单纯依赖一个桌面级 Markdown 软件明显不够顺手。折腾一圈之后我把主力 Markdown 编辑器固定在了 VSCode 上并整理出了一套可以复用的部署方案。这套方案主要解决三个问题第一想用一个编辑器同时搞定写作、代码、文档和发布流程不用在多个软件之间来回跳第二多设备之间配置一致换电脑不需要重新“装修”第三Markdown 写作里最麻烦的预览、表格、公式、图片、导出这些点都能在 VSCode 插件生态里找到对应的解法。适合谁参考刚接触 Markdown 的新手可以直接照抄配置正在用其他 Markdown 工具的人可以用来对比和迁移团队想统一文档工具的也可以把它当成一份选型参考。1. 为什么把 Markdown 编辑器搭在 VSCode 上1.1 编辑器不等于编译器先搞清楚这层关系很多刚入门的朋友会把“编辑器”“编译器”“IDE”混在一起。实际上编辑器负责的只是文本编辑VSCode、记事本、网页里的文本框都算编译器做的事情是把源码翻译成计算机能运行的程序。VSCode 首先是编辑器它自带了语法高亮、插件系统、文件管理能力所以拿它来写 Markdown本质上就是利用它的编辑能力再通过插件补齐 Markdown 的预览和渲染能力。这就像一个机械加工车间VSCode 是那台多功能机床Markdown 只是其中一种需要换上去的刀头。理解这一点很重要因为很多人在选型时会陷入误区觉得“代码编辑器怎么能写文档”。恰恰相反正是因为 VSCode 在文本处理层面足够强大它才更适合承载 Markdown 这种纯文本格式。Markdown 本身就是从纯文本排版需求里长出来的东西一个底层文本能力强的编辑器反而比那些追求“所见即所得”的专用软件更自由、更可控。1.2 Markdown 写作场景有哪些“隐性需求”日常写 Markdown看起来只是敲几个#和*但实际场景里需求往往比想象中多得多。我需要随时打开一个几百行的技术文档快速定位重点需要让表格在屏幕上清晰展示需要在写技术方案时插入流程图需要让数学公式正常渲染还有图片路径问题——文档目录一旦挪位置图片全变裂图这是很多 Markdown 新手最崩溃的时刻。VSCode 对 Markdown 的支持并不靠单一功能而是靠插件组合。比如内置的 Markdown 预览足够简单但如果你需要自定义样式、支持 Mermaid 图表、导出 PDF就需要通过插件来扩展。这种“积木式”的搭建方式比起专用工具“开箱即用但上限固定”更适合有长期写作需求的人。1.3 与代码、自动化工作流天然打通马克down 不只是写作格式它还是项目文档、技术笔记、发布系统的中间格式。很多团队现在用 Markdown 写接口文档、写公告、写知识库最后通过自动化工具转成网页或者 Word。VSCode 本身是开发工具它天然具备 Git 集成、终端、任务运行器这些东西写完文档可以直接git push可以直接跑脚本转换格式不用单独打开命令行窗口。这点对于技术背景的人非常友好也是我最终放弃专用 Markdown 编辑器、转向 VSCode 的最核心原因。2. 基础部署从安装到可正常写作2.1 下载安装与版本选择部署第一步自然是在目标机器上装好 VSCode。建议到 VSCode 官网下载认准官方来源。Windows 选择 User Installer 即可它不需要管理员权限安装在当前用户目录下日常使用完全够Linux 下我一般下载.deb包用sudo dpkg -i安装。如果你的电脑比较老特别是 Windows 7 仍然在用注意新版 VSCode 对系统版本有要求需要找兼容旧系统的历史版本装完以后不要乱升级能用就行。安装过程中有几点细节值得留意。第一安装路径尽量不要带中文和空格虽然现在 VSCode 对中文路径支持不错但后续装扩展、跑脚本时偶尔会有意外。第二Windows 下安装界面有个“添加到 PATH”的选项我一般都会勾选这样可以在命令行里直接输入code打开 VSCode后面部署脚本会用到。第三首次启动后不要急着把所有插件一次性装完先理解自己的需求再按需安装避免插件数量过多拖慢启动速度。2.2 第一次启动必改的几处设置VSCode 是一款高度可配置的编辑器核心配置文件叫settings.json。你可以通过快捷键Ctrl Shift P打开命令面板输入“open settings”进入设置页面也可以直接打开 JSON 文件编辑。我把一份基础配置贴在下面这些是我在 Markdown 写作场景下最低限度的设置。{ editor.wordWrap: on, files.eol: \n, files.autoSave: onFocusChange, editor.minimap.enabled: true, editor.renderWhitespace: none, markdown.preview.breaks: true, search.useIgnoreFiles: false, files.exclude: { **/.git: true, **/node_modules: true } }关键几项说明一下。editor.wordWrap设置为on处理长文本时不会出现横向滚动条阅读体验更接近普通文档files.eol设置为\n统一换行符为 LF避免在 Windows 下生成一堆CRLF提交到 Git 的时候也少一些无关痛痒的差异markdown.preview.breaks设置为true影响的是 Markdown 预览里换行解析方式。这个设置在预览上体验很好但注意它只影响 VSCode 内置预览本身不符合严格 CommonMark 标准所以如果你对 Markdown 规范要求苛刻可以保留默认。2.3 插件从哪里找、怎么装VSCode 的扩展市场内置在软件里左侧那个方块图标就是扩展入口直接搜索关键字安装即可。中文用户第一件事通常是装“Chinese (Simplified) Language Pack”装完重启就是中文界面。但这里我要提醒一句中文语言包本身很好用不会怎么影响性能但如果你看了英文界面也舒服可以不用装减少一个可能出问题的变量。我自己的电脑有时候保留英文界面方便去社区查最新报错信息中文环境下的关键词搜索内容往往滞后一两个版本。命令行安装是更快的方式特别是在批量部署时。我常用code --install-extension这个命令例如code --install-extension yzhang.markdown-all-in-one code --install-extension shd101wyy.markdown-preview-enhanced code --install-extension bierner.markdown-mermaid这样装扩展的好处是可以用脚本自动化在几台电脑上批量安装比在图形界面里一个个点效率高很多。后面第 4 章我会给一个完整的部署脚本示例。3. 写作体验部署预览、表格、公式、图片路径3.1 预览方案我为什么没选内置预览VSCode 自带 Markdown 预览快捷键Ctrl Shift V就能在右侧打开预览窗口。内置预览对基础语法支持没问题但遇到复杂表格、数学公式、流程图时就开始力不从心。所以我在实际部署中会安装 Markdown Preview Enhanced这是目前社区里公认体验最好的 Markdown 预览扩展之一它对 Typora 用户几乎是无缝迁移——支持目录、支持自定义 CSS、支持导出 PDF 和 Word、支持数学公式、支持 Mermaid 图表。安装之后需要理解它的预览模式。Markdown Preview Enhanced 默认在右侧显示预览你可以在预览窗口右键打开控制菜单里面有滚动同步、导出、打开预览到浏览器等选项。我体验最深的点是“滚动同步”左侧写代码右侧预览跟着走几百行的文档也能快速定位这点对长文档写作非常重要。默认预览主题是浅色如果你喜欢深色界面可以在它的设置里调整主题或者直接写自定义 CSS。3.2 表格编辑与 Excel 转换Markdown 表格的语法学习成本不高但手写经常对不齐。Markdown All in One 插件提供了格式化功能可以自动对齐表格列让源码更整齐。安装方法就是扩展市场搜 Markdown All in One装完之后在表格区域右键就能看到“格式化表格”的选项快捷键是全选后Shift Alt F它会把表格的竖线、空格排整齐。有人问 Markdown 表格怎么转成 Excel。实际场景里我经常要把内容粘贴到 Excel 或者飞书表格里。Markdown 表格复制到 Excel 最常见的问题是“不分列”所有内容挤在一个单元格里。解决办法有两种一种简单的方式是用文本编辑器把分隔符|替换成制表符Tab也就是|换成\t再粘贴到 Excel 就会自动分列另一种是在 Excel 里用“数据-分列”功能以竖线为分隔符手动拆开。如果你经常需要 Markdown 表格和 Excel 双向转换也可以去找专门的在线转换工具但注意数据敏感度内网环境我不建议把内容贴到外部网站。3.3 数学公式渲染Markdown 写作里需要数学公式的场景不少尤其是技术文档、算法说明、理工科笔记。标准 Markdown 语法本身不包含数学公式但 Markdown Preview Enhanced 和 Markdown All in One 同时支持 LaTeX 风格的公式渲染。写法很简单行内公式用单个美元符号包裹比如$E mc^2$块级公式用双美元符号包裹。部署时需要注意两件事。第一公式不渲染往往是因为缺了 KaTeX 或 MathJax 支持但 Markdown Preview Enhanced 已经内置了常用的数学渲染引擎一般不需要单独配置。第二在表格里塞公式要小心Markdown 表格对竖线敏感公式里如果出现竖线符号比如绝对值|x|就会破坏表格结构需要写成\|x\|。这是我在实际写作中踩过多次的坑刚接触时非常容易掉进去。3.4 Mermaid 图表的落地经验技术文档里画流程图、时序图、甘特图曾经是件麻烦事直到 Mermaid 这种用文本描述图表的方式出现。VSCode 生态里支持 Mermaid 的插件很多我常装的组合是 Markdown Preview Enhanced 配合 Markdown Preview Mermaid Support。Mermaid 的核心思路是用一种类似 Markdown 的简化语法描述图的结构。比如要描述一个流程大概的逻辑是“节点 A 指向节点 B节点 B 根据条件指向节点 C 或节点 D”把这种结构用文本写出来预览时插件会渲染成图形。用文本描述图表的最大好处是版本管理友好图随文档走改文字就能改图不需要打开庞大的图形绘制软件。实际部署提示多设备使用 Mermaid 时所有设备都需要安装预览插件否则换一台电脑打开文档只能看到描述文本看不到渲染后的图形。另外Mermaid 版本不断更新不同插件内置的版本可能不同如果一台电脑渲染正常、另一台渲染异常优先检查插件版本是否一致。3.5 图片路径最容易踩坑的地方图片路径问题大概是 Markdown 用户最热门的技术话题。很多人写文档时直接用绝对路径比如C:\Users\xxx\Pictures\img.png在自己的电脑上怎么都正常但一旦把文档复制给同事、推到 Git 仓库、或者换台机器图片全部裂图。正确做法是在 Markdown 里使用相对路径也就是把文档和图片放在同一个目录体系下引用时只写相对关系。比如一篇文章在docs/readme.md图片放在docs/images/1.png引用时就写images/1.png而不是整条盘符路径。VSCode 对图片路径还有一点额外帮助它内置了拖拽插入图片功能甚至一些插件支持粘贴剪贴板图片直接保存为文件。我常用的方案是 Paste Image 插件配置好pasteImage.path为${currentFileDir}/images之后截图、复制一张剪贴板图片直接在编辑器里粘贴它会自动把图片保存到当前文件的 images 目录下并生成相对路径引用。这个操作让 Markdown 写作的“插图体验”提升了一个档次不用每次手动保存图片再找路径。4. 进阶部署导出、模板与多设备还原4.1 导出 Word 和 PDF解决“序号自动编号”问题Markdown 写完之后的下一站往往是 Word 或 PDF特别是在职场环境里文档最终形态经常需要交给不熟悉 Markdown 的人。Markdown Preview Enhanced 内置 PDF 导出功能但它导出 PDF 的样式依赖你自己配置的 CSS默认样式凑合能用想好看还是得调。Word 导出我基本交给 Pandoc它是一款开源万能文档格式转换工具在命令行里一条命令就能把 Markdown 转成 Wordpandoc input.md -o output.docx --toc--toc参数可加可不加加上了会自动生成目录。Pandoc 在 Windows 下需要单独安装Linux 下用包管理器安装即可。这个方案比较土但非常稳定适合批量处理。关于“Markdown 转 Word 后序号自动编号”这个老大难问题我多说几句。Markdown 里无序列表用的是-有序列表用的是1. 2. 3.但导出到 Word 后Word 自带的标题样式默认不会自动编号跨章节的“1.1”“1.2”经常要手动调。Pandoc 导出的 Word 文档通常基于一个reference.docx模板你可以在模板里预先设置好标题的自动编号格式这样导出后就自动带编号。第一次配置模板有点麻烦但配好之后一劳永逸。社区里也有一些自动化工作流能处理“Markdown 转 Word 自动编号”核心思路都是提前定制 Word 样式而不是靠导出工具自动完成。4.2 写作模板与目录结构长期写作靠的是一套稳定的目录结构。我个人的 Markdown 仓库固定长这样notes/ ├── images/ ├── docs/ ├── templates/ │ └── article-template.md └── readme.md项目里有模板文件的话新建文档直接复制模板开头写标题、标签、日期等元信息后面再补正文。模板价值在于减少从零开始的决策成本。VSCode 里的文件资源管理器本身就很灵活新建文件、复制文件、快速重命名都非常顺手只要目录结构清晰整个仓库管理起来没什么压力。如果你需要更自动化的模板管理可选的插件方案是“Project Templates”它为不同项目预先定义模板文件可以在新建项目时一键套用。不过这类插件需要前期维护我个人的建议是不依赖插件模板文件放在 Git 仓库里随文档一起管理和分发更简单也更自然。4.3 配置备份与一键还原多设备部署最需要解决的是配置一致性问题。VSCode 的设置和插件列表可以同步方式有很多最简单的是用扩展 Settings Sync它可以同步settings.json、快捷键、插件列表到 Gist新机器上一条命令就能恢复相当于给编辑器做个“系统镜像”。不过我后来发现Gist 本质上是远程文本片段用起来是方便但如果你对代码托管没顾虑更推荐直接把整个配置目录交给 Git 管理。把settings.json、keybindings.json和extensions.json插件列表快照放到固定仓库里新机器克隆下来再用脚本批量安装扩展整个过程完全透明也方便团队统一。执行如下命令导出当前已安装的插件列表code --list-extensions extensions.txt新机器上想按列表安装所有插件while read -r ext; do code --install-extension $ext; done extensions.txt这套流程我用了很久实测下来比图形界面一个个重装省太多时间。4.4 顺带解决代码需求VSCode 本来就是代码编辑器部署完 Markdown 功能后写代码的需求也天然具备了。比如说配置 C/C 环境装个 C/C 扩展再装 Code Runner就能直接编译运行单文件Python 环境则更简单装 Python 扩展和 Pylance设置好解释器路径写脚本、跑测试都很顺畅。很多人喜欢“一台 VSCode 包打天下”也是因为这个生态太方便了。但这里有个提醒不要为了追求大而全把插件一股脑全装。每多一个插件编辑器启动速度和内存占用就多一点。我的原则是只在有真实需求时加装。比如长期不写 Java就不装 Java 扩展包等真遇到 Java 项目再部署不迟。5. 常见问题与排查技巧实录5.1 图片不显示到底哪里出了问题图片不显示是 Markdown 问题里最高频的一个。我自己排查时按顺序检查三件事第一路径对不对尤其是相对路径的基准目录很多人以为相对路径是相对当前文件实际上是相对 Markdown 文件所在目录确认一下图片文件真实位置第二文件名是否包含中文或特殊字符有些预览引擎处理中文路径会出问题我一般直接改成英文文件名第三图片格式是否被支持.webp、.SVG在不同预览器里的支持情况不完全一致必要时转成.png更稳妥。5.2 Markdown 换行为什么不生效一个特别经典的新手问题写完一行回车之后到下一行预览里却还是连在一起的。这不是 VSCode 的问题而是 Markdown 语法本身的定义。标准 Markdown 里单一换行不会产生新段落必须行尾加两个空格再回车才能实现真正的换行如果想要段落间距更好的做法是两行之间留一个空行。很多预览引擎还提供了“忽略标准语法、任意换行都生效”的选项比如 VSCode 内置预览的markdown.preview.breaks我们设置成true后每次回车就会在预览里产生换行但这偏离语法规范发布到某些严格平台时可能渲染效果不一样。我的建议是写作阶段随意发布前统一检查一遍格式。5.3 表格里的竖线被“吃掉”Markdown 表格结构靠|分隔如果你在单元格内容里也写了|比如“条件 A 或条件 B”写成“A|B”表格就会解析错乱。解决办法是使用转义写法\|在 Markdown 源码里写成 A\|B预览就会正确显示竖线。另一个相关的坑是表格里的代码块不要直接在表格里塞长篇代码要么把代码放到表格外要么用br控制单元格内的换行。5.4 预览公式和 Mermaid 图表时全是乱码公式不渲染或显示原始符号通常是因为你用了 Markdown 原文写在代码环境里但预览引擎没有启用数学渲染。使用 Markdown Preview Enhanced 后在文档开头可以加上!-- import style.less --之类配置但公式一般默认可用。Mermaid 不渲染更常见的可能一是流程图语法写错了节点定义和箭头书写不规范二是插件版本过低或没装全三是某些预览器在离线环境下无法加载 Mermaid 相关资源。排查时先拿 Mermaid 官方示例贴进文档测试如果示例能渲染而你写的不能多半是语法问题对照文档逐行改即可。5.5 新机器部署后的权限问题新电脑上部署 VSCode 后偶尔会遇到扩展装不上、预览无法打开、终端命令找不到等问题。Windows 上优先检查执行策略PowerShell执行Set-ExecutionPolicy RemoteSigned很多扩展脚本需要这个策略才能跑。Linux 上则要注意目录权限VSCode 扩展一般装在用户目录下如果某个扩展怎么都装不上可以尝试删掉扩展目录重新安装。遇到权限类问题别急着重装先看 VSCode 的日志通常它会在输出面板里明确提示哪些目录没有写入权限。我把常见问题整理成一个速查表方便你日后快速定位。问题现象可能原因快速处理图片全部显示裂图图片路径使用的是绝对路径改成相对路径并确保文件存在回车后没有换行Markdown 标准要求行尾空两格设置markdown.preview.breaks为 true或行尾补两个空格表格单元格里竖线丢失竖线被当成表格分隔符写成|转义公式显示为源代码预览引擎没启用数学渲染安装 Markdown Preview EnhancedMermaid 图表不渲染插件版本不一致或语法错误插件版本对齐用官方示例检测扩展装不上系统权限限制Windows 调整执行策略Linux 检查目录权限6. 一套能直接用到底的部署脚本与我的体验如果要从零开始在一台新设备上把整套环境搭起来直接执行下面的流程就行我给它起了个名字叫“markdown-deploy”。先安装 VSCode然后打开终端执行mkdir -p ~/.vscode-backup code --list-extensions ~/.vscode-backup/extensions.txt备份完现有配置后再看当前机器需要安装哪些扩展。单片机的逐条安装方式已经写在上面了你也可以直接写一个脚本一次性装完所有扩展。我整理了一套适用于大多数写作场景的必备扩展清单按优先级排序Markdown All in One表格格式化、列表缩进、目录生成。Markdown Preview Enhanced核心预览引擎支持公式、Mermaid、导出。Markdown Preview Mermaid Support增强 Mermaid 渲染兼容。Paste Image剪贴板图片直接粘贴保存为本地文件。Chinese (Simplified) Language Pack中文界面需要者自取。Settings Sync多设备设置同步。把这几个扩展装完基础写作能力就已经齐了。剩下的交给日常使用慢慢补充不要一次装完所有推荐列表。我见过不少朋友照着“最全插件清单”装完结果 VSCode 启动变得很慢菜单一堆选项不知道用哪个最后反而放弃了这个方案。在这套方案的实际使用中我最满意的一点是它的“可迁移性”。我可以在公司电脑上写一半回家后继续在个人电脑上打开同一个 Git 仓库接着写图片、目录、预览效果完全一致不用担心换设备后水土不服。文档全部是.md文本文件随时能转成 Word、PDF、HTML随时能放进自动化发布管道。它不像一个专用的 Markdown 编辑器反而更像一个围绕写作搭建的工作台。最后再分享一个细节心得我在所有设备上都绑定了 Git 仓库里的文档目录每次写完随手提交也算一种隐形备份。如果你也有多设备写作、长期文档维护的需求不妨按这个思路搭一套你会发现自己越来越离不开一个“会写文档的代码编辑器”。