很多人在入门 Markdown 的时候第一反应是去下载一个专用的 Markdown 编辑器试了一圈之后又回到 VS Code 里写文档。我自己的经历也差不多从最早的文本编辑器加 HTML 预览到后来用 Typora、语雀、Obsidian最后真正稳定下来长期用的反而是 VS Code。原因不复杂它免费、跨平台、插件生态足够丰富写 Markdown 的同时还能顺手改代码、配脚本、管文件一个窗口解决所有事。这篇内容我想分成两大部分。第一部分是 VS Code 里做 Markdown 写作的完整环境配置包括插件选择、预览设置、图片处理这些真正会踩坑的地方第二部分是 Markdown 基础语法把日常写文档最常用的语法过一遍顺便说清楚换行为什么不生效、图片路径为什么总挂、表格怎么做这些高频问题。适合刚接触 Markdown 的新手也适合已经用了一段时间但想优化 VS Code 写作流程的人。1. 为什么反复折腾编辑器最后留在 VS Code1.1 免费、开源、跨平台VS Code 是 Microsoft 出品的免费开源编辑器Windows、macOS、Linux 全平台覆盖。这个基础属性和 Markdown 的跨平台特性很搭你今天在 Windows 上写好文档明天换到 Mac 上继续编辑文件格式不会变编辑器行为也基本一致。很多人纠结要不要装某个 Markdown 专用软件其实要看的核心指标就三个一是能不能本地存储文件二是预览够不够快三是语法兼容性怎么样。VS Code 在这三点上表现得都比较稳尤其是本地存储这一点所有 Markdown 文档就是普通的 .md 文件没有私有格式不绑定任何平台想迁移随时能拿走。这也是我最终选择它的重要原因写的内容永远属于自己。1.2 从“写文档”到“写作代码发布”一条龙VS Code 的优势在于生态一个编辑器里能把 Markdown 写作、代码调试、版本管理、脚本执行全部串起来。你写技术文档的时候需要贴代码片段、跑命令、调格式如果用的是独立 Markdown 工具常常要在两个软件之间来回切换。而在 VS Code 里快捷键、终端、文件树都是现成的写完一段说明文字马上切到旁边终端跑个命令验证体验非常顺。另外很多人的工作流里还有文档转 PDF、转 Word、发布到博客平台这些环节。VS Code 通过插件系统基本都能覆盖Markdown Preview Enhanced 这类插件可以导出 PDF、HTML、Word 等格式配合 Pandoc 还能做更复杂的转换。这就让 VS Code 不只适合写博客也适合做项目文档、团队 Wiki、课程笔记甚至毕业论文初稿。1.3 谁适合用 VS Code 写 Markdown如果你是开发者那 VS Code 几乎是默认选择因为写文档和写代码天然在一个环境里。如果你是非技术背景的写作用户VS Code 的界面初看会比 Typora 这类沉浸式编辑器显得复杂一些但基本只用到编辑区和预览区其他面板都可以关掉适应一段时间后并不会觉得难。还有一个适合人群是需要在 Markdown 里嵌入代码、Mermaid 图表、LaTeX 公式的人。这类需求在普通编辑器里要么不支持要么支持得不好而 VS Code 的 Markdown 预览插件对这些扩展语法支持得很完整。简单说你只是想写个几百字的笔记用什么都行你打算长期维护一批结构化文档那 VS Code 值得认真配置一次。2. 先把环境准备好安装与初始设置2.1 下载安装避坑点VS Code 的官网下载页面会自动识别你的操作系统下载对应的安装包。Windows 用户建议选择 64 位用户安装器安装过程中有一步会问“选择其他任务”建议勾选“添加到 PATH”和“将‘通过 Code 打开’操作添加到文件和目录上下文菜单”这两个选项对日常使用非常方便能直接在文件夹右键打开编辑器。安装完成后可能遇到的一个常见情况是快捷键和中文输入法冲突尤其是 Windows 自带拼音输入法会把某些组合键吃掉。建议进入文件 - 首选项 - 键盘快捷方式先把不常用的快捷键清掉之后按自己的习惯绑定 Markdown 相关快捷键。macOS 用户则要注意VS Code 的默认快捷键和系统快捷键有部分重叠比如 Command, 是设置CommandB 是切换侧边栏和系统冲突时在偏好设置里调整即可。2.2 将界面设置成中文VS Code 默认是英文界面对英文不习惯的人第一印象可能不太好。设置中文很简单打开扩展面板搜索“Chinese (Simplified) Language Pack”这是微软官方出的中文语言包安装后右下角会提示重启重启之后就变成全中文界面了。有部分用户安装完语言包仍然显示英文原因是“显示语言”配置没刷新。可以按 CtrlShiftPmacOS 是 CommandShiftP输入“Configure Display Language”选择 zh-cn再重启一次。这个操作本质是修改 locale.json 文件直接改文件也行但用命令面板更不容易出错。2.3 工作区与常用快捷键Markdown 写作建议用“文件夹”方式管理而不是单个文件方式。把项目所有文档放进同一个文件夹VS Code 会自动建立工作区左侧文件树能看到全部文档和图片方便相互引用。如果你经常在多个项目之间切换可以把常用文件夹固定为“已保存的工作区”下次直接打开该工作区文件所有窗口布局、打开的文档、甚至终端都会被还原。常用的几个快捷键值得记下来CtrlShiftP打开命令面板几乎所有操作都能通过它执行CtrlK V在侧边打开 Markdown 预览CtrlShiftV切换 Markdown 预览到当前标签页CtrlB切换侧边栏显示Ctrl打开集成终端编辑时如果发现文字不换行需要开启自动换行功能。在设置里搜索“Word Wrap”把 Editor: Word Wrap 改为 on 即可否则长段落会出现横向滚动条非常影响阅读。3. Markdown 基础语法这些就够用3.1 标题、段落与换行标题语法很简单在行首加井号# 是一级标题## 是二级标题一直到 ###### 是六级标题。注意井号和文字之间要留一个空格这是很多人的第一个坑写成“#标题”在某些平台会被当作普通文本处理。段落是由空行分隔的连续文本块。很多人从 Word 转过来习惯用换行分段但 Markdown 里单独的换行不会产生新段落只会在渲染时被视为一个空格。如果确实想在某一行后面强制换行需要在行尾添加两个空格再回车。这个规则让不少新手困惑为什么回车了渲染出来还是连在一起。基础的解决方法是段落之间用空行分隔同一段落内不需要手动换行特殊情况需要强制换行时行尾加两个空格。有些编辑器和平台支持“结尾加反斜杠”的换行方式不过最通用、跨平台兼容性最好的仍然是两个空格。3.2 强调与列表加粗用两个星号包裹文字斜体用单个星号比如加粗斜体加粗斜体~~删除线~~列表有无序和有序两种。无序列表用减号、加号或星号加空格开头有序列表直接用“1.”、“2.”这类数字加点号。列表可以嵌套子列表在上一级基础上缩进两个或四个空格。这里容易踩的坑是数字列表的编号不连续有时渲染器会重新编号所以写有序列表时不用刻意维护序号全部写“1.”也能正常渲染成递增序号。3.3 链接与图片链接语法是方括号加圆括号 显示文字 。地址可以是外链网址也可以是相对路径的本地文件比如在同一个 docs 文件夹里引用其他 md 文件。圆括号里的地址如果包含空格最好用尖括号包起来或者对空格做百分比编码否则链接可能会断掉。图片语法和链接类似只是在前面多了一个感叹号。替代文字的作用是图片加载失败时显示的文本同时也方便屏幕阅读器读取不要省略。图片宽度在标准 Markdown 语法中没有定义如果需要对尺寸做控制可以借助 HTML 标签配合 style 属性大部分 Markdown 渲染器都支持这一点。3.4 引用、代码块与行内代码引用用大于号开头“ ”加空格。它通常用于标注他人的话、注意事项或文章摘录。引用可以嵌套多写一个大于号就是嵌套二级引用。引用块内部也可以包含列表、代码等块级元素这在写技术文档时很实用。行内代码用单个反引号包裹比如npm install。代码块用三个反引号包裹并在第一行的反引号后面标注语言类型比如javascript渲染时会自动做语法高亮。代码块内部不需要转义原样显示代码这比用文本编辑器写代码片段时手动调格式方便得多。这里有一个实用技巧在 VS Code 里选中代码后按 CtrlB可以直接把选区包裹成加粗按 Alt左箭头能跳回上一个光标位置代码书写效率会高不少。更常用的是输入三个反引号后直接按回车编辑器会自动生成代码块光标落在代码块内部非常顺手。3.5 表格、任务清单与转义字符表格是 Markdown 里最不好记的语法之一基本结构是表头行、分隔行、数据行。分隔行中的短横线数量不要求精确三个起即可冒号控制对齐方式左侧冒号左对齐两侧冒号居中右侧冒号右对齐。功能快捷键说明加粗CtrlB常见斜体CtrlI常见删除线无略少表格写起来容易手滑我建议直接借助 VS Code 的 Markdown All in One 插件来插入表格或者用在线表格生成器生成后再粘贴能省不少时间。表格语法不支持合并单元格这是 Markdown 表格的先天限制如果明确需要合并单元格只能回退到 HTML 表格。任务清单用减号加方括号的形式- [ ]表示未完成- [x]表示已完成。它非常适合做待办列表GitHub 和 VS Code 预览都支持直接勾选切换。转义字符方面Markdown 里像*、#、[这类特殊符号在需要原样显示时要使用反斜杠转义例如\*会显示星号。3.6 目录与锚点长文档需要一个可跳转的目录。VS Code 的预览侧栏自带大纲视图会自动按标题生成目录树展开后点击即可跳转这个功能比在正文里手动维护目录要省心得多。如果你需要在文档正文里放一个可点击的目录列表可以使用[TOC]语法但注意这个语法不是标准 Markdown部分编辑器支持、部分不支持。VS Code 默认预览对[TOC]不生效需要安装 Markdown All in One 插件它可以用命令面板生成真实目录序列效果是在指定位置插入一段带锚点链接的列表。GitHub 平台则不支持[TOC]只会在文档开头自动渲染目录。锚点跳转的通用做法是给标题后加自定义 id然后用链接指向它。例如### 注意事项 {#tips}然后在正文任何位置用[跳到注意事项](#tips)点击即可跳转。这种方式在多平台的表现比较稳定也是平时写长文最常用的办法。4. VS Code 的 Markdown 插件配置4.1 必装插件清单与作用VS Code 自带的 Markdown 功能已经可以编辑和预览可以做基础语法高亮。但要让写作体验接近 Typora、Notion 这类工具还是得装几个插件。我筛选下来最常用的是这四个插件名称作用推荐度Markdown All in One快捷键、目录、自动格式化、表格生成必装Markdown Preview Enhanced增强预览、导出 PDF/HTML/Word、支持 Mermaid强烈推荐Paste Image剪贴板图片直接粘贴为本地文件强推markdownlint语法规范检查减少格式错误建议装这几个插件不需要全装但前三个组合起来基本就把 VS Code 变成一个完整的 Markdown 写作环境。4.2 Markdown All in One 的细节用法Markdown All in One 是出镜率最高的 Markdown 工具插件它提供的核心能力包括快捷插入加粗、斜体、链接、代码块表格快捷插入以及自动目录生成。几个最常用的快捷键CtrlB加粗选中文字后直接生效CtrlI斜体AltC勾选/取消勾选任务清单表格生成输入后按 Tab 可以快速跳到下一格这个插件的“自动完成”功能也很实用输入标题后按回车会自动生成缩进的列表标记输入链接的方括号时会自动补全右括号。它还提供一个一次性把整个文档的所有列表自动编号的功能适合维护大型文档时统一格式。一个容易被忽略的命令是“打印到 HTML”。用 CtrlShiftP 调出命令面板输入“Print”它能按模板把你的 Markdown 文档渲染成一个独立的 HTML 文件尤其适合做快速分享或打包给同事。4.3 Markdown Preview Enhanced更好的预览与导出能力Markdown Preview Enhanced简称 MPE是 VS Code 里把 Markdown 功能上限拉高一个档次的插件。它的中文配置说明很全支持目录、图表、数学公式、绘图等丰富功能。MPE 支持 Mermaid 图表的渲染。写法是在代码块的语言类型里写 mermaid预览时就会自动渲染成流程图、时序图或甘特图。比如三个反引号加 mermaid里面写 graph TD 开头的节点关系预览区就能看到对应的图形。这让技术文档画图变得非常简单不用再打开独立绘图软件导图再贴回文档。MPE 的导出功能支持 PDF、HTML、PNG 等格式。导出 PDF 时建议先安装 Chrome 或 Edge 浏览器因为 MPE 默认调用 Puppeteer 驱动 Chrome 渲染 PDF没有浏览器会报错。导出 Word 则是通过 Pandoc 实现需要提前安装 Pandoc 并配置好路径。我在实际使用中导出最简单的 HTML 文件最稳PDF 如果文档里有中文偶尔会碰到字体问题把系统缺的字体补上就行。MPE 预览的滚动和同步也比默认预览强它在侧边打开时你滚动源码预览区会跟着滚动到对应位置鼠标悬停还能显示图片放大这些体验已经很接近专门写作软件。4.4 Paste Image解决粘贴图片的问题图片是 Markdown 写作最麻烦的一环。早期没有插件时要手动把截图保存到项目 assets 文件夹再手写图片路径效率极低还很容错。Paste Image 插件解决了这个问题截图复制到剪贴板后直接按 CtrlAltV它会自动把图片保存到指定目录并在光标位置插入图片语法。需要重点配置的是图片保存位置。常见做法是固定在当前文档所在目录下建一个 images 文件夹这样相对路径最稳定。之后主题里设置图片位置assets路径格式选择相对路径一个维持文件名不重复可以使用基于时间的自动命名。这样每次截图粘贴后图片自动落入 assets 目录文档引用的是相对路径拷贝整个项目文件夹到任何地方都不会丢图。这套流程配合同步网盘使用时特别舒服文件夹里既有 md 文件又有对应图片整个目录打包或同步文档在哪个设备打开图片都能显示。注意在配置 Paste Image 时插入的路径前缀不能写错否则 Markdown 里看到的是死链。4.5 自定义快捷键与用户设置 JSON插件装好后可能觉得默认快捷键不完全符合自己的习惯。VS Code 的“键盘快捷方式”面板可以搜索任意命令并重新绑定打开命令面板输入“Preferences: Open Keyboard Shortcuts”即可。如果希望一劳永逸可以直接编辑用户配置文件 settings.json。文件 - 首选项 - 设置右上角图标打开 JSON 文件在里面可以放一组自己的配置。比如常用的配置项包括开启自动保存files.autoSave: afterDelay设置默认 Markdown 预览风格markdown-preview-enhanced.previewTheme: github-dark.css关闭 markdownlint 某些规则markdownlint.config: { MD013: false }格式规范方面markdownlint 默认会检查很多规则其中 MD013 是行长度限制写中文长文时非常容易触发我一般直接关掉。MD024 是多个标题同名也是中文文档常见误报可按自己的需要关闭。5. 常见问题与排查技巧实录5.1 换行不生效这是 Markdown 新手最高频的问题之一。写文档时按了回车预览里文字却连在一起以为哪里没配置好。其实原因就是前面讲过的普通换行在 Markdown 里不算段落分割只有空行或行尾两个空格才会产生换行。处理办法有两种。写新文档时段落之间尽量用空行分隔不要依赖行内换行迫不得已要强制换行就在上一行结尾敲两个空格再回车。也有不少人为了省事把 VS Code 的“回车键直接换行”需求做成设置但 Markdown 语法标准决定了编辑器不能自动把普通回车识别为换行所以最终还是要靠两个空格。如果你想在预览里看到和源码一致的换行效果可以用 Markdown Preview Enhanced 设置里把换行符渲染成 br 标签。不过这样导出的 PDF 或者发布到平台后可能和预览不一致我不建议依赖这个设置。5.2 图片路径失效的排查思路图片不显示的排查步骤我从使用第一天踩坑后总结了一套固定流程先看预览区的图片链接是不是相对路径再看图片文件是不是真的存在于目标路径最后检查文件名是否包含中文或空格。路径写错是最常见的原因。使用相对路径时如果图片在 docs/images 下而你写的文档在 docs 根目录那么图片路径应当写成images/xxx.png不能多加或少加斜杠。文件名里的空格会导致部分渲染器解析失败可以把空格改成中划线或下划线或者使用 Git 等版本管理工具时顺便统一文件命名规范。VS Code 预览状态下Ctrl点击图片链接可以直接打开文件或跳转到对应位置。这个功能很强建议遇到死链时先用它验证路径是否正确。如果点击后能打开文件但预览不显示多半是预览缓存问题关闭重新打开预览即可。5.3 表格在预览和复制时变形Markdown 表格的标准语法在源代码里看起来比较乱尤其是单元格内容长短不一时。实际上这不会影响渲染效果但会影响源码可读性。如果表格特别多推荐两个工具一是在线 Markdown 表格生成器可以按行列填写并生成规范表格二是 Markdown All in One 的格式化命令可以统一对齐表格列宽。转换方面Markdown 表格要转成 Excel先用表格生成器把 Markdown 表格粘贴进去变成 HTML 表格再复制到 Excel 里打开数据就自动分离到单元格了这是最稳的免费转换路径。表格复制到各平台时比如从 VS Code 复制进微信文档或飞书文档很多编辑器不支持 Markdown 表格语法会原样显示成竖线。遇到这种情况先在本地渲染成 HTML再从预览页复制表格内容粘过去通常能保留表格结构。5.4 目录与大纲不显示用 Markdown 写长文时左侧大纲是导航利器。如果左侧没有显示大纲先看视图菜单里有没有勾选“打开侧边栏视图”中的“大纲”或者直接用快捷键 CtrlShiftO 跳转到某个符号。大纲只在文档存在标题时才有内容纯文本文档大纲是空的。使用 Markdown All in One 生成的目录不会自动随文档更新。当你新增或删除了标题需要再次运行命令重新生成目录。MPE 的目录则是基于文档标题实时生成的但格式不同看个人需求选择。如果切换了渲染器之前生成的锚点可能失效需要重新生成一次。5.5 Mermaid 图表预览不渲染Mermaid 图表在 MPE 里默认是支持的但版本差异会导致部分语法不被识别。如果你确认代码块语言名写的 mermaid 而且语法正确预览区却只有代码先检查 MPE 的配置项里 Mermaid 是否被禁用。有时安装其他 Markdown 插件会互相干扰可以临时禁用其他插件单独启用 MPE 再测试。Mermaid 图表的语法问题比较多的是节点文本里的特殊符号比如括号和引号需要在文本外加大括号或引号处理。画甘特图时如果日期格式写成2025-1-1部分版本解析有要求通常改成2025-01-01会渲染正常。遇到渲染失败时打开开发者控制台看具体报错一般能快速定位到语法问题。5.6 预览不刷新怎么办VS Code 默认预览是跟随光标实时更新的但文档特别长或者插件较多时预览偶尔不会立即刷新。最常见的解决办法是点击预览区右上角的刷新按钮或者关闭预览重新打开。如果你习惯分屏写作左侧源码、右侧预览一直开着建议把光标定位到要查看的位置预览会自动滚动到对应标题位置。如果遇到预览延迟可以用命令面板执行“Markdown: 刷新预览”强制刷新。另外最新版本的 VS Code 还把 Markdown 文件的预览默认升级成了更快的体验遇到底层渲染异常时重启 VS Code 是最直接的兜底方案。结语我的实际使用体会用 VS Code 写 Markdown 断断续续也有几年了中间也换过好几款编辑器但每次最后都会切回来。最重要的原因不是某个功能多强而是这个组合的确定性Markdown 文件本身是开放的VS Code 是稳定的插件生态给的自由度高。文档不怕锁死在某个软件里今天用 VS Code明天换其他工具文件拿到手照样能读。最后分享一个小技巧我习惯给每个写作项目单独建一个文件夹里面除了 md 文档还会建一个 assets 目录专门放图片然后把 Paste Image 的默认路径指向 assets。这样整个项目可以当做一个独立的知识库不管是同步到云盘还是打包发给别人都不会出现图片丢失的问题。新的项目直接复制这个文件夹当模板连配置都不用重新调。如果你也准备把 VS Code 当成长期写作工具不用一开始追求把所有插件都装全先装 Markdown All in One 和一个好用的预览插件上手写几天遇到实际痛点再补齐方案。工具的尽头是简单配置再多也不如把内容写好。