Mermaid插件安装后预览不显示需启用渲染器：VSCode 1.86+需设置"markdown.preview.mermaid": true；旧版需安装mermaid-cli并启用插件；流程图注意ID命名、缩进及标签格式；导出应使用mmdc命令行工具而非截图；协作推荐.mmd文件+显式语法声明。
Mermaid插件装了但预览不显示？检查渲染器是否启用
VSCode 默认不内置 Mermaid 渲染能力，光装插件 Mermaid Preview 或 Markdown Preview Mermaid Support 不够，必须确认底层渲染器已激活。常见错误是只装了插件却没启用 mermaid-cli 或 VSCode 内置的 Mermaid 渲染支持。
实操建议：
- 打开 VSCode 设置（
Ctrl+,），搜索markdown.mermaid.previewer，确保值为true - 若使用旧版插件（如
bierner.markdown-mermaid），需额外安装 Node.js 并全局运行npm install -g @mermaid-js/mermaid-cli，否则右键「Open Preview」会报错Command 'mermaid.preview' not found - VSCode 1.86+ 已原生支持 Mermaid（无需插件），只需在
settings.json中确认有："markdown.preview.mermaid": true
流程图语法写对了却乱码或错位？注意缩进与换行规则
Mermaid 流程图（graph TD）对空格和换行敏感，尤其在子图（subgraph）、链接标签、多行文本中容易出问题。不是所有 Markdown 预览器都等价处理这些细节。
实操建议：
- 节点 ID 避免用中文或空格，推荐用下划线命名，例如
start_node而非开始节点；否则某些渲染器会忽略该节点 - 链接语句后不能紧跟换行再写标签，要写成：
A -->|点击| B
，而不是A -->\n|点击| B
- 子图内节点定义必须缩进（至少 2 空格），且子图名后不能加冒号，正确：
subgraph Login\n login_btn\nend
；错误：subgraph Login:\n login_btn\nend
导出 PNG/SVG 失败或模糊？优先用 CLI 渲染而非预览窗截图
VSCode 内置预览窗是 HTML 渲染，右键「Save As」导出的 PNG 实际是网页截图，分辨率低、字体糊、不支持透明背景。真正可用的导出得靠 mmdc 命令行工具。
实操建议：
- 安装后验证命令是否可用：
npx mmdc --version（推荐用 npx 避免全局污染） - 导出高清 SVG：
npx mmdc -i flow.mmd -o flow.svg -t neutral，其中-t指定主题，neutral最接近 VSCode 默认配色 - 导出带透明背景的 PNG：
npx mmdc -i flow.mmd -o flow.png -b transparent；若出现字体缺失，加--puppeteerConfigFile puppeteer-config.json指定含args: ["--no-sandbox"]的配置
协作时别人打不开你的 .mmd 文件？统一用 .mmd 后缀 + 显式声明语法类型
Mermaid 代码混在 Markdown 里（```mermaid）时，VSCode 能识别，但 GitLab/GitHub 的 Mermaid 渲染器可能因版本差异跳过渲染；纯 .mmd 文件则更稳定，但需明确标注语法类型。
实操建议：
- 独立图表文件务必用
.mmd后缀（不是.md），并首行写明：%%{init: {'theme': 'base'}}%%，避免不同环境默认主题冲突 - 如果嵌入 Markdown，用三重反引号包裹时，语言标识必须是
mermaid（小写），不能写Mermaid或mermaid-js，否则 GitHub 不识别 - 团队共用时，在项目根目录放一个
.mermaidrc，内容为：{"theme":"neutral","securityLevel":"loose"}，部分 CLI 工具会自动读取
.mmd 文件 + mmdc CLI 导出 + 主题显式声明。别依赖预览窗截图交差。 
