1. 为什么在 VSCode 里折腾 PlantUML 环境PlantUML 的核心价值就一句话用文本代码画 UML 图不用拖拽对齐。你写startuml到enduml之间的描述它帮你渲染成时序图、类图、用例图、活动图。适合谁适合那些写文档时被 Visio 折磨过、又不想装 EA 这种重型建模工具的开发者。本地写.puml文件VSCode 里实时预览改一行代码图就跟着变导出 PNG/SVG 直接贴进技术方案。但环境搭建这件事坑比想象中多。Java 要装、Graphviz 要配、VSCode 插件要选对、settings.json里plantuml.jar路径和dot路径写错一个字符就渲染失败。更现实的问题是现在写 UML 也想让 AI 帮忙补全——比如你写了个类名想让模型把关联关系、方法签名补出来或者把一段自然语言需求转成 PlantUML 语法。这时候就需要一个统一的 API 通道来接入 AI 能力而不是每个插件单独配一套 Key。这篇就围绕「VSCode PlantUML TaoToken 统一 Key」这条链路把插件安装、Java/Graphviz 依赖、settings.json配置骨架、AI 补全接入、三步验证动作全部跑通。目标很明确你照着配完能预览、能补全、能导出。2. TaoToken 前置统一 Key 与 API 通道准备在讲配置之前先把 TaoToken 这条通道说清楚。TaoToken 提供的是统一的模型 API 接入层你拿到一个 Key就能在多个工具里复用同一个通道不用为每个插件单独申请。对于 PlantUML 场景它的作用是当你在 VSCode 里用 AI 辅助生成或补全.puml代码时请求走 TaoToken 的 API 端点模型返回 PlantUML 语法片段你直接贴进文件里渲染。你需要准备的东西一个 TaoToken 账号登录后进入控制台创建 API Key。地址是https://taotoken.net/api-keys创建后复制那串sk-开头的 Key后面配置里要用。确认你要用的模型名称。TaoToken 的模型对话入口在https://taotoken.net/chat你可以在那里先试一下模型对 PlantUML 语法的理解能力比如让它「用 PlantUML 写一个电商下单的时序图」看输出是否符合预期。如果你打算长期在 VSCode 里做编码辅助不只是 PlantUML可以了解下 Coding Plan地址https://taotoken.net/coding-plan它更适合高频调用的场景。注意API 端点统一用https://taotoken.net/api不要在代码里带 UTM 参数那是给官网链接用的。Key 不要硬编码在会提交到 Git 的文件里建议用环境变量或 VSCode 的settings.json配合本地.env。拿到 Key 之后先别急着配 VSCode。用 curl 测一下通道是否通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: 你选定的模型名, messages: [ {role: user, content: 用 PlantUML 写一个最简单的 Hello 时序图只要 startuml 到 enduml 之间的内容} ] }如果返回里有startuml开头的文本说明通道没问题。这一步别跳过后面 VSCode 里补全不工作时你能快速判断是插件问题还是 Key 问题。3. 可复制配置Java、Graphviz 与 settings.json 骨架3.1 Java 环境PATH 里必须有 javaPlantUML 的渲染引擎是 Java 写的所以本机必须有 JRE 或 JDK。装完之后关键一步把 Java 的bin目录加到系统 PATH 里不是只配JAVA_HOME就完事。很多人配了JAVA_HOME但命令行敲java -version没反应就是 PATH 漏了。Windows 下验证java -version能输出版本号就行。如果提示找不到命令去「系统属性 → 环境变量 → Path」里加一条C:\Program Files\Java\jdk-17\bin按你实际安装路径改。3.2 GraphvizGRAPHVIZ_DOT 指向 dot.exePlantUML 画类图、组件图时需要 Graphviz 的dot来做布局。下载 Graphviz 安装后找到bin目录下的dot.exe然后配一个系统变量变量名GRAPHVIZ_DOT变量值E:\PlantUml\graph\bin\dot.exe换成你的实际路径配完在命令行验证dot -V输出dot - graphviz version x.x.x就对了。这一步不做后面渲染复杂图时会报Dot executable does not exist或图布局错乱。3.3 VSCode 插件装对那一个在 VSCode 扩展市场搜PlantUML装那个下载量最高的作者 jebbs。它支持预览、导出、语法高亮。装完后打开任意.puml文件按AltD就能开预览窗口。3.4 settings.json 配置骨架这是本篇的核心可复制部分。在 VSCode 里按CtrlShiftP输入Open User Settings (JSON)把下面这段合并进去{ plantuml.server: https://www.plantuml.com/plantuml, plantuml.render: Local, plantuml.java: java, plantuml.jar: E:\\PlantUml\\plantuml.jar, plantuml.dot: E:\\PlantUml\\graph\\bin\\dot.exe, plantuml.commandArgs: [], plantuml.diagramsRoot: docs/diagrams, plantuml.exportFormat: png, plantuml.exportOutDir: docs/diagrams/out, plantuml.exportSubFolder: false, plantuml.previewAutoUpdate: true, plantuml.timingDiagram.optimize: true, editor.formatOnSave: true, [plantuml]: { editor.defaultFormatter: jebbs.plantuml } }几个关键字段解释字段作用注意plantuml.render渲染方式设Local用本地 JavaGraphviz不依赖外网plantuml.jarPlantUML 核心 jar 路径从官网下载plantuml.jar放本地plantuml.dotGraphviz dot 路径和系统变量GRAPHVIZ_DOT保持一致plantuml.previewAutoUpdate预览自动刷新改代码图跟着变建议开plantuml.exportFormat导出格式png/svg 按需提示plantuml.jar建议放在一个固定目录比如E:\PlantUml\plantuml.jar不要放在临时下载文件夹里否则清理时容易误删导致渲染失败。3.5 AI 补全接入参数VSCode 里做 AI 补全可以用支持自定义 API 的补全插件比如 Continue、CodeGPT 这类把请求指向 TaoToken。以 Continue 的配置为例在config.json里加一个模型{ models: [ { title: TaoToken, provider: openai, model: 你选定的模型名, apiBase: https://taotoken.net/api/v1, apiKey: sk-你的Key } ] }这样你在.puml文件里选中一段文字让 AI 补全成 PlantUML 语法请求就走 TaoToken 通道。模型对话入口https://taotoken.net/chat可以先用来调 prompt确认模型输出的 PlantUML 语法稳定后再写进插件配置。4. 三步验证预览渲染、AI 补全、导出图片配置写完不算完得验证。我习惯按这三步走每步都有明确的成功标志。4.1 第一步预览渲染新建test.puml写入startuml Alice - Bob: 下单请求 Bob - Alice: 返回订单号 enduml按AltD。如果右侧弹出预览窗口并显示时序图说明 Java、Graphviz、jar 路径全对。如果报错看 VSCode 右下角提示常见的是Cannot find java或Dot executable does not exist回到第 3 节检查路径。4.2 第二步AI 补全在.puml文件里写一段注释startuml 请补全一个用户登录的时序图包含前端、网关、认证服务三个参与者 enduml选中注释行调用 AI 补全快捷键看你用的插件。如果模型返回了完整的participant和消息交互并且贴进去后能正常渲染说明 TaoToken 通道和插件配置都通了。4.3 第三步导出图片按CtrlShiftP输入PlantUML: Export Current Diagram选择 png。导出成功后去docs/diagrams/out目录看文件是否存在。这一步验证的是exportOutDir和exportFormat配置是否生效。三步都过环境就算搭完了。整个过程最耗时的其实是 Java 和 Graphviz 的路径排查配置本身复制粘贴就行。5. 本篇常见错排查报错一Cannot find java或java is not recognized原因PATH 里没有 Java 的bin目录。解决命令行敲where java确认路径把该路径的上一级bin加进系统 PATH重启 VSCode。报错二Dot executable does not exist原因plantuml.dot路径写错或 Graphviz 没装。解决确认dot.exe真实存在路径用双反斜杠\\或正斜杠/。Windows 下E:\PlantUml\graph\bin\dot.exe在 JSON 里要写成E:\\PlantUml\\graph\\bin\\dot.exe。报错三预览窗口空白无报错原因plantuml.jar路径不对或 jar 文件损坏。解决重新下载plantuml.jar确认文件大小正常几 MB路径指向文件本身而不是目录。报错四AI 补全无响应原因API Key 无效、apiBase写错、或模型名不对。解决先用第 2 节的 curl 命令测通道确认 Key 和模型名再检查插件配置里apiBase是否为https://taotoken.net/api/v1注意结尾不要多斜杠。报错五导出的图片是空白或只有部分元素原因Graphviz 布局失败通常是dot版本太旧或路径指向了错误的可执行文件。解决命令行dot -V确认版本重新配GRAPHVIZ_DOT和plantuml.dot为同一个dot.exe。报错六中文乱码原因PlantUML 默认字体不含中文。解决在.puml文件开头加skinparam defaultFontName Microsoft YaHei或导出时指定字体。6. 后续怎么用把 Key 和配置沉淀下来环境搭好之后日常使用就是写.puml、AltD预览、AltShiftF格式化、需要时让 AI 补全。几个实用习惯把plantuml.jar和 Graphviz 装在一个固定目录比如E:\PlantUml\整个目录可以打包备份换机器时直接复制改一下settings.json里的盘符就行。API Key 不要写死在插件配置里用环境变量TAOTOKEN_API_KEY插件配置里引用变量这样配置文件可以同步到 Git 而不泄露 Key。如果你后面要在 CI 里自动渲染 PlantUML 图可以把plantuml.jar和dot一起打进构建镜像用命令行java -jar plantuml.jar -tpng docs/diagrams/*.puml批量导出。这时候 TaoToken 的 Key 只用在开发阶段的 AI 补全CI 里不需要。需要长期在 VSCode 里做编码辅助的可以看下 Coding Planhttps://taotoken.net/coding-plan把 PlantUML 补全和其他语言的 AI 辅助统一到一个通道里。接入文档在https://taotoken.net/doc里面有各语言的调用示例配插件时对照着看能少踩坑。