VS Code 安装插件显示 Mermaid 渲染图完整手顺

目录准备工作1.1 安装 Visual Studio Code1.2 了解 Mermaid 和 Markdown安装必要的 VS Code 插件2.1 推荐插件清单2.2 插件安装详细步骤2.3 验证插件是否生效编写第一个带 Mermaid 的 Markdown 文件3.1 创建 Markdown 文件3.2 写入 Mermaid 代码块3.3 保存文件预览 Mermaid 图形4.1 打开预览窗口4.2 侧边栏预览最常用4.3 全屏预览4.4 预览自动刷新高级配置5.1 修改预览主题5.2 调整 Mermaid 渲染参数5.3 自定义 CSS 样式常见错误与解决办法6.1 预览窗口不显示图形只显示代码6.2 Mermaid 语法解析错误Parse error6.3 中文显示乱码或方框6.4 图形过大或过小6.5 侧边栏预览无法打开6.6 安装插件后仍然没有渲染6.7 与其它 Markdown 插件冲突进阶应用7.1 在 Mermaid 中使用主题和样式7.2 导出带 Mermaid 图形的 HTML/PDF7.3 结合 Pandoc 转换为 Word保留图形附录常用 Mermaid 语法速查8.1 流程图8.2 时序图8.3 状态图8.4 类图8.5 甘特图总结1. 准备工作1.1 安装 Visual Studio Code步骤 1下载 VS Code访问官网https://code.visualstudio.com/根据您的操作系统选择对应的安装包Windows、macOS、Linux。步骤 2安装 VS CodeWindows运行下载的.exe安装程序按向导操作。建议勾选以下选项“添加到 PATH”“注册为受支持的文件类型的编辑器”“将‘通过 Code 打开’添加到上下文菜单”macOS将下载的.app文件拖入 Applications 文件夹。Linux使用包管理器如sudo apt install code或下载.deb/.rpm安装。步骤 3启动 VS Code安装完成后从开始菜单或应用程序中找到 VS Code 并启动。首次启动可能会提示安装语言包可根据需要选择。常见问题如果启动后界面是英文想改为中文可以后续安装中文语言包在扩展商店搜索 “Chinese”。但本文不影响 Mermaid 显示。1.2 了解 Mermaid 和 MarkdownMermaid一种基于文本的图表绘制工具使用类似 Markdown 的语法定义流程图、时序图等然后自动渲染为矢量图形。Markdown轻量级标记语言常用于编写文档。在 Markdown 中可以用代码块包裹 Mermaid 代码格式为mermaid graph TD A[开始] -- B{判断} B --|是| C[执行] B --|否| D[结束] VS Code 本身不直接支持渲染 Mermaid需要安装插件。2. 安装必要的 VS Code 插件2.1 推荐插件清单为了在 VS Code 中显示 Mermaid 图形您需要安装一个支持 Mermaid 渲染的 Markdown 预览插件。以下三个插件均可实现推荐使用第一个插件名称特点推荐度Markdown Preview Mermaid Support轻量、专门为 Mermaid 设计安装即用无多余功能⭐⭐⭐⭐⭐Markdown Preview Enhanced功能强大支持 Mermaid、LaTeX、图表、幻灯片等但较重⭐⭐⭐⭐Mermaid Markdown Syntax Highlighting仅语法高亮不负责渲染需要配合其他预览插件⭐⭐本文以Markdown Preview Mermaid Support为主进行讲解它最简洁且与 VS Code 原生预览无缝集成。2.2 插件安装详细步骤步骤 1打开扩展视图方法一点击 VS Code 左侧活动栏的“扩展”图标四个方块组成的图标。方法二使用快捷键CtrlShiftXWindows/Linux或CmdShiftXmacOS。步骤 2搜索插件在扩展视图顶部的搜索框中输入Markdown Preview Mermaid Support。步骤 3安装插件在搜索结果中找到由Matt Bierner发布的同名插件。点击右侧蓝色的Install按钮。等待安装完成通常只需几秒钟按钮会变成Uninstall表示已安装。步骤 4可选安装其他辅助插件为了语法高亮可以再安装Mermaid Markdown Syntax Highlighting搜索安装即可。为了更好的编辑体验推荐安装Markdown All in One提供快捷键、自动补全、目录生成等。步骤 5重新加载 VS Code部分插件需要重新加载窗口才能生效。您可以按CtrlShiftP输入Reload Window并回车。或者直接关闭 VS Code 再打开。2.3 验证插件是否生效安装完成后无需额外配置。快速验证在 VS Code 中新建一个文件CtrlN。将语言模式设置为 Markdown点击右下角语言模式默认为“纯文本”选择 “Markdown”。输入以下内容mermaid graph LR A--B 按CtrlShiftV打开预览窗口。如果看到一条从左到右的箭头A→B则插件生效如果仍然显示代码块说明未生效请参考第 6 章的故障排除。3. 编写第一个带 Mermaid 的 Markdown 文件3.1 创建 Markdown 文件在 VS Code 中点击文件→新建文件或CtrlN。点击右下角的语言模式选择Markdown。保存文件CtrlS命名为example.md注意扩展名必须是.md。3.2 写入 Mermaid 代码块Mermaid 代码块以mermaid开头以 结尾。以下是一个简单的流程图示例# 我的第一个 Mermaid 图 mermaid graph TD Start[开始] -- Decision{是否继续?} Decision --|是| Action[执行操作] Decision --|否| End[结束] Action -- End 您也可以尝试时序图mermaid sequenceDiagram Alice-John: Hello John, how are you? John--Alice: Great! 3.3 保存文件按CtrlS保存。建议将文件存放在一个专门的文件夹中方便管理。4. 预览 Mermaid 图形4.1 打开预览窗口VS Code 提供两种预览方式侧边栏预览编辑与预览并排和全屏预览单独标签页。对于 Mermaid 图形侧边栏最为常用因为修改代码时右侧实时更新。4.2 侧边栏预览最常用方法一快捷键Windows/LinuxCtrl K V先按 CtrlK松开后再按 VmacOSCmd K V按下后编辑器右侧会立即出现一个预览面板显示渲染后的 Markdown 内容Mermaid 代码块会自动变成图形。方法二命令面板按CtrlShiftP或CmdShiftP。输入Markdown: Open Preview to the Side。选择并回车。方法三鼠标操作在 Markdown 编辑器区域的右上角有一个分屏预览图标带放大镜的页面右侧有一个分屏图标点击即可。预览效果左侧编辑 Mermaid 代码右侧实时更新图形。如果图形复杂可能需要等待 1~2 秒渲染。4.3 全屏预览快捷键CtrlShiftVWindows/Linux或CmdShiftVmacOS。全屏预览会打开一个新的标签页没有编辑器。适合最终阅读但无法同时编辑。4.4 预览自动刷新默认情况下每次保存文件CtrlS时预览会刷新。如果您希望实时刷新即输入时自动更新可以安装Markdown Preview Enhanced插件它支持实时渲染。但Markdown Preview Mermaid Support需要保存后刷新这是原生预览的行为也足够使用。技巧开启“自动保存”可以省去手动保存的步骤。点击文件→自动保存或者按CtrlShiftP输入Auto Save开启。这样每次编辑后自动保存预览会即时刷新。5. 高级配置虽然Markdown Preview Mermaid Support无需配置即可工作但您可以调整一些设置来改善体验。5.1 修改预览主题VS Code 的 Markdown 预览支持亮色/暗色主题与编辑器主题同步。但 Mermaid 图形有自己的主题default、forest、dark、neutral等。要修改 Mermaid 主题需要安装Markdown Preview Enhanced或在 Mermaid 代码块开头指定。方法使用 Markdown Preview Enhanced在 Markdown 文件开头添加 front-matter---mermaid:theme:dark---然后使用Markdown Preview Enhanced预览即可。如果只使用Markdown Preview Mermaid SupportMermaid 图形会使用默认主题通常为base无法直接修改。但可以通过自定义 CSS 间接调整颜色见 5.3。5.2 调整 Mermaid 渲染参数对于复杂图形您可能需要调整渲染尺寸或缩放比例。Markdown Preview Mermaid Support不支持参数配置。如需精细控制推荐Markdown Preview Enhanced它支持在 Mermaid 代码块中添加参数mermaid {scale: 1.5, theme: forest} graph TD A--B 5.3 自定义 CSS 样式您可以编写自定义 CSS 来改变预览中 Mermaid 图形的外观如字体、背景色、箭头样式。步骤在项目根目录下创建一个style.css文件。写入 CSS 规则例如.mermaid{background-color:#f0f0f0;font-family:Microsoft YaHei,sans-serif;}.mermaid .label{font-size:14px;}在 VS Code 设置中Ctrl,搜索Markdown: Styles添加一个路径style.css的绝对路径或相对路径相对于工作区根目录。重新加载预览窗口样式生效。6. 常见错误与解决办法本节汇总了用户在 VS Code 中使用 Mermaid 预览时最常遇到的问题及解决方案。6.1 预览窗口不显示图形只显示代码现象预览窗口中Mermaid 代码块保持原始文本没有变成图形。原因与解决没有安装支持 Mermaid 的插件请确认已安装Markdown Preview Mermaid Support或Markdown Preview Enhanced。如果已安装尝试禁用其他 Markdown 插件如Markdown All in One可能冲突但极少见。代码块语言标识错误必须使用mermaid不能是mermaid后有空格也不能是mermaid flowchat等其他标识。插件未激活重启 VS Code 或重新加载窗口CtrlShiftP→Reload Window。VS Code 版本过旧建议升级到最新版本目前 1.90。预览模式问题确保您使用的是Markdown: Open Preview to the Side或CtrlShiftV而不是其他非 Markdown 预览。6.2 Mermaid 语法解析错误Parse error现象预览窗口显示类似Parse error on line X...的错误信息或者图形部分缺失。常见语法错误中文标点符号未加引号错误示例动作: 存储DTC, 点亮警告灯正确写法动作: 存储DTC, 点亮警告灯节点 ID 中包含特殊字符错误A[Hello World!]感叹号可能被解析 → 使用引号包裹A[Hello World!]箭头或连接符格式错误错误A--|text|B中 text 含有未转义的引号。解决使用A--text with \quote\--B缺少空格错误graph TD;A--B缺少换行 → 必须每行一个语句。通用排查方法将 Mermaid 代码复制到在线编辑器如 Mermaid Live Editor中验证语法。检查错误提示的行号定位到具体位置。避免使用全角标点如中文逗号、句号除非用双引号包裹。具体到您之前的错误错误信息Parse error on line 7 ... 动作: 存储DTC, 点亮警告灯正是上述未加引号的问题。将描述文本用双引号包裹即可解决。6.3 中文显示乱码或方框现象图形中的中文显示为乱码或小方框。原因Mermaid 渲染时使用的字体不支持中文。解决方法一在 VS Code 预览中自定义 CSS强制指定中文字体参考 5.3 节。方法二安装Markdown Preview Enhanced并在其设置中指定 Mermaid 字体。方法三在 Mermaid 代码块中使用%%{init: {theme: base, themeVariables: {fontFamily: Microsoft YaHei}}}%%声明支持较新版本。示例mermaid %%{init: {theme: base, themeVariables: {fontFamily: Microsoft YaHei, sans-serif}}}%% graph TD A[开始] -- B[结束] 6.4 图形过大或过小现象Mermaid 图形在预览窗口中显示不全或者特别小。解决使用侧边栏预览时可以拖动预览窗口的分隔条来调整宽度。在 Mermaid 代码块中设置缩放仅Markdown Preview Enhanced支持mermaid {scale: 0.8}。全局设置在 VS Code 设置中搜索markdown.preview.scrollPreviewWithEditor等但无直接缩放选项。最有效的方法是使用Markdown Preview Enhanced并调整其mermaid配置。6.5 侧边栏预览无法打开现象按CtrlK V没有反应或者出现错误提示。原因当前文件不是 Markdown 文件扩展名不是.md。键盘快捷键冲突例如某些其他插件占用了CtrlK V。VS Code 键盘映射问题。解决确认文件语言模式为 Markdown右下角可见。尝试通过命令面板Markdown: Open Preview to the Side打开。如果仍然无效重置键盘快捷键CtrlK CtrlS打开快捷键设置搜索markdown.showPreviewToSide查看是否被修改。6.6 安装插件后仍然没有渲染现象按照步骤安装了Markdown Preview Mermaid Support但预览时还是纯文本。深度排查检查插件是否被禁用扩展视图中插件旁边是否有 “Disable” 按钮如果有表示已启用如果显示 “Enable”则点击启用。检查 VS Code 的设置中是否禁用了 Markdown 预览的扩展打开设置Ctrl,搜索markdown.preview.extension确保没有排除 Mermaid 相关插件。尝试卸载并重装插件。查看 VS Code 的开发控制台Help→Toggle Developer Tools→Console看是否有红色错误信息可能与网络或渲染进程有关。如果所有方法无效请考虑使用Markdown Preview Enhanced作为替代。6.7 与其它 Markdown 插件冲突现象同时安装了Markdown All in One、Markdown Lint等导致 Mermaid 渲染异常。解决暂时禁用其他 Markdown 插件逐一排查。已知Markdown All in One不会影响 Mermaid 渲染。Markdown Preview Enhanced与Markdown Preview Mermaid Support同时安装时预览默认会使用前者可能导致后者不生效。如果您希望使用后者可以禁用前者。7. 进阶应用7.1 在 Mermaid 中使用主题和样式Mermaid 支持内置主题default、forest、dark、neutral。在Markdown Preview Enhanced中可以全局配置。对于普通预览可以在每个图表前添加%%{init: {theme:forest}}%%。示例mermaid %%{init: {theme:forest, themeVariables: { background: #ffffff }}}%% graph TD A[主题示例] -- B[深色背景] 7.2 导出带 Mermaid 图形的 HTML/PDFVS Code 原生预览支持导出为 HTML右键点击预览窗口 →Copy→ 但无法直接保存。更好的方法使用Markdown Preview Enhanced它支持导出为 HTML、PDF通过 Chrome 打印、PNG 等。步骤安装Markdown Preview Enhanced。打开预览CtrlShiftV。右键点击预览 →Export→HTML或PDF。导出的文件中Mermaid 图形会以 SVG 或图片形式保留。7.3 结合 Pandoc 转换为 Word保留图形如您之前的对话将带 Mermaid 的 Markdown 转换为 Word 并保留图形可以使用 Pandoc mermaid-filter。但该方法容易遇到语法错误和依赖问题。更简单的方法是先用 VS Code Markdown Preview Enhanced 导出为 HTML。再用 Word 打开 HTML 文件或复制内容到 Word图形通常能保留。或者使用 Typora付费版直接导出 Word。8. 附录常用 Mermaid 语法速查为了让您快速上手这里列出几种最常用的 Mermaid 图表类型及其代码示例。8.1 流程图graph是否Start处理条件判断结束1结束28.2 时序图sequenceDiagram服务器客户端服务器客户端请求数据返回响应8.3 状态图stateDiagram-v2启动故障复位待机运行停止8.4 类图classDiagramAnimalint ageeat()DuckFish8.5 甘特图gantt2023-01-022023-01-032023-01-042023-01-052023-01-062023-01-072023-01-082023-01-09需求分析详细设计设计项目计划9. 总结通过以上手顺您应该能够成功在 VS Code 中安装插件并显示 Mermaid 渲染图。核心步骤总结如下安装 VS Code如果尚未安装。安装插件Markdown Preview Mermaid Support推荐。编写 Markdown 文件使用mermaid代码块。使用侧边栏预览CtrlK V即可实时查看图形。遇到错误时参考第 6 章的常见问题列表绝大多数语法错误都可以通过在线验证和引号包裹解决。进阶需求可安装Markdown Preview Enhanced获得更强大的导出和自定义能力。现在您可以愉快地在 VS Code 中绘制和展示 Mermaid 图形了如果在操作过程中仍有任何疑问欢迎根据错误提示进一步排查或查阅 Mermaid 官方文档https://mermaid.js.org/。