根本原因是plantuml.jar路径未配置或Java环境未识别；需安装JDK 8–17、下载plantuml.jar并配置绝对路径，类图语法须严格遵循缩进、大小写及引号规则。
PlantUML插件装了但预览不显示
根本原因通常是plantuml.jar路径没配对，或者Java环境没识别到。VSCode的PlantUML插件默认不自带Java运行时，它只是个“前端”，真正画图靠的是本地Java + plantuml.jar。
实操建议：
- 确认已安装JDK 8–17（别用JDK 21+，PlantUML 1.2024.x 对新版本兼容不稳定）
- 下载最新
plantuml.jar（从 plantuml.com/download），放固定路径，比如/opt/plantuml/plantuml.jar - 在VSCode设置里搜
plantuml.jar，填入完整绝对路径（Windows注意用正斜杠或双反斜杠：C:/plantuml/plantuml.jar） - 重启VSCode，打开一个
.puml文件，按Ctrl+Shift+P→ 输入PlantUML: Preview Current Diagram试试
类图语法写出来但关系线乱或不渲染
PlantUML类图不是“写完就成图”，它的缩进、空格、关键字大小写和换行都有隐含语义。最常见的是把class写成Class，或用中文类名没加引号，导致解析失败。
实操建议：
- 类名含空格或中文，必须用双引号包裹：
class "用户登录服务" - 继承用
，实现用<code>，聚合用<code>o--，组合用*--——符号方向不能反，比如-|>是错的 - 避免在类定义中间空行，PlantUML会当成段落分隔，导致后续关系失效
- 字段/方法用
+-#开头，后面紧跟空格，再写内容；没空格会当作文本字面量处理
示例（能跑通的最小类图）：
class "UserService" {
+String username
-void login()
}
class "AuthController" {
#boolean isAuthenticated
}
UserService <|-- AuthController想用代码自动生成类图但不敢动源码
直接解析Java/Python源码生成UML，本质是静态分析，不是魔法。主流方案如py2puml或javapuml只能处理简单结构，一旦有泛型嵌套、Lombok、动态代理，图就断掉或漏成员。
实操建议：
- Python项目优先试
py2puml：pip install py2puml，然后py2puml mypackage/ -o class.puml，但它不支持type alias和dataclass字段注解推导 - Java项目慎用
javapuml，更推荐用IDEA内置的Diagrams（右键类 → Diagrams → Show Diagram），导出为PNG后人工补PlantUML语法 - 别指望“一键全量生成整个项目类图”——模块间依赖太深时，生成的
.puml常超500行，VSCode预览卡死，建议按子模块拆成多个小图
序列图里生命线不自动激活或销毁错位
PlantUML默认不会自动管理激活条（activation bar），你得手动用activate/deactivate控制。不写的话，所有对象都显示为静止状态，箭头连上去也没高亮效果。
实操建议：
- 每个同步调用前加
activate，返回后立刻deactivate，否则后续消息会叠在错误的生命线上 - 异步消息用
->，同步用-->，返回用或<code>，类型错配会导致激活条断裂 - 如果某对象参与多轮交互，中间又退出，记得用
destroy显式销毁，否则它会一直横在底部
片段示意：
participant A participant B A -> B: doWork() activate B B --> A: done deactivate B
PlantUML不是绘图工具，是文本到图形的编译器——空格、换行、标点稍有偏差，输出就可能空白或报错Cannot find the end of the diagram。调试时先删一半内容，看是否还能预览，比对着文档逐行查更快。
