1. 先聊聊为什么我坚持用VS Code写Markdown如果你经常写技术文档、记开发笔记或者维护个人博客Markdown一定不陌生。而编辑器这块我前后换过不少工具——Typora、Obsidian、Notion都试过最后真正稳定下来长期使用的反而是VS Code。原因很简单它原生支持Markdown而且不是那种“能编辑、能预览”的敷衍支持是真正把Markdown当成一等公民来对待。很多人第一次打开VS Code写Markdown可能只是觉得“哦有个预览按钮”但实际用久了会发现这套原生能力覆盖了从写作、排版到导出的完整链路。更关键的是VS Code本身是一个可无限扩展的编辑器Markdown只是它的基础能力之一你可以随时在这个基础上叠加各种插件把它变成适合自己写作习惯的专属工具。这篇文章我打算从原生功能、配置优化、高效写作技巧、常见问题这几个维度把VS Code写Markdown这件事讲透。不管你是刚开始接触Markdown的新手还是已经写了不少文档的老手应该都能在里面找到一些之前没注意到的细节。我也尽量把实际操作中踩过的坑、试出来的经验写出来方便你直接“抄作业”。2. VS Code原生Markdown能力的完整拆解2.1 原生不是“阉割版”基础编辑体验足够扎实先说结论VS Code对Markdown的原生支持绝对够用而且是经过精心设计的。它不是一个看不了预览、只能打字的纯文本编辑器而是从一开始就把Markdown的编辑体验做了一个完整的闭环。首先VS Code内置了Markdown语法高亮。这意味着你写#标题、**加粗**、- 列表的时候不同元素会有不同的颜色和样式一眼就能看出层级结构。相比纯文本编辑器里满屏都是黑色小字这种可视化反馈能大幅提升写作效率。语法高亮不是简单的颜色区分它会智能识别代码块、行内代码、链接、图片、引用块等不同节点连表格里的对齐线都会标出来。其次VS Code原生支持Markdown预览。打开一个.md文件后按快捷键CtrlShiftVMac上是CmdShiftV就会在右侧打开一个实时预览窗口你写的内容会立即渲染成最终的HTML效果。这个预览默认是同步滚动的——你在左边编辑到哪个位置右边自动滚动到对应位置两边是实时联动的。这个预览细节做得很好。它的渲染引擎用的是markdown-it和很多主流Markdown平台是同一个引擎所以预览出来的效果基本上和你发到网上的效果是一致的。我印象最深的是它支持details折叠块、任务列表的复选框交互甚至还能渲染数学公式后面会专门讲。另外VS Code原生支持图片的拖拽插入和粘贴。你只需要把图片文件拖进编辑区VS Code会自动生成相对路径的Markdown图片语法比如。如果是从剪贴板粘贴图片默认行为可能只是把图片文件保存到项目里路径问题需要配合插件调整。这一点在第三章会仔细说。2.2 智能感知与快捷操作原生功能里的隐藏宝藏除了高亮和预览VS Code还为Markdown内置了一些“隐藏”的智能功能很多人可能用了很久都没发现。第一个是标题导航。当你在编辑一个很长的Markdown文档时打开左侧的资源管理器文件列表上方会有一个“Outline”大纲面板它会自动解析你文档里的所有标题结构形成一棵树。你可以点击树上的任意节点直接跳转到文档对应位置。对于动不动几千行的长文档来说这个功能简直是效率神器不用手动滚动查找。第二个是路径智能补全。在写图片或链接的时候只要输入![或[VS Code就会触发文件路径的自动补全你可以从项目文件里选一个目标文件。这解决了手写图片路径容易出错的大问题尤其是项目结构比较深的时候。第三个是链接跳转。Ctrl点击Mac上是Cmd点击一个链接如果这个链接指向的是项目内的另一个文件VS Code会直接打开那个文件如果是锚点链接如#标题会跳转到文档内对应标题位置如果是普通网页链接会调用默认浏览器打开。这个功能让Markdown文档之间形成了一种“可点击的网状结构”写文档的时候真的有种“链接即导航”的感觉。第四个是代码块的语法检测。Markdown文档里嵌的代码块VS Code会按语言类型做高亮。如果你写的是JavaScript它甚至会在代码块内提供一部分语法检查和补全能力。对于技术文档来说这意味着你文档里的示例代码和真实代码一样具备可读性读者复制出去就能直接用。最后还有工作区的多文件搜索与替换。你可以在整个项目里搜一条文本快速定位哪个文档的哪一段写了这个内容然后一键全局替换。配合Markdown文档维护时批量更新链接、修改术语这个功能是刚需。2.3 原生预览的快捷键与组合技巧VS Code给Markdown预览准备了好几组快捷键很多人只记住了CtrlShiftV但其实还有别的CtrlShiftV在右侧打开预览边写边看。CtrlK V先按CtrlK再按V预览会以独立标签页形式打开适合需要更大预览空间的时候。CtrlK S打开快捷键大全但这不是Markdown专属算是编辑器通用功能。值得多说一句的是预览窗口并不是一个“静态渲染结果”它和编辑器之间是双向联动的。你可以把光标定位在编辑器中的某一行预览窗口会同步高亮对应的内容块反过来你在预览窗口点击元素编辑器也会把光标跳转到对应源码位置。这种双向定位对修改长文档特别有用我经常在预览里检查排版发现问题时直接点击定位回去改。预览窗口的左上角还有一个下拉菜单可以切换预览的渲染方式。默认是“Default”如果你装了Markdown Preview Enhanced插件这里会多出一些选项比如滚动同步方式、是否显示目录等。原生状态下够用但装了插件会有更多玩法这在第三章聊。3. 从原生到顺手值得补上的配置与插件3.1 基础配置让原生体验更贴合习惯虽然原生功能已经不错但有些默认行为还是不够“顺手”。我这里分享几个我长期使用的settings.json配置片段你可以按需复制到自己的配置里。{ // Markdown预览字体大小 markdown.preview.fontSize: 15, // 预览是否显示行号 markdown.preview.lineNumbers: off, // 编辑器内是否显示空白字符空格、Tab editor.renderWhitespace: none, // 自动保存 files.autoSave: onFocusChange, // 关闭编辑器的迷你地图把空间留给代码 editor.minimap.enabled: false, // 粘贴图片时自动生成相对路径 markdown.copyFiles.destination: ${documentDirName}/images/${documentBaseName}/, }这几项里最值得解释的是markdown.copyFiles.destination。这个配置是VS Code内置的“复制文件”功能当你把外部图片粘贴到Markdown文档中时VS Code默认会把图片保存到当前文档所在目录下。如果你不设置图片可能散落在项目各处。我自己喜欢把每个文档的图片统一放在文档名/images/的子目录里这样打包文档、迁移项目都很干净。另外files.autoSave我设置成onFocusChange意思是当光标离开当前文件、切换到其他文件时自动保存。写Markdown的时候经常忘记按CtrlS开了自动保存之后预览一直是实时渲染的不怕丢失内容。3.2 扩展推荐面向不同写作场景的插件组合VS Code的Markdown生态很丰富但插件不是装得越多越好装多了反而会拖慢启动速度、造成配置冲突。我建议按自己的场景来选下面这套组合是我在不同项目中实测过的插件名称解决的问题适用场景markdownlint检查Markdown语法规范提示标题层级、空行、列表格式等问题文档规范要求严格的团队项目Markdown Preview Enhanced增强预览效果支持导出PDF/HTML支持自定义CSS、数学公式、流程图等需要专业排版的文档、幻灯片、论文Paste Image粘贴剪贴板图片时自动保存到指定目录并生成Markdown语法写作时经常需要截图插入文档Word Count CJK显示中文字数统计写博客、公众号文章时需要统计字数Markdown All in One自动补全、格式化表格、快捷键生成标题、列表自动续写等日常写作的核心助手值得优先安装这里面我特别想展开说两个markdownlint和Markdown Preview Enhanced。markdownlint是一个基于规则集的检查工具类似代码里的ESLint。它默认开启很多条规则比如标题层级不能跳级、列表前面空行、行尾不要多余空格等。刚用的时候可能会觉得“哪来这么多提示”但适应之后你会发现它能在很大程度上保证多人协作时文档风格统一。比如团队约定所有标题从一级开始、列表统一用-不用*加了规则后成员写进去的内容会自动被检查。Markdown Preview Enhanced以下简称MPE则是我强烈推荐的重型插件。它不仅把预览效果提升了一个档次还能直接导出PDF、HTML、PNG甚至PPT风格的手稿支持数学公式渲染MathJax/KaTeX、支持用mermaid画流程图虽然我在本文不展开mermaid但它能支持、支持自定义CSS主题还内置了目录TOC生成。如果你的Markdown文档最终需要提交给非技术同事阅读或者要打印成PDF存档MPE几乎是最好的免费方案。3.3 定制预览样式让你的Markdown看起来更高级很多人写Markdown的时候会觉得默认预览样式有点“素”——标题不够突出、代码块样式一般、间距偏窄。其实你不用把文档复制到别的工具里调整只需要给预览窗口配一套自定义CSS就能让所有.md文件渲染出你喜欢的风格。方法不复杂在settings.json里设置markdown.styles数组填入本地或远程的CSS文件路径。markdown.styles: [ https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown.css, style/custom.css ]如果你没有现成的CSS也可以从网上下载一些开源的Markdown样式比如github-markdown-css它会自动把你的预览页面变成GitHub风格的排版代码块、表格、引用块的样式都会好看很多。更进一步可以在项目目录里放一个custom.css自己覆写标题颜色、边框、间距等细节。我自己常用的做法是远程引入github-markdown-css本地放一个custom.css在里面把body字体调成“等距更舒服的中文字体”同时给表格加个hover效果。这套配置在公司内部分享文档的时候观感非常好几乎不需要再用Word调整格式。4. 实操从零搭建一个Markdown写作工作流4.1 场景拆解一篇技术博客是怎么在VS Code里完成的理论说了一大堆不如直接走一遍完整流程。我自己写技术博客的日常是这样的打开VS Code新建一个项目文件夹里面放docs、images两个目录然后新建一个post.md文件开始写。这个项目的结构大概长这样my-blog/ ├── docs/ │ ├── images/ │ │ ├── post-cover.png │ │ └── screenshot-01.png │ └── post.md └── style/ └── custom.css写作的时候我一般开着两个窗口左边是编辑区右边是CtrlShiftV打开的预览窗口。边写边看效果空格、空行、加粗、列表都能即时反馈。如果某个地方格式乱了不用切到别的地方直接在预览里点击跳回源码改。写完之后我还会做一次“文档体检”用markdownlint的提示检查有没有漏空行、标题层级乱跳。用Word Count CJK看看字数判断文章长度是否合适。用Markdown All in One的“格式化表格”功能把表格对齐统一一下。最后如果需要发布到某个平台我会把Markdown内容直接复制过去或者先用Markdown Preview Enhanced导出成HTML再复制HTML内容。如果平台支持Markdown导入这一步几乎零成本。4.2 表格、公式、代码块的实战写法写作过程中最常见的三个复杂元素是表格、数学公式和代码块我把它们单独拎出来讲讲。Markdown表格的语法本身不复杂但手工对齐会让人崩溃。比如| 工具 | 是否支持Markdown | 导出格式 | 备注 | | ---- | ---- | ---- | ---- | | VS Code | 支持 | HTML/PDF/图片 | 需要安装相关扩展 | | Typora | 支持 | HTML/PDF/Word | 老牌编辑器 | | Obsidian | 支持 | HTML/PDF | 双链笔记利器 |写完这个表格后如果你用了Markdown All in One可以打开命令面板CtrlShiftP运行“Format Document”或者“Markdown All in One: Format Table”它会自动把表格里的空格对齐成等宽。这样在源码里看也是整整齐齐的预览里更是正正方方。数学公式方面VS Code原生预览支持的公式能力有限。如果你写的是数学相关的文章我建议安装Markdown Preview Enhanced然后在文档里用$...$写行内公式、用$$...$$写块级公式。渲染时选择MathJax或KaTeX引擎。我一般选KaTeX速度更快。比如质能方程可以用 $Emc^2$ 表示也可以用块级公式表示 $$ E mc^2 $$代码块的处理就更简单了。用三个反引号加上语言标识符比如pythonVS Code会自动做语法高亮。如果你还想在代码块里显示文件名可以用MPE插件支持的属性语法但这属于进阶内容默认的代码块语法已经足够。4.3 导出与发布一份Markdown多种用途Markdown最大的优势之一就是“一次编写多处发布”。这里我按不同目标场景列出我常用的导出方案发布到博客平台直接把Markdown源码复制到平台的Markdown编辑器里比如掘金、CSDN、知乎都支持简单粗暴。发布到微信公众号微信公众号不支持Markdown我的做法是先用Markdown Preview Enhanced导出为HTML再用浏览器的“复制为富文本”粘贴到公众号编辑器里。或者用一些在线转换工具。打印/存档为PDF在Markdown Preview Enhanced预览页里右键选择“Chrome (Puppeteer) 导出为 PDF”或“Prince 导出为 PDF”可以生成排版精美的PDF。MPE自带的导出选项非常成熟。转成Word这是很多办公场景的需求。我的办法是先导出HTML再用Word打开HTML文件另存为docx或者直接把文本复制进Word再做样式微调。如果你有更自动化的需求可以研究一下Pandoc它能直接把Markdown转成Word但需要额外安装命令行工具。这里顺便提醒一句搜索结果里经常能看到“vs code下的markdown预览导出乱码”这类问题大部分是因为导出PDF时没指定中文字体或者CSS里没有设置UTF-8编码。我的经验是导出PDF前先确认预览界面文字显示正常再检查系统是否安装了中文字体。如果乱码可以尝试换用Prince导出方式Prince对中文字体支持相对更好。4.4 方便好用的“半自动”写作组合拳除了手动写作VS Code还能帮你把一部分重复动作变成半自动这里介绍几个我个人每天都在用的小技巧。技巧一快速创建带日期的文档我习惯把笔记文件名加上日期比如2024-06-15-关于XX.md。每次新建文件时手打日期很麻烦虽然可以用系统日期但不够内嵌。我的做法是用VS Code的代码片段功能Snippets在Markdown文件里输入date然后按Tab自动插入今天的日期。当然这不是Markdown专属但确实大幅减少了我写文档头部的机械劳动。技巧二把常用模板存成代码片段经常写技术方案的人可能每次都会有一个固定模板标题、背景、方案、总结。这个模板完全可以做成Snippet每次新建文件时输入几个字母直接生成一大段框架。Snippet里支持占位符$1、$2写完第一个位置按Tab跳到下一个。技巧三用任务清单管理文章进度如果一篇文章很长我习惯在文首放一个任务清单- [x] 搭好文档框架 - [ ] 写第一章 - [ ] 补充截图 - [ ] 校对排版在预览里这些复选框是真实可点击的写一段就点一个进度一目了然。这也是VS Code原生渲染支持的功能不需要插件。5. 常见问题与排查实录5.1 安装插件时提示“EPERM: operation not permitted”这个问题在Windows上特别常见。很多人第一次装插件时VS Code会报错Error: EPERM: operation not permitted看起来像是权限不够或者文件被占用。我排查过几次大部分原因是VS Code的插件安装目录权限问题或者杀毒软件拦截了扩展目录的写入。解决思路是按顺序试以管理员身份运行VS Code再安装插件。如果还不行关闭杀毒软件的实时防护再次安装。检查扩展目录%USERPROFILE%\.vscode\extensions是否被设置为只读取消只读属性。实在不行重装VS Code注意不要装到C盘权限过紧的路径下比如Program Files可以装到用户目录或D盘。这个问题和Markdown没有直接关系但很多新手第一次装插件就卡在这里容易误以为“VS Code坏了”所以值得专门提一下。5.2 预览乱码或样式错乱怎么办Markdown预览乱码有两种常见情况。第一种是文档内容本身就是乱码。这多半是因为文件编码问题。VS Code默认是UTF-8但如果你打开的是一个GBK编码的文件编辑器可能识别不了。解决方法是点击右下角的编码按钮重新选择“通过编码重新打开”选UTF-8即可。第二种是预览时中文显示成方块或者乱码。这更多是字体问题。在Windows上VS Code预览默认会使用系统中的中文字体如果字体缺失可以手动在settings.json里指定字体markdown.preview.fontFamily: Microsoft YaHei, PingFang SC, sans-serif另外如果你自定义过markdown.styles也可能是CSS引入的资源路径不对导致渲染异常。检查一下CSS文件是否存在于指定路径或者远程链接是否可访问。5.3 表格复制散架、粘贴图片路径不对很多人写Markdown表格的时候从其它工具复制一个表格过来粘贴到VS Code后表格语法可能不是Markdown格式或者格式乱了没法渲染。我的经验是从Excel/CSV复制过来的数据别直接粘贴。先在编辑区里按CtrlShiftP运行“Markdown All in One: Insert Table”或者手动把数据粘到一个临时文件再选择数据用命令把它转成Markdown表格。从网页复制表格浏览器里表格一般是HTML格式VS Code不会自动转成Markdown。需要先粘贴到一个支持“HTML转Markdown”的地方再用转换结果。图片粘贴路径的问题前面提过设置好markdown.copyFiles.destination之后粘贴图片会自动存到指定目录再插入相对路径引用。如果用的是第三方插件Paste Image它有自己的配置项可以设置图片保存路径但要注意不要和VS Code原生的图片复制功能冲突否则会出现“粘贴一次生成两张图”的情况。我的建议是二选一如果你装了Paste Image就把VS Code自带的markdown.copyFiles禁用或者在Paste Image的配置里把路径设置成和原生一致保持统一。5.4 与周边工具联动时容易踩的坑这几个月里我注意到社区里很多人在研究VS Code与AI工具的联动比如把本地大模型接入编辑器的聊天窗口或者在Markdown文档里直接生成内容。这里面的坑主要是配置路径和环境变量。以Ollama为例如果你想在VS Code里通过某个AI插件调用本地模型你需要在插件配置里指定Ollama的服务地址通常是http://localhost:11434。第一次调用时插件会去拉模型列表如果一直超时先检查本地的Ollama服务是否启动再检查代理设置。另外Windows下本地模型的显存占用要留意连续生成内容时可能因为显存不足导致编辑器崩溃。还有一个容易忽略的点很多AI插件会把生成的Markdown内容直接插入到当前光标位置。如果你写文档时习惯把光标停在代码块内部插入的内容可能被嵌套在代码块里导致Markdown渲染异常。我建议使用这类插件时先把光标移到文档外层再触发生成或者在生成后再检查一遍格式。5.5 常见问题速查表为了你排查方便我把上面提到的问题整理成一张速查表现象可能原因快速解决插件安装报EPERM权限不足/被杀软拦截管理员运行VS Code调整扩展目录权限预览中文乱码文件编码或字体问题重新以UTF-8打开手动指定中文字体复制表格后格式乱数据源不是Markdown格式用“Markdown All in One”转换表格粘贴图片后没反应路径未配置/插件冲突检查markdown.copyFiles.destination或Paste Image配置预览内容与编辑不同步文件未保存/预览缓存开启自动保存强制刷新预览导出PDF乱码中文字体未安装安装中文字体推荐Prince导出方式AI插件生成卡顿Ollama服务异常或显存不足检查服务状态重启Ollama关闭无关大模型进程这些问题基本都是我或者身边朋友实际遇到过的。处理思路的核心是“先确认基础环境再查插件配置”不要一上来就重装编辑器那样成本太高而且很多时候重装并不能真正解决问题。6. 适合进阶用户的“更野”玩法6.1 用Markdown做幻灯片、报告和笔记体系Markdown不只是写博客的工具它还能做很多“办公室场景”里的事。比如你想做一个简洁的幻灯片不需要打开PowerPoint装好Markdown Preview Enhanced后可以在一个Markdown文件里用---分页# 第一页标题 - 要点一 - 要点二 --- # 第二页标题 | A | B | | -- | -- | | 1 | 2 |然后在预览窗口中点击右键选择“Open in Browser”再配合浏览器的全屏模式或者直接导出为HTML/PDF/PPT就能得到一套简单但不简陋的幻灯片。这个用法特别适合内部技术分享省去了来回切换Word、PPT的时间。做报告也一样。把项目进展、数据表格、代码示例全部写在Markdown里统一排好版后导出PDF整个文档的质感和Word写出来差不太多但维护成本低得多。我有一次给客户写需求分析文档全程用VS Code写Markdown最后导出PDF客户那边的反馈是“排版很清晰”。笔记体系更是Markdown的强项。你可以用VS Code打开一个专门的笔记文件夹里面按时间或主题创建多个.md文件再用大纲面板快速切换。如果你想增加跳转关系就用相对路径链接互相链接形成一套自己的知识库。6.2 把Markdown文件变成网站或内部知识库如果你写了很多Markdown文档想把这些文档发布成一个可供团队访问的小网站其实不需要上复杂的CMS。我试过用docsify或VitePress这类静态网站生成器它们天然支持把Markdown文件渲染成网站页面而且配置非常简单通常是装一个Node包、写一个配置文件然后把Markdown文件放进指定目录即可。这种方式的优势在于你不需要把文档从一个工具复制到另一个工具所有内容都维护在本地Markdown文件里改完之后执行一遍构建命令或者配置自动部署团队成员就能在浏览器里看到最新版。这对团队内部的知识库、接口文档、运营手册特别实用。如果你用的是VitePress你还可以利用它支持Markdown扩展语法的能力在文档里写自定义容器、代码组等排版会更灵活。但核心还是Markdown本身VS Code全程作为编辑器配合预览和lint生产效率非常高。6.3 与本地大模型、代码生成类插件结合2024年以来AI辅助编码和写作工具变得非常流行很多插件都能在VS Code里直接调用大模型生成Markdown内容。如果你想体验“在Markdown文档里让AI帮你起草段落”可以考虑配置本地模型比如Ollama或者插上你习惯的AI服务。我个人的建议是不要把AI当成文档的唯一作者而是当成一个“初稿生成器”。比如你要写一段关于某个接口使用的说明可以先让AI生成一版Markdown草稿然后手动校对、补充细节、调整格式。因为Markdown本身是纯文本你完全可以把AI生成的内容复制到VS Code里逐段审阅而不用打开任何额外工具。这个工作流我自己用下来最大的收益是节省了“从空白页开始”的启动成本而不是完全甩手。不过要注意AI生成的内容可能存在事实性错误或者格式不规范。如果你把它直接发布到正式文档里容易被人看出“机翻味太浓”。我的做法是至少在VS Code里跑一遍markdownlint再通读一遍把术语和风格统一成自己的。7. 我对这套工作流的真实体会写到这里我想聊一点自己的感受。VS Code并不是一个纯粹的“Markdown编辑器”它的定位是通用代码编辑器但正因为它把Markdown原生支持做得扎实反而让我这种喜欢折腾工具的人找到了一个稳定的落脚点。你不必为了Markdown单独安装一个软件也不用在各个编辑器之间反复横跳。装好VS Code配好插件一个人的文档工作流基本就能跑通。我日常的使用习惯是电脑上的VS Code长期开着随手新建一个.md文件就能开始记录无论是会议纪要还是技术方案写到中途发现需要插图直接截图粘贴路径自动归位改完一轮用预览看一眼排版然后导出HTML或PDF发给同事。整个过程没有离开过这个编辑器。当然也会有人觉得VS Code默认配置不够好看、需要折腾CSS和插件这个门槛确实存在。可换个角度想这种可定制性也带来了别的编辑器给不了的灵活性。花一下午时间把环境调成自己顺手的样子之后每一篇文章的产出都会受益。最后再分享一个小技巧如果你在团队里整理文档记得把所有.md文件统一放到项目根目录下图片统一放在images文件夹中同时要求大家把文件编码固定为UTF-8。这样无论谁接手打开VS Code都能直接预览不会出现路径断裂或者字符乱码的问题。文档的整洁度和代码的整洁度一样重要都是长期合作的润滑剂。