【VS Code】Windows10下VS Code配置PlantUML使用环境：TaoToken统一Key接入与settings.json骨架

1. Windows10 下 PlantUML 环境为什么总在预览这一步卡住如果你在 Windows10 的 VS Code 里搜 PlantUML大概率会看到两种结果一种是插件装完AltD 一按右下角转圈半天然后弹一句Cannot find Graphviz另一种是图能出来但中文乱码、时序图箭头错位或者干脆提示java不是内部或外部命令。这两个问题其实都不在插件本身而在本地运行时链路没打通。PlantUML 的本质是一个 Java 类库它把文本描述翻译成图形指令再交给 Graphviz 的 dot 引擎做布局。VS Code 插件只是帮你调用这条链路。所以真正要配的是三件事Java 运行时、Graphviz 可执行文件、以及插件指向这两个东西的路径。Windows10 上最容易出问题的就是路径里带空格、环境变量没刷新、以及 Graphviz 装完没勾选“加入 PATH”。这篇按“从零到一次跑通时序图和类图预览”来写同时给出一份可以直接复制的settings.json骨架。另外我会把 AI 辅助生成 UML 的那条通道也接进来——用 TaoToken 的统一 Key 走 API让模型帮你把需求描述转成 PlantUML 源码再回到 VS Code 里预览。这样你既保留了本地渲染的确定性又省去了手写语法的重复劳动。适合谁看在 Windows10 上用 VS Code 写设计文档、准备软考/设计模式笔记、或者需要把 UML 图嵌进 Markdown 的人。不需要你之前配过 Java 项目但需要你能接受“装两个运行时 改一个 JSON 文件”这种程度的操作。2. 前置准备Java、Graphviz 与 TaoToken 统一 Key2.1 安装 Java 运行时PlantUML 需要 Java 8 以上。推荐装 Temurin 或 Oracle 的 JDK 17 LTS安装时一路默认即可。装完打开一个新的 PowerShell 窗口执行java -version正常会输出类似openjdk version 17.0.x。如果提示找不到命令说明安装时没勾选“Set JAVA_HOME”或者 PATH 没生效重开终端或手动把bin目录加进系统变量。2.2 安装 Graphviz去 Graphviz 官网下载 Windows 安装包安装向导里有一个关键选项Add Graphviz to the system PATH for all users务必勾上。装完同样新开终端验证dot -V输出dot - graphviz version 9.x就对了。这一步没做的话类图、组件图、状态图都会渲染失败只有时序图和活动图能勉强出来。2.3 在 VS Code 安装 PlantUML 插件扩展商店搜索PlantUML安装 jebbs 维护的那个图标是蓝色背景的 UML 图。这个插件同时支持本地渲染和远程渲染我们走本地。装完后它会在设置里暴露plantuml.java、plantuml.dot、plantuml.render等字段。2.4 TaoToken 统一 Key 的定位TaoToken 在这里的角色是“AI 辅助生成 UML 源码”的通道。你不需要在本地跑模型也不需要给每个编辑器单独配一套密钥。注册后在控制台创建一个 API Key后续无论是 VS Code 插件、还是你自己写的脚本都用同一个 Key 去请求模型对话接口让模型把“帮我画一个策略模式的类图”转成 PlantUML 代码块。需要提前拿到的两个地址官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/apiKey 的创建在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite如果你只是想先验证模型能不能按 PlantUML 语法输出可以直接用模型对话页试一句https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期在 VS Code 里做编码和 Agent 类任务的话Coding Plan 会更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite3. 可复制配置settings.json 骨架与插件参数3.1 打开 settings.json在 VS Code 里按CtrlShiftP输入Open User Settings (JSON)回车。你会看到用户级settings.json。下面这份骨架可以直接合并进去注意把路径换成你自己的实际安装位置。{ plantuml.java: C:\\Program Files\\Eclipse Adoptium\\jdk-17.0.9.9-hotspot\\bin\\java.exe, plantuml.dot: C:\\Program Files\\Graphviz\\bin\\dot.exe, plantuml.render: Local, plantuml.diagramsRoot: docs/uml, plantuml.exportOutDir: docs/uml/out, plantuml.exportFormat: png, plantuml.exportSubFolder: false, plantuml.previewAutoUpdate: true, plantuml.server: https://www.plantuml.com/plantuml, plantuml.commandArgs: [-charset, UTF-8], files.associations: { *.plantuml: plantuml, *.puml: plantuml } }几个字段说明一下。plantuml.java和plantuml.dot必须写绝对路径Windows 下反斜杠要转义成双反斜杠。plantuml.render设为Local表示用本地 Java 渲染不走远程服务器。plantuml.commandArgs里加-charset UTF-8是解决中文乱码的关键很多人预览出来中文变方块就是漏了这一条。3.2 用表格对照关键参数参数作用建议值plantuml.java指定 java.exe 路径JDK 安装目录下 bin\java.exeplantuml.dot指定 dot.exe 路径Graphviz 安装目录下 bin\dot.exeplantuml.render渲染方式Localplantuml.exportFormat导出格式png 或 svgplantuml.commandArgs传给 PlantUML 的参数-charset UTF-8plantuml.previewAutoUpdate编辑时自动刷新预览true注意路径里如果包含空格比如Program FilesJSON 字符串里不需要额外加引号但反斜杠必须双写。写错的话插件会静默失败预览窗口只显示空白。3.3 把 AI 生成通道接进来PlantUML 插件本身不直接调大模型但你可以用 VS Code 的 REST Client 插件或者一个简单的 PowerShell 脚本把需求发给 TaoToken 的对话接口拿回 PlantUML 代码再贴进.puml文件。请求体走标准的 chat completions 格式基址用https://taotoken.net/api认证头带上你创建的 Key。$headers { Authorization Bearer 你的TaoTokenKey Content-Type application/json } $body { model claude-sonnet-4-5 messages ( { role user; content 用 PlantUML 语法画一个策略模式类图只输出 startuml 到 enduml 之间的代码 } ) } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri https://taotoken.net/api/v1/chat/completions -Method Post -Headers $headers -Body $body返回内容里就是一段可直接粘贴的 PlantUML 源码。这样你写文档时先让模型出草稿再在 VS Code 里 AltD 预览微调比纯手写快很多。4. 验证请求从时序图到类图一次跑通4.1 第一个时序图在项目里新建docs/uml/sequence.plantuml输入startuml Alice - Bob: 发起登录请求 Bob - Server: 校验凭证 Server -- Bob: 返回 token Bob -- Alice: 登录成功 enduml按AltD右侧应该出现预览窗口显示四条带箭头的消息线。如果预览窗口提示Cannot find java回到第 3 节检查plantuml.java路径。如果图出来了但中文是乱码检查plantuml.commandArgs是否包含-charset UTF-8。4.2 类图验证 Graphviz 链路再建一个docs/uml/strategy.plantumlstartuml abstract class Strategy { AlgorithmInterface() } class ConcreteStrategyA { AlgorithmInterface() } class Context { -Strategy strategy ContextInterface() } Strategy |-- ConcreteStrategyA Context o-- Strategy enduml这个图用到了继承和聚合关系必须依赖 Graphviz 的 dot 引擎。如果预览报Cannot find Graphviz说明plantuml.dot路径不对或者 Graphviz 没装。确认dot -V在终端能跑通后把dot.exe的完整路径填进设置。4.3 导出图片预览窗口右上角有导出按钮也可以按CtrlShiftP输入PlantUML: Export Current Diagram。导出格式由plantuml.exportFormat决定输出目录是plantuml.exportOutDir。导出成功后在文件管理器里能看到对应的 png 或 svg。4.4 用 AI 生成一段再验证把第 3.3 节的 PowerShell 脚本跑一遍把返回的 PlantUML 代码贴进新文件再 AltD。这一步能同时验证两件事TaoToken 的 Key 是否有效、以及模型输出的语法是否能被本地渲染器接受。如果模型返回的代码里有 Markdown 代码块标记手动去掉plantuml和再预览。5. 本篇常见错排查5.1 预览空白或一直转圈最常见的原因是plantuml.java指向了javaw.exe而不是java.exe。javaw不输出控制台信息插件拿不到渲染结果。改成java.exe即可。另一个原因是 JDK 装在了带中文或空格的路径下尽量用默认的C:\Program Files\Eclipse Adoptium\这类路径。5.2 Cannot find Graphviz先确认dot -V在新开的终端里能跑。如果终端能跑但 VS Code 报错说明 VS Code 启动时继承的 PATH 是旧的重启 VS Code 或者注销重登一次。还不行就直接在settings.json里写死plantuml.dot的绝对路径绕过 PATH 查找。5.3 中文乱码三个地方要同时满足文件本身保存为 UTF-8、plantuml.commandArgs带-charset UTF-8、以及 Java 运行时没有用奇怪的默认编码。前两个做到基本就不会乱码了。如果导出 png 时乱码但预览正常检查plantuml.exportFormat换成 svg 试试svg 对字体嵌入更友好。5.4 AltD 没反应检查文件扩展名是不是.plantuml或.puml并且files.associations里做了映射。如果文件是.txt插件不会激活预览快捷键。另外确认没有和其他插件的快捷键冲突可以在键盘快捷方式里搜plantuml看绑定。5.5 TaoToken 请求返回 401说明 Key 没带上或者带错了。检查Authorization头是不是Bearer加 Key中间有一个空格。Key 在控制台创建后只显示一次如果忘了就重新建一个。请求地址用https://taotoken.net/api/v1/chat/completions不要漏掉/v1。5.6 模型返回的代码渲染失败模型有时会输出startuml和enduml之外的说明文字或者用了插件不支持的语法扩展。把纯代码段截出来先在最简的时序图上试确认渲染链路没问题后再逐步加复杂度。如果某个语法本地报错可以让模型换一种等价写法。6. 后续怎么用这套环境本地渲染链路跑通之后你的工作流可以变成先用 TaoToken 的模型对话把需求转成 PlantUML 草稿贴进 VS Code 预览手动调整布局和文案最后导出 png 或 svg 嵌进文档。整个过程不依赖在线 PlantUML 服务器图的内容也不会离开本地。如果你后面要批量生成 UML比如一次画十几个类图可以写个脚本循环调用 API把返回结果按文件名写入docs/uml/目录再用命令行的java -jar plantuml.jar批量导出。命令行用法在插件文档里有核心就是java -jar plantuml.jar -charset UTF-8 docs/uml/*.plantuml。需要长期在 VS Code 里做这类编码和文档任务的话Coding Plan 的额度比单次调用更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteKey 管理和新建入口https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite先把第 4 节的两个图跑通再回头调 AI 生成那段。顺序反了的话出问题你分不清是渲染链路还是请求链路。