VSCode中PlantUML插件默认本地渲染需Graphviz支持复杂图表，否则导出失败或黑屏；改用PlantUMLServer可跳过依赖快速验证，但离线导出必须正确安装并配置Graphviz路径。
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 代码块，除非你显式声明语言标签。常见错误写法：
```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 启动方式，四者只要一个脱节，就会在导出那一刻才暴露问题。
