plantuml预览不生效需检查java和graphviz是否正确安装并加入path，文件须为.puml后缀且@startuml独占一行，渲染问题可设exportformat为svg并指定中文字体，预览依赖保存触发而非实时刷新。
安装 PlantUML 插件后预览不生效？检查 Java 和 Graphviz 是否真就绪
VSCode 的 PlantUML 插件本身不渲染图，它依赖本地 java 和 dot（Graphviz）命令行工具。常见错误是：插件装了、扩展启用状态显示正常，但右键 Preview Diagram 没反应，或提示 java not found / dot command not found。
实操建议：
- 在终端运行
java -version和dot -V，必须都能输出版本号；Windows 用户注意 PATH 要包含java.exe所在目录和dot.exe所在目录（如C:\Program Files\Graphviz2.44\bin） - VSCode 设置里搜
plantuml.java，确认plantuml.java配置项指向正确的java可执行路径（尤其多 JDK 环境下容易指错） - Graphviz 安装后默认不加到系统 PATH，手动添加比依赖安装器“自动配置”更可靠
用 @startuml 写完图，右侧预览空白？检查文件后缀和语法起始标记
VSCode 的 PlantUML 插件只对特定后缀的文件触发预览逻辑，且要求严格匹配语法起始符。不是所有 .puml 或 .uml 文件都能被识别，也不是所有含 @startuml 的文本块都会渲染。
实操建议：
- 文件必须保存为
.puml后缀（.uml不被默认识别，除非手动修改files.associations设置） -
@startuml必须独占一行，前面不能有空格或注释；结尾的@enduml同理。常见坑：// @startuml或@startuml都会导致预览失败 - 预览快捷键是
Ctrl+Alt+D（Windows/Linux）或Cmd+Alt+D（macOS），右键菜单里的Preview Diagram有时响应滞后，优先用快捷键
预览图模糊、字体乱码或中文显示成方块？调整 VSCode 渲染参数
PlantUML 默认用内嵌字体渲染 SVG，但中文字体缺失或缩放策略不当，会导致右侧预览图文字糊成一片、箭头断裂、甚至整个图不显示。这不是代码问题，而是渲染链路中的字体/分辨率配置偏差。
实操建议：
- 在 VSCode 设置中搜索
plantuml.exportFormat，改为svg（别用png，SVG 更清晰且支持缩放） - 在用户设置 JSON 中添加：
"plantuml.javaArgs": ["-Dfile.encoding=UTF-8"]
，避免中文路径或注释引发编码异常 - 如果仍乱码，在
@startuml后第一行加：skinparam defaultFontName "Microsoft YaHei"
（Windows）或skinparam defaultFontName "PingFang SC"
（macOS），指定系统已安装的中文字体
想边写边看架构图实时更新？别依赖“自动刷新”，用保存触发 + 小心缓存
VSCode 的 PlantUML 插件没有真正的“实时监听+热重绘”能力。所谓“实时”，其实是靠文件保存动作触发重新生成。很多人改了几行就等图变，结果没反应，其实是忘了 Ctrl+S。
实操建议：
- 关闭
plantuml.previewAutoUpdate（设为false），避免编辑中途误触发失败渲染干扰节奏；养成“改完 →Ctrl+S→ 看预览”的习惯 - 预览窗口偶尔会卡在旧图，此时不要关掉再开，直接在预览标签页按
F5刷新即可（它会重新调用本地 PlantUML.jar） - 如果图结构复杂（比如含大量
package或together块），首次渲染可能卡顿 2–3 秒，不是崩溃，别急着关插件
真正卡住的点往往不在写法，而在 Java 进程有没有权限读取当前工作区路径、Graphviz 的 dot 是否被杀毒软件拦截、或者 VSCode 工作区根目录名含空格/中文导致 PlantUML.jar 启动失败——这些细节比语法本身更常拦住你。
