1. 为什么要在本地跑 PlantUML离线内网画图的真实痛点PlantUML 是一套用纯文本描述 UML 图的工具你写几行类似Alice - Bob: Hello的代码它就能渲染出时序图、类图、用例图、部署图甚至架构图。它适合谁适合那些需要在离线环境、内网服务器、或者公司安全策略不允许把设计稿上传到外部渲染服务的开发者。你只要本地有 Java 和 Graphviz就能把.puml文件变成 PNG、SVG全程不碰外网。我试过在一个完全断网的内网机器上画架构图最开始图省事用了在线渲染结果图里带公司内部服务名差点出事。后来改成纯本地链路JDK 负责跑 PlantUML 的 jar 包Graphviz 负责把 PlantUML 生成的中间 dot 描述转成真正的图形布局。这两个组件缺一不可很多人只装了 jar 却忘了 Graphviz结果一渲染就报Dot executable does not exist卡半天。这篇内容聚焦 PlantUML 本地环境搭建的完整流程从零开始把 Java、Graphviz、PlantUML 三件套装好再给一条可复制的本地渲染命令验证环境最后说明怎么用 TaoToken 统一管理 Key 和 API 通道让相关工具调用不至于散落各处。整套流程在 Windows 10/11 上验证过Linux 和 macOS 的思路一致只是包管理命令不同。核心检索词先摆出来PlantUML 本地环境搭建本质就是让「文本 → 图形」这条链路完全跑在你自己的机器上。你不需要联网不需要账号不需要把源码交给任何第三方。下面按依赖顺序一步步来每一步都有验证命令装完一个验一个别攒着一起测否则出错很难定位。2. 前置依赖三件套JDK、Graphviz、plantuml.jar 的安装与验证2.1 安装 JDK 并配置 JAVA_HOMEPlantUML 是 Java 写的所以第一步是 JDK。推荐 JDK 17 或更高OpenJDK 和 Oracle JDK 都行。下载 Windows x64 的.msi安装包安装时选自定义路径比如D:\Java\jdk-17别默认塞 C 盘后面 jar 包和缓存也会占空间。装完后配环境变量。新建系统变量JAVA_HOME值为D:\Java\jdk-17然后编辑Path追加%JAVA_HOME%\bin。打开新的命令行窗口验证java -version能打印出类似openjdk version 17.0.x就说明 JDK 就位。这里有个坑如果你之前装过多个 JDKPath里旧版本排在前面java -version会显示旧版本。把%JAVA_HOME%\bin挪到最前面即可。2.2 安装 Graphviz 并让 dot 命令可用Graphviz 是布局引擎PlantUML 自己不做图形排版它把图转成 dot 语言后交给 Graphviz 的dot命令。去 Graphviz 官网下 Windows 64 位.msi默认路径一般是C:\Program Files\Graphviz。安装时有一个关键选项安装向导里会问是否把 Graphviz 加入系统Path一定要勾上。如果漏了手动编辑Path追加C:\Program Files\Graphviz\bin。验证dot -V正常输出dot - graphviz version 2.44.1之类。注意是大写-V小写-v在某些版本会进入交互模式看起来像卡住。2.3 下载 plantuml.jar 并固定存放去 PlantUML 官网下载最新版plantuml.jar比如plantuml-1.2024.7.jar。建议放到固定目录例如D:\PlantUML\plantuml.jar。这个 jar 是自包含的不需要额外依赖只要 JDK 在。三件套装完后建议把三个验证命令连着跑一遍java -version dot -V java -jar D:\PlantUML\plantuml.jar -version第三条会打印 PlantUML 版本和它检测到的 Graphviz 路径。如果这里显示Dot: not found说明 Graphviz 的bin没进Path回到 2.2 检查。注意环境变量改完必须开新的命令行窗口才生效旧窗口读的是旧Path这是最常见的「明明配了却找不到」的原因。3. 可复制的本地渲染配置命令行、VSCode 与统一 Key 管理3.1 一条命令完成本地渲染验证先建一个测试文件demo.pumlstartuml Alice - Bob: Hello Bob -- Alice: Hi enduml然后执行渲染命令输出 SVGjava -jar D:\PlantUML\plantuml.jar -tsvg demo.puml成功后同目录生成demo.svg。想输出 PNG 就把-tsvg换成-tpng。这条命令就是整个本地环境是否可用的判定标准能出图说明 JDK、Graphviz、jar 三者串通了。3.2 VSCode 集成配置片段命令行能跑之后日常画图更推荐 VSCode。装两个扩展PlantUML语法高亮和预览和Graphviz (dot) language。然后在 VSCode 的settings.json里写死本地路径避免插件联网渲染{ plantuml.jar: D:\\PlantUML\\plantuml.jar, plantuml.graphvizDot: C:\\Program Files\\Graphviz\\bin\\dot.exe, plantuml.render: Local, plantuml.exportFormat: svg }plantuml.render设为Local是关键它强制走本地 jar不走远程服务器。配好后打开.puml文件Alt D实时预览Ctrl Shift P输入PlantUML: Export Diagram导出图片。3.3 用 TaoToken 统一管理工具调用的 Key 与 API 通道本地渲染本身不需要任何 Key但实际项目里PlantUML 往往和 AI 辅助生成图代码、CI 流水线里的自动出图、以及各种脚本调用混在一起。这些工具调用如果各自维护一套 Key 和 Base URL很快就会乱。我的做法是用 TaoToken 做统一通道一个 Key 管所有调用Base URL 固定为https://taotoken.net/api模型 ID 按需切换。在需要配置的地方三件套写全Base URL、Key、Model ID。比如某个脚本读取环境变量export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_MODELclaude-sonnet-4-5如果你用 Claude Code 这类编码工具配置思路一样把 Base URL 指向https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你要用的模型。这样 PlantUML 图代码的生成、润色、批量转换都能走同一条通道不用在多个平台之间来回切 Key。需要长期跑编码或 Agent 任务的话Coding Plan 更适合Key 和额度集中管理省得每个工具单独配。4. 验证请求与成功结果从 puml 到 svg 的完整链路环境搭好后验证要分两层一层是纯本地渲染一层是工具调用通道。本地渲染验证用 3.1 的命令即可。成功时你会看到同目录出现demo.svg用浏览器打开能看到 Alice 和 Bob 两条箭头。如果图能出但中文变方块是字体问题在 puml 里加一行skinparam defaultFontName Microsoft YaHeiWindows 上用微软雅黑Linux 上可以换成WenQuanYi Zen Hei。工具调用通道的验证可以用一条 curl 请求确认 Key 和 Base URL 通不通curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的Key返回模型列表就说明通道正常。这一步和 PlantUML 本地渲染是两条独立的链路但都指向同一个目标让整个画图工作流可控、可复现。本地渲染保证图不出内网统一通道保证工具调用不散乱。实测下来最稳的组合是本地 jar 本地 Graphviz 负责出图TaoToken 负责所有需要模型能力的辅助环节。两者互不干扰任何一边出问题都能单独排查。5. 本篇常见报错排查401、local proxy failed、reading choices 与 OAuth排错时先分清是本地渲染链路的问题还是工具调用通道的问题。下面几个是高频报错。Dot executable does not existGraphviz 没装或bin没进Path。跑dot -V确认不行就重装并勾选加入 Path。401 Unauthorized工具调用通道的 Key 不对或没带。检查Authorization: Bearer sk-xxx头是否完整Key 是否复制时带了空格。TaoToken 的 Key 在控制台的 API Keys 页面生成生成后只显示一次丢了就重新建。local proxy failed通常是本地网络配置或代理设置干扰了请求。检查环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY有就临时清掉再试。本地渲染不需要任何代理纯离线也能跑。reading choices相关报错多出现在调用模型接口解析响应时说明返回结构和你代码里取字段的路径不一致。先打印完整响应体确认choices字段是否存在再调整解析逻辑。OAuth报错如果你用的是需要 OAuth 的工具检查 token 是否过期。TaoToken 的 Key 是长期有效的但某些客户端会缓存旧 token清缓存重新登录即可。排查顺序建议先确认java -version、dot -V、java -jar plantuml.jar -version三条命令都正常再看工具调用的 Base URL 和 Key。本地链路和通道链路分开测别混在一起猜。6. 把本地渲染接进日常CI 出图与统一通道的配合环境搭好只是起点真正省事的是把它接进日常流程。比如在 CI 里加一步把仓库里所有.puml批量渲染成 SVGfind . -name *.puml -exec java -jar /opt/plantuml/plantuml.jar -tsvg {} \;CI 机器上同样要装 JDK 和 Graphviz思路和本地一致。如果 CI 里还要调用模型生成图代码就把 TaoToken 的 Base URL 和 Key 配成 CI 的 secret统一走https://taotoken.net/api模型 ID 按任务选。这样本地和 CI 用的是同一套通道行为一致排查也方便。需要看模型能力或调试接口时可以直接在模型对话里试要生成 Key 就去 API Keys 页面接入细节看接入文档。长期跑编码和 Agent 任务Coding Plan 的额度管理更省心。整套下来PlantUML 本地环境搭建不再是装完就忘的一次性操作而是能持续复用的出图管线。