企业官网建设流程全解析

1. Windows10 下 PlantUML 环境为什么总在预览这一步卡住

如果你在 Windows10 的 VS Code 里搜 PlantUML，大概率会看到两种结果：一种是插件装完，Alt+D 一按，右下角转圈半天然后弹一句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 统一 Key

2.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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 基址：https://taotoken.net/api

Key 的创建在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite

如果你只是想先验证模型能不能按 PlantUML 语法输出，可以直接用模型对话页试一句：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite

长期在 VS Code 里做编码和 Agent 类任务的话，Coding Plan 会更省心：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite

3. 可复制配置：settings.json 骨架与插件参数

3.1 打开 settings.json

在 VS Code 里按Ctrl+Shift+P，输入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 用表格对照关键参数

注意：路径里如果包含空格（比如Program Files），JSON 字符串里不需要额外加引号，但反斜杠必须双写。写错的话插件会静默失败，预览窗口只显示空白。

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 里 Alt+D 预览微调，比纯手写快很多。

4. 验证请求：从时序图到类图一次跑通

4.1 第一个时序图

在项目里新建docs/uml/sequence.plantuml，输入：

@startuml Alice -> Bob: 发起登录请求 Bob -> Server: 校验凭证 Server --> Bob: 返回 token Bob --> Alice: 登录成功 @enduml

按Alt+D，右侧应该出现预览窗口，显示四条带箭头的消息线。如果预览窗口提示Cannot find java，回到第 3 节检查plantuml.java路径。如果图出来了但中文是乱码，检查plantuml.commandArgs是否包含-charset UTF-8。

4.2 类图验证 Graphviz 链路

再建一个docs/uml/strategy.plantuml：

@startuml 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 导出图片

预览窗口右上角有导出按钮，也可以按Ctrl+Shift+P输入PlantUML: Export Current Diagram。导出格式由plantuml.exportFormat决定，输出目录是plantuml.exportOutDir。导出成功后在文件管理器里能看到对应的 png 或 svg。

4.4 用 AI 生成一段再验证

把第 3.3 节的 PowerShell 脚本跑一遍，把返回的 PlantUML 代码贴进新文件，再 Alt+D。这一步能同时验证两件事：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 Alt+D 没反应

检查文件扩展名是不是.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_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite

接入细节和参数说明看文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

Key 管理和新建入口：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite

先把第 4 节的两个图跑通，再回头调 AI 生成那段。顺序反了的话，出问题你分不清是渲染链路还是请求链路。