企业官网建设流程全解析

1. VSCode 里画类图，为什么最后都绕回 PlantUML

如果你平时用 VSCode 写 Java、C# 或者 TypeScript，迟早会遇到一个需求：把代码里的类关系画成 UML 类图。用拖拽工具画一次还行，但类一多、字段一改，图就对不上了，维护成本高得离谱。PlantUML 的思路正好反过来——你用文本描述类、字段、方法、继承和组合关系，它负责渲染成图。改代码的同时改几行描述，图就跟着更新，特别适合放进 Git 里做版本管理。

这篇聚焦的是「配置落地」：在 VSCode 里装好 PlantUML 插件之后，怎么把settings.json写对，让 Java、Graphviz、渲染引擎三者配合起来，一次预览成功。很多人卡住不是因为语法不会，而是环境没配好，报错Dot executable does not exist或者预览一直转圈。我会给出一份可直接复制的settings.json骨架，顺带说明怎么用统一的 Key/API 通道接入模型能力，帮你把「画图」和「让 AI 帮你生成类图描述」串起来。适合需要画 UML 类图的开发者，尤其是本地已经装了 JDK 但 Graphviz 没配好的同学。

2. 前置准备：JDK、Graphviz 和 TaoToken 通道

PlantUML 插件本身只是个壳，真正干活的是plantuml.jar，它依赖 Java 运行环境。而类图、组件图这类非时序图，还需要 Graphviz 提供的dot引擎来布局。所以三样东西缺一不可：JDK、Graphviz、VSCode 的 PlantUML 插件。

JDK 建议 11 以上，装完在终端执行java -version能看到版本号即可。Graphviz 在 Windows 上装完记得把bin目录加进 PATH，macOS 用brew install graphviz，Ubuntu 用sudo apt install graphviz。装完执行dot -V，能打印版本就说明引擎就绪。

至于 TaoToken，它的作用是在你写类图描述时，可以调用模型帮你把一段代码或需求转成 PlantUML 语法。它提供统一的 Key 和 API 通道，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。你可以在控制台生成 Key，后面在插件或脚本里复用同一个通道，不用为每个工具单独配一套凭证。这一步不是渲染类图的必需项，但如果你想让 AI 辅助生成类图源码，提前把通道准备好会省事很多。

3. settings.json 可复制骨架：Java 路径与 Graphviz 指向

VSCode 的 PlantUML 插件配置项都写在用户或工作区的settings.json里。按Ctrl+Shift+P打开命令面板，输入Preferences: Open User Settings (JSON)，把下面这份骨架贴进去，按你本机实际路径改三处即可。

{ "plantuml.java": "C:\\Program Files\\Java\\jdk-17\\bin\\java.exe", "plantuml.jar": "", "plantuml.dot": "C:\\Program Files\\Graphviz\\bin\\dot.exe", "plantuml.render": "Local", "plantuml.diagramsRoot": "docs/diagrams", "plantuml.exportOutDir": "docs/diagrams/out", "plantuml.exportFormat": "png", "plantuml.exportSubFolder": false, "plantuml.server": "https://taotoken.net/api", "plantuml.commandArgs": ["-Djava.awt.headless=true"] }

几个关键点解释一下。plantuml.java指向你本机的java可执行文件，Windows 路径里的反斜杠要写成双反斜杠。plantuml.jar留空时插件会用内置版本，如果你有特定版本的plantuml.jar，填绝对路径。plantuml.dot是 Graphviz 的dot路径，这一项配错就会报Dot executable is /opt/local/bin/dot Error: File does not exist这类错误。plantuml.render设为Local表示本地渲染，不依赖远程服务。

plantuml.server这一项填的是 TaoToken 的 API 地址，用于需要走统一通道的场景。如果你只是本地画图，可以暂时忽略它；但当你希望用模型辅助生成或校验类图描述时，这个通道就能复用同一套 Key。生成 Key 的入口在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。把 Key 配到你的脚本或插件里，就能通过 https://taotoken.net/api 统一调用。

macOS 或 Linux 用户把路径换成/usr/local/bin/java、/usr/bin/dot这类即可。改完保存，VSCode 会提示重载窗口，点一下让配置生效。

4. 从 .puml 源码到类图预览的完整验证

配置写完，来跑一次完整验证。新建一个文件order.puml，内容如下：

@startuml class Order { +String orderId +Date createTime +void submit() +void cancel() } class OrderItem { +String sku +int quantity } class User { +String userId +String name } Order "1" *-- "n" OrderItem : contains User "1" -- "n" Order : places @enduml

注意类与类之间不要有多余的分号，否则会生成错误。保存后按Alt+D，插件会调用本地 Java 和 Graphviz 渲染。如果一切正常，右侧会弹出预览窗口，显示三个类以及它们之间的组合和关联关系。组合用实心菱形*--，关联用--，方向从Order指向OrderItem。

想导出图片，按Ctrl+Shift+P打开命令面板，输入Export Current Diagram，选择png或svg。导出目录由plantuml.exportOutDir控制，默认会放在你配置的docs/diagrams/out下。实测下来，本地渲染一次通过的关键就是plantuml.dot路径正确，以及dot -V在终端能跑通。

如果你想让模型帮你把一段 Java 代码转成上面的 PlantUML 描述，可以走 TaoToken 的模型对话通道：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。把代码贴进去，让它输出@startuml到@enduml的完整片段，再粘回.puml文件里预览，省去手写类成员的功夫。

5. 本篇常见错排查

第一个高频错误是Dot executable is ... Error: File does not exist。这基本就是plantuml.dot没配或者路径写错。先在终端执行dot -V，如果命令找不到，说明 Graphviz 没装好或没进 PATH；如果终端能跑但插件报错，就是settings.json里的路径和实际不一致，注意 Windows 的双反斜杠和大小写。

第二个是预览一直转圈或提示 Java 相关错误。检查plantuml.java是否指向真实的java可执行文件，而不是javac。执行java -version确认能输出版本。如果装了多个 JDK，填绝对路径最稳。

第三个是类图渲染出来但布局很乱、连线交叉严重。这通常是 Graphviz 版本过旧，升级到较新版本会改善。另外类名和关系描述尽量简洁，避免一个类挂太多关系。

第四个是导出图片失败。确认plantuml.exportOutDir目录存在，插件不会自动创建多级目录。可以先手动建好docs/diagrams/out，再执行导出命令。

如果你在接入模型辅助生成类图时遇到鉴权问题，检查 Key 是否从控制台正确复制，以及请求地址是否用了 https://taotoken.net/api 。需要长期在编码流程里调用模型生成或校验类图描述，可以考虑 Coding Plan 通道：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，把类图生成纳入日常开发工作流。

6. 把类图生成接进你的日常流程

配置一次之后，后面画类图基本就是「写描述、按 Alt+D、导出」三步。我的习惯是把.puml文件和对应的源码放在同一个模块目录下，改完类结构顺手更新描述，提交时一起进 Git。这样类图永远不会和代码脱节。

如果你想让 AI 帮你从现有代码批量生成类图描述，走 TaoToken 的模型对话或 Coding Plan 通道都行，Key 和 API 地址复用同一套，不用重复配置。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有请求格式和参数说明。Claude Code 相关的接入方式可以参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite ，适合把类图生成嵌进命令行工作流。

最后提醒一句：settings.json改完一定要重载窗口，路径类配置不重载不生效。Graphviz 的dot路径是本地渲染类图的命门，配好它，后面就顺了。