PlantUML在VSCode画图失败主因是插件、Java与Graphviz配置不当：须安装jebbs.plantuml插件，终端验证java -version和dot -V成功，文件后缀为.puml且编码UTF-8无BOM，保存后用Ctrl+Alt+D预览。
PlantUML 在 VSCode 里画图失败，90% 是因为插件没配对依赖，不是代码写错了。核心就三点：插件装对、Java 和 Graphviz 能被找到、文件格式和语法不踩坑。
PlantUML 插件选哪个？别用错名字
必须安装 jebbs.plantuml（作者名是 jebbs），不是 “PlantUML Language Support” 或其他同名插件。VSCode 扩展市场搜 “PlantUML”，认准发布者是 “jebbs”，安装后重启编辑器。
实操建议：
- 卸载所有旧版 PlantUML 插件，避免缓存干扰
- 安装后新建一个
test.puml文件，右下角语言模式应自动识别为 “PlantUML” - 不要装
markdown-preview-enhanced，它和 PlantUML 预览冲突，优先用markdown-all-in-one
Java 和 Graphviz 怎么才算“真装好了”？
VSCode 的 PlantUML 插件本身不渲染图，它只是调用本地 java 和 dot 命令。只要终端里跑不通，VSCode 就一定预览失败。
实操建议：
- 终端执行
java -version，输出必须含11、17（JDK 21+ 不稳定，慎用） - 终端执行
dot -V，必须输出版本号（如dot - graphviz version 11.0.0） - Windows 用户检查 PATH 是否包含
java.exe和dot.exe所在目录（例如C:\Program Files\Graphviz2.44\bin） - VSCode 设置中搜
plantuml.java和plantuml.graphviz.dot，填绝对路径，别信“自动检测”
@startuml 预览空白？先查这三件事
文件保存了、插件启用了、命令也通了，但右侧预览还是空——大概率是文件没被识别为 PlantUML 源码。
实操建议：
- 文件后缀必须是
.puml（.uml或.plantuml默认不触发预览） -
@startuml必须独占第一行，前面不能有空格、注释或 BOM 字符；@enduml同理 - 用快捷键
Ctrl+Alt+D（Win/Linux）或Cmd+Alt+D（macOS）触发预览，右键菜单有时延迟或失效 - 中文乱码？在
@startuml下一行加skinparam defaultFontName "Microsoft YaHei"（Win）或"PingFang SC"（macOS）
想离线渲染？别依赖在线服务
默认走 https://www.plantuml.com/plantuml，网络差、隐私敏感、中文注释还容易 400 错误。本地服务更稳。
实操建议：
- 下载最新
plantuml.jar（官网 plantuml.com/download） - 终端运行：
java -jar plantuml.jar -picoweb（端口默认 8080） - VSCode 设置中把
plantuml.server改成http://localhost:8080 - 顺手把
plantuml.exportFormat设为svg，缩放不失真，比 png 强得多
最常被忽略的点：预览不靠“实时”，靠“保存触发”。改完代码必须按 Ctrl+S，再按快捷键刷新，否则图不会更新。还有，.puml 文件编码必须是 UTF-8 无 BOM —— VSCode 右下角点一下编码，选 “Reopen with Encoding → UTF-8” 就能救回一堆白屏问题。
