1. 为什么在 VSCode 里画时序图最后都绕不开 PlantUML如果你写过接口文档、排查过线上调用链、或者给同事解释过「这个请求到底经过了哪些服务」大概率都遇到过同一个尴尬用鼠标拖拽画出来的时序图改一个字段就要重新对齐半天版本一多根本维护不动。PlantUML 解决的正是这个问题——它是一门用纯文本描述 UML 图的脚本语言你写的是代码它渲染出来的是图。时序图Sequence Diagram是它最常用的场景之一参与者、消息箭头、激活条、返回虚线全都能用几行文本表达清楚。在 VSCode 里用 PlantUML 画时序图好处是编辑、预览、导出都在一个窗口完成改一行代码右边立刻刷新比在线编辑器顺手得多。但真正落地时会卡在几个地方本地渲染依赖 Java 和 GraphViz环境变量配错就报Cannot find Graphviz插件默认走公共渲染服务内网或者批量出图时不稳定多人协作时每个人的settings.json各写各的换台机器又要重配一遍。这篇就按「装插件 → 写语法 → 配 settings.json → 接统一 Key → 渲染验证 → 排错」的完整链路走一遍。适合刚接触 PlantUML 的后端、测试、架构同学也适合已经在用但想把配置沉淀成团队骨架的人。下面所有配置都可以直接复制改掉路径和 Key 就能跑。2. TaoToken 统一 Key 在绘图工作流里扮演什么角色先说清楚一件事PlantUML 本地渲染时序图本身不需要任何大模型或 API靠的是本地 Java GraphViz。那为什么这篇要提 TaoToken因为实际工作流里画图只是中间一环前后往往还挂着「让模型帮我根据接口定义生成 PlantUML 源码」「把这段时序图翻译成文字说明」「批量给几十个接口补时序图」这类动作。这些动作需要一个稳定的模型调用通道而 TaoToken 提供的就是一个统一 Key 的接入方式一个 Key 走通多家模型不用在每台机器、每个插件里分别填不同厂商的地址和密钥。它的定位是 API 聚合与统一入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你可以在控制台创建 Key然后在 VSCode 里配合支持自定义 Base URL 的 AI 插件使用让「生成 PlantUML 代码」这一步走统一通道。需要强调的是TaoToken 不替代 VSCode也不替代 PlantUML 插件它只是把模型调用这一层收敛成一个 Key方便你在 settings.json 里集中管理。对绘图场景来说这个统一 Key 的价值在于团队里每个人不用各自去申请不同平台的额度配置骨架里只留一个占位符换人换机器时改一处即可。下面第 3 节先给可复制的 settings.json 骨架第 4 节再讲 Key 怎么接进去。3. 可复制的 settings.json 配置骨架3.1 先装齐三样东西在动 settings.json 之前本地环境要到位否则后面预览一定是红的。第一Java 运行时。PlantUML 是 Java 写的没装 JDK 或 JRE 直接报错。装完后在终端执行java -version能打印版本号即可。第二GraphViz。时序图里参与者的布局、箭头走向靠它算。装完把bin目录加进系统 PATH终端执行dot -v能看到版本信息就算成功。Windows 上常见路径是C:\Program Files\Graphviz\binmacOS 用brew install graphviz更省事。第三VSCode 插件。在扩展市场搜PlantUML作者是 jebbs 的那个装上。它负责语法高亮、预览、导出。装完重启 VSCode。3.2 settings.json 骨架打开 VSCode 的命令面板输入Preferences: Open User Settings (JSON)把下面这段合并进去。注意路径要换成你自己机器上的实际路径Windows 的反斜杠在 JSON 里要写成双反斜杠。{ plantuml.render: Local, plantuml.java: C:\\Program Files\\Java\\jdk-17\\bin\\java.exe, plantuml.dotPath: C:\\Program Files\\Graphviz\\bin\\dot.exe, plantuml.diagramsRoot: docs/diagrams, plantuml.exportOutDir: docs/diagrams/out, plantuml.exportFormat: png, plantuml.exportSubFolder: false, plantuml.previewAutoUpdate: true, plantuml.server: https://taotoken.net/api, plantuml.commandArgs: [], files.associations: { *.puml: plantuml, *.plantuml: plantuml } }逐项说明一下关键字段。plantuml.render设为Local表示用本地 Java 渲染不依赖外部服务内网也能用。plantuml.java和plantuml.dotPath是最容易配错的两项路径里带空格没关系但反斜杠必须转义。plantuml.diagramsRoot和plantuml.exportOutDir把源码和导出图分开放避免.puml和.png混在一个目录里。plantuml.previewAutoUpdate打开后你改代码右边预览会自动刷新体验接近 Markdown 预览。plantuml.server这一项如果你只用本地渲染其实用不到但当你需要走统一通道做「模型生成 PlantUML 源码」时可以把相关 AI 插件的 Base URL 指向 TaoToken 的 API 地址保持整个工作流的出口一致。这里先留作占位第 4 节展开。3.3 工作区级别的配置团队协作时建议把和路径无关的配置放到工作区的.vscode/settings.json个人机器相关的路径留在用户级 settings.json。这样别人拉下代码后只需要补自己的 Java 和 GraphViz 路径其余规则直接继承。{ plantuml.diagramsRoot: docs/diagrams, plantuml.exportOutDir: docs/diagrams/out, plantuml.exportFormat: svg, plantuml.previewAutoUpdate: true }导出格式这里换成svg因为时序图里文字多SVG 放大不糊放进文档或网页都清晰。如果是要贴进 PPT再单独导 PNG 也行。4. 接入统一 Key 与验证请求4.1 拿 Key 和填配置先去控制台创建 API Key入口在 https://taotoken.net/console 。创建后复制那串 Key注意它只完整显示一次。然后在 VSCode 里如果你用的是支持 OpenAI 兼容接口的 AI 插件比如用于生成代码片段的助手把它的 Base URL 填成https://taotoken.net/apiAPI Key 填你刚复制的那串。这样「让模型根据接口描述生成 PlantUML 时序图源码」这一步就走统一通道了。需要提醒的是不要把 Key 硬编码进提交到 Git 的 settings.json。推荐用环境变量或者放在不纳入版本管理的本地配置文件里。团队共享的骨架里只留占位符比如apiKey: ${env:TAOTOKEN_API_KEY}每个人在自己系统里设环境变量。4.2 一段可渲染的时序图源码配置就绪后建一个docs/diagrams/login.puml把下面这段贴进去。这是一个登录流程的时序图覆盖了参与者声明、同步消息、返回消息、激活条和注释。startuml title 用户登录时序图 actor 用户 as User participant 前端 as Web participant 网关 as Gateway participant 认证服务 as Auth database 用户库 as DB User - Web : 输入账号密码 activate Web Web - Gateway : POST /login activate Gateway Gateway - Auth : 校验凭证 activate Auth Auth - DB : 查询用户 activate DB DB -- Auth : 返回用户记录 deactivate DB Auth -- Gateway : 签发 Token deactivate Auth Gateway -- Web : 200 Token deactivate Gateway Web -- User : 跳转首页 deactivate Web note right of Auth : Token 有效期 2 小时 enduml按Alt D触发预览右侧应该出现一张带激活条的时序图。如果预览窗口空白或者报错先看第 5 节。4.3 导出与批量渲染单张图预览没问题后导出用命令面板的PlantUML: Export Current Diagram会按plantuml.exportOutDir和plantuml.exportFormat输出。如果目录里有一批.puml可以用PlantUML: Export Workspace Diagrams一次性全导。导出前确认plantuml.exportSubFolder的设置设为false时所有图平铺在输出目录设为true会按源码目录结构建子文件夹图多的时候建议开true。5. 本篇常见错排查5.1 Cannot find Graphviz这是最高频的报错九成是plantuml.dotPath指错了或者 GraphViz 没装。先在终端执行dot -v如果命令找不到说明 PATH 没配好回去把 GraphViz 的bin目录加进系统环境变量。如果终端能跑但 VSCode 报错检查 settings.json 里的路径是不是写成了单反斜杠JSON 里必须双写。macOS 用户注意路径通常是/opt/homebrew/bin/dot或/usr/local/bin/dot别照抄 Windows 路径。5.2 预览一直转圈或超时如果plantuml.render被设成了PlantUMLServer之类的远程模式而网络又不通就会一直转。改回Local即可。另外 Java 版本太老也可能导致渲染卡住建议 JDK 11 以上。还有一种情况是图太大本地渲染耗时超过预览超时可以先把图拆小验证语法再合并。5.3 中文乱码或方框时序图里出现中文变方框通常是字体问题。在.puml文件顶部加一行skinparam defaultFontName Microsoft YaHeiWindows或skinparam defaultFontName PingFang SCmacOS指定一个系统里存在的中文字体。如果导出 SVG 后中文正常、PNG 异常多半是导出时的字体渲染差异优先用 SVG。5.4 修改 settings.json 后不生效VSCode 的配置有用户级和工作区级两层工作区级会覆盖用户级。如果你改了用户级没反应检查项目里.vscode/settings.json是不是有同名项把它盖掉了。改完配置建议重启一次 VSCode 窗口命令面板执行Developer: Reload Window即可比完全退出重开快。5.5 统一 Key 调用返回 401如果生成 PlantUML 源码的 AI 插件报 401先确认 Key 有没有复制完整前后有没有多余空格。再确认 Base URL 是不是https://taotoken.net/api注意结尾不要多加/v1之类的路径具体以接入文档为准。文档入口在 https://taotoken.net/doc 。如果确认 Key 和地址都对去控制台看下额度是否用完。6. 把配置沉淀成团队骨架走到这里你应该已经能在 VSCode 里顺畅地写 PlantUML 时序图、本地预览、导出 SVG 了。最后给一个实用建议把第 3 节的 settings.json 骨架和第 4 节的.puml示例一起放进项目的docs/diagrams目录配一个简短的 README 说明「装 Java、装 GraphViz、改两个路径、按 AltD」。新同事入职时照着做十分钟就能出第一张图比口头讲一遍快得多。如果你还想把「模型生成时序图源码」这一步也固化下来可以在团队里统一用 TaoToken 的 Key把 AI 插件的 Base URL 指向 https://taotoken.net/api Key 通过环境变量注入。这样换人换机器时配置骨架不用动只改本地环境变量。需要长期跑编码或 Agent 类任务的可以看下 Coding Plan 的入口 https://taotoken.net/coding-plan 只是偶尔生成几段 PlantUML 的用模型对话页 https://taotoken.net/models 手动问也够用。Key 的管理都在控制台 https://taotoken.net/console 接入细节以文档 https://taotoken.net/doc 为准。真正省时间的不是画图本身而是把「环境配置 源码模板 统一出口」这三件事一次性定好之后每张时序图都只是填空。