PlantUML在VSCode中需配置Java、plantuml.jar和Graphviz三依赖才能预览；默认在线渲染有隐私与性能限制，本地渲染需启动-picoweb服务并正确设置路径；类图关系线错位多因语法空格或符号方向错误。
PlantUML 在 VSCode 里不是“装了插件就能用”，它本质是个 Java 程序，VSCode 插件只是个调度器。没配对后端渲染方式，.puml 文件永远只是一堆带颜色的文本。
为什么按 Alt+D 没反应？——检查三个硬依赖是否就位
预览失败绝大多数情况不是插件问题，而是后端缺失或路径错位：
-
java命令必须可用，且版本在 JDK 8–17 范围内（JDK 21+ 已知与plantuml.jar1.2024.x 不兼容） -
plantuml.jar必须下载并填入完整绝对路径（Windows 用正斜杠C:/path/to/plantuml.jar或双反斜杠；macOS/Linux 用/Users/xxx/tools/plantuml.jar） - 若启用 Graphviz 渲染（如类图、组件图），
dot命令需能执行，且 VSCode 设置中plantuml.graphviz.dot必须指向真实可执行文件（不是目录，不是别名）
在线 vs 本地渲染：选哪个？——看你的场景和隐私要求
默认走 https://www.plantuml.com/plantuml 是最省事的，但有明显限制：
- 图表内容会发到公网服务器，含敏感业务逻辑或内部接口名时禁止使用
- 离线环境完全不可用
- 大图或批量导出时响应慢，偶尔返回 502 或超时
本地渲染更可控，但要多两步：
- 启动服务：终端运行
java -jar /path/to/plantuml.jar -picoweb（端口默认 8080） - VSCode 设置中把
plantuml.server改成http://localhost:8080
注意：-picoweb 模式不依赖 Graphviz，适合快速验证；但若需精确布局（如类图中继承线对齐），仍得配好 dot 并设 plantuml.render 为 image。
类图关系线总画歪？——语法空格和符号方向是关键
PlantUML 解析器对空白字符极其敏感，关系线失效常因以下细节：
- 继承写成
ClassA ，不能写成 <code>ClassA（<code> 前后必须有空格） - 聚合用
o--，组合用*--，箭头方向不能反：正确是A o-- B，错误是B --o A - 中文或含空格类名必须加双引号：
"用户服务"，否则解析中断 - 字段/方法定义后必须换行或空行分隔，
+String name +void init()会被当作文本字面量，不识别为成员
保存后没自动刷新？——别漏掉这个开关
VSCode 默认关闭自动预览，需手动开启：
- 打开设置（
Cmd+,或Ctrl+,），搜索plantuml.previewOnSave - 勾选该选项，或在
settings.json中加一行："plantuml.previewOnSave": true
这个开关不起作用的常见原因是：你用的是旧版插件（v2.15.0 之前），或当前文件没被识别为 PlantUML 类型（右下角状态栏没显示 “PlantUML” 字样，此时需手动点击切换语言模式为 PlantUML）。
真正卡住人的从来不是语法本身，而是 plantuml.jar 路径里一个多余的空格、dot 路径指向了目录而非可执行文件、或者 JDK 版本刚好踩在 PlantUML 的兼容断层上。这些地方没报明确错误，只静默失败。
