本地渲染是PlantUML自动化绘图的前提，因云端会拒析含敏感信息的架构图；需正确配置Java（≥11）和Graphviz的dot并确保其加入系统PATH，且VSCode须通过code命令启动以继承环境变量。
VSCode 配合 PlantUML 能实现自动化架构图绘制，但前提是本地渲染链路必须打通——否则你写的 @startuml 会卡在“预览空白”或“无法生成 SVG/PNG”，根本谈不上自动化。
为什么本地渲染失败是自动化前提的最大拦路虎
PlantUML 插件默认走云端服务（https://www.plantuml.com/plantuml），看似省事，但架构图一旦含敏感组件名、内部服务路径或私有协议（比如 http://auth-service.internal），就会被服务器拒绝渲染，返回 Error:400 Bad Request 或直接超时。自动化脚本调用时更没法人工点“重试”。
所以必须切到本地渲染模式，而这依赖两个可执行程序能否被 VSCode 正确识别：
-
java：PlantUML 的核心运行时，版本需 ≥ 11（推荐 Adoptium JDK 11/17） -
dot：Graphviz 的布局引擎，负责把文本关系转成节点+连线的物理排版；没它，时序图、组件图、部署图都会错位或缺失箭头
常见现象：plantuml.render 设为 Local 后预览无反应，终端报错 Cannot run program "dot": CreateProcess error=2 —— 这不是 PlantUML 插件问题，是 dot 没进系统 PATH。
Windows 下 dot 和 java 的 PATH 验证要点
别只看命令行能跑，VSCode 启动时读的是登录会话的环境变量，而 GUI 应用（如 VSCode）往往不继承你手动改过的 CMD 环境。最稳妥的验证方式是：
- 关闭所有 VSCode 实例
- 打开新终端（PowerShell 或 CMD），执行：
where java和where dot，确认路径存在且非空 - 再用该终端启动 VSCode：
code --new-window，避免继承旧环境
Graphviz 安装时务必勾选 Add Graphviz to the system PATH；若已安装但未勾选，手动把 C:Program FilesGraphvizin 加到系统环境变量 Path 末尾（注意不是 ...graphvizin，新版默认不含 graphviz 子目录）。
VSCode 中 plantuml.render 和 plantuml.jar 的真实作用
"plantuml.render": "Local" 只是开关，真正决定用哪个 JAR 的是 "plantuml.jar" 配置项：
- 不填：插件自动下载并缓存一个
plantuml.jar（位置在%USERPROFILE%.vscodeextensionsjebbs.plantuml-*/plantuml.jar），够用但不可控 - 填绝对路径：比如
"C:\tools\plantuml.jar"，适合团队统一版本或离线环境 - 填相对路径（如
./plantuml.jar）：VSCode 会从当前工作区根目录找，方便项目级隔离
注意：plantuml.jar 本身不带 Graphviz 功能，它只是调用 dot 的桥梁。哪怕你指定了最新版 JAR，只要 dot 不可用，组件图照样崩。
自动化导出架构图的关键配置项
想用脚本批量生成 PNG/SVG（比如 CI 流程里跑 plantuml *.puml），仅靠插件不够，得靠命令行工具。但 VSCode 插件的配置能直接影响脚本行为：
-
"plantuml.exportOutDir": "./docs/arch"：设置导出目录，确保和脚本输出路径一致 -
"plantuml.previewAutoUpdate": false：关掉自动刷新，避免脚本执行中途被插件干扰 -
"plantuml.server": ""：清空此项，强制走本地，防止插件悄悄 fallback 到云端
真正自动化时，建议直接用 CLI：java -jar plantuml.jar -tsvg -o ./docs/arch *.puml，而不是依赖插件的右键导出——后者无法批量、不可复现、不记录日志。
最容易被忽略的点：Graphviz 的 dot 默认使用 neato 布局算法画组件图，但大型微服务架构图需要 fdp 或 sfdp 才能避免节点重叠。这没法在 VSCode 设置里调，得在 .puml 文件开头加 !pragma layout fdp —— 不写这句，图看起来永远“挤在一起”。
