如何解决VSCode中PlantUML拓展预览界面空白无法使用的问题

基础依赖校验 #

• 确认Java环境正常：PlantUML运行依赖Java 8及以上版本，打开终端执行java -version，确认能正常输出版本信息，若未安装先完成JDK/JRE安装并配置全局环境变量。
• 确认Graphviz安装正常：绘制非时序、活动类UML图需要Graphviz支持，终端执行dot -version确认版本输出正常，未安装可通过对应系统包管理器安装：Windows用Chocolatey执行choco install graphviz，Mac用Homebrew执行brew install graphviz，Linux执行对应包管理命令如apt install graphviz。

插件配置检查 #

• 打开VSCode设置，搜索PlantUML: Java，确认配置的Java路径和本地java命令的实际可执行路径完全一致，多Java版本环境必须填写完整路径。
• 搜索PlantUML: Graphviz Dot Path，确认配置路径和本地dot命令的实际可执行路径匹配，避免插件无法调用依赖。
• 检查是否开启强制离线渲染：若勾选该选项但本地依赖不全也会导致空白，暂时关闭该选项后重试。

问题场景修复 #

• 语法验证：新建空白.puml文件，粘贴最简测试代码验证渲染是否正常：

@startuml
user -> system : 测试请求
system -> user : 正常响应
@enduml

如果测试代码可正常渲染，说明原有文件存在PlantUML语法错误。

• 网络/代理排查：若开启了VSCode系统代理，部分渲染请求会被拦截导致空白，暂时关闭代理后重启VSCode重试。
• 插件冲突排查：禁用其他UML类、markdown预览类插件后重启VSCode，避免插件抢占渲染进程。
• 插件重装：以上操作都无效的话，卸载PlantUML插件后删除本地插件缓存，重新安装最新稳定版后重启VSCode即可。

内容的提问来源于stack exchange，提问作者Yannick Pezeu