VSCode安装PlantUML工具架构设计VSCode自动绘图方案-VSCode-PHP中文网

VSCode中PlantUML插件默认本地渲染需Graphviz支持复杂图表，否则导出失败或黑屏；改用PlantUMLServer可跳过依赖快速验证，但离线导出必须正确安装并配置Graphviz路径。

vscode安装plantuml工具架构设计vscode自动绘图方案

VSCode 里装 PlantUML 不需要 Java 环境也能跑，但想稳定导出活动图、组件图这类复杂图表，Graphviz 必须配好；否则预览能看，导出就卡在 java.lang.NullPointerException 或直接黑屏。

PlantUML 插件安装后为啥不渲染？检查 `plantuml.render` 配置

插件默认走本地渲染（plantuml.render 值为 Local），但新版插件内置的 JAR 包只支持基础类图/时序图；一旦用到 activityDiagram、componentDiagram 或带布局逻辑的图，就会因缺少 Graphviz 引擎报错或静默失败。

解决方法很直接：

打开 VSCode 设置（Ctrl+,），搜索 plantuml.render，改成 PlantUMLServer —— 这会走官方远程服务，跳过本地依赖，适合快速验证
若需离线、批量导出或自定义样式，必须本地装 Graphviz，并在系统 PATH 中可用（验证命令：dot -V）
不建议手动改 plantuml.jar 路径：插件新版已弃用该配置项，强行指定反而触发 ClassNotFoundException

Graphviz 安装踩坑最多：Windows 用户别信一键 exe 安装包

官网下载的 graphviz-2.49.msi 类安装包，默认不勾选「Add Graphviz to the system PATH」，装完 dot -V 仍报 command not found。更隐蔽的问题是：它把 dot.exe 放在 C:Program FilesGraphviz2.49in，但 PATH 只加了 ...Graphviz2.49 根目录，漏掉 in 子路径。

稳妥做法：

卸载现有 Graphviz，改用 Chocolatey（Windows）：choco install graphviz，自动处理 PATH
macOS 用户用 Homebrew：brew install graphviz，无需额外配置
Linux 用户注意发行版差异：Ubuntu/Debian 用 apt install graphviz 即可；CentOS/RHEL 需先启用 EPEL 源再 yum install graphviz

Markdown 里嵌 PlantUML 代码块，预览不生效？确认语言标识符

VSCode 的 Markdown 预览器不会自动识别 PlantUML 代码块，除非你显式声明语言标签。常见错误写法：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

```plantuml
@startuml
A --> B
@enduml
```

这行不通——插件只认 ```puml 或 ```plantuml，但部分旧版插件甚至只响应 ```puml。实测最兼容的是：

用 ```puml 开头，不是 ```plantuml
确保文件后缀是 .md，且已安装 markdown-all-in-one 插件（markdown-preview-enhanced 会冲突）
如果预览仍空白，右键 Markdown 预览页 → “Open Preview to the Side”，再按 Alt+D 手动唤出 PlantUML 面板

导出 PNG 失败提示 `Cannot find Graphviz dot executable`？别只查 PATH

PATH 正确、dot -V 有输出，但 VSCode 里导出仍失败，大概率是插件没读到环境变量——尤其 Windows 下用非管理员权限启动 VSCode，PATH 可能被截断或继承不全。

绕过方案：

在 VSCode 设置中显式指定 plantuml.graphvizDot 路径，例如：C:\Program Files\Graphviz\bin\dot.exe（注意双反斜杠）
macOS/Linux 用户若用 zsh，确保 dot 在 ~/.zshrc 里 PATH 已 export，且 VSCode 是从终端用 code 命令启动的（否则 shell 配置不加载）
导出前先手动运行一次预览（Alt+D），插件会缓存 Graphviz 路径；若预览都失败，导出必然失败

真正麻烦的不是装不上，而是装上了但插件找不到——Graphviz 的路径、权限、shell 环境、VSCode 启动方式，四者只要一个脱节，就会在导出那一刻才暴露问题。