企业官网建设流程全解析

1. 为什么我最后用 VS Code + PlantUML 画 UML

如果你也经历过「打开一个 UML 软件，拖了半天框，导出的图丑得不想放进文档」这件事，那我们大概率是同路人。我最早画类图用的是那种拖拽式工具，画完自己都不想看第二眼：线条歪、对齐难、改一个类名要重新拖一遍。后来接触到 PlantUML，才发现 UML 原来可以用「写代码」的方式画出来——文本即图形，改一行字图就变了，版本管理也友好，丢进 Git 里 diff 一目了然。

这篇要解决的核心问题很具体：在 VS Code 里搭一套以 PlantUML 为主、Graphviz 为渲染后端的 UML 绘图工作流。PlantUML 负责把文本描述解析成图形语义，Graphviz 负责把节点和连线做自动布局（尤其是类图、组件图这种关系密集的图，没有 Graphviz 布局会很难看）。VS Code 只做一件事：当你的编辑器和预览器。

适合谁看？三类人最合适。第一类是要在技术文档、毕业设计、项目设计里画类图/时序图/用例图的开发者；第二类是想把 UML 纳入代码仓库、用文本方式维护图表的工程师；第三类是想顺手把 AI 模型通道也统一管理起来的人——因为下面我会给一套 TaoToken 统一 Key 的配置，让 VS Code 里的 AI 辅助和 UML 工作流共用一个 API 入口，不用每个插件单独填 Key。

先说清楚这套工作流的三个关键点，避免你走弯路：

• PlantUML 本体是 Java 写的，所以机器上必须有 JDK，插件才能调用它渲染。
• Graphviz 是可选但强烈建议装的，类图里继承、聚合这些关系线，靠 Graphviz 的 dot 布局引擎排出来才整齐。
• VS Code 插件只是壳，真正干活的是本地的 plantuml.jar 和 dot.exe，插件通过环境变量或 settings.json 找到它们。

我实测下来，只要这三样东西路径配对，预览和导出就非常稳。下面按「装依赖 → 配插件 → 写配置 → 验证 → 排错」的顺序走，每一步都给可复制的片段。

2. 前置准备：JDK、Graphviz 与 TaoToken 统一 Key 的接入

这一节把「画图依赖」和「模型通道」两件事一起准备好。画图依赖是硬性的，缺了预览直接报错；TaoToken 统一 Key 是加分项，让你后面在 VS Code 里用 AI 辅助写 PlantUML 语法、解释类图结构时，不用到处找 Key。

2.1 安装 JDK 并确认 JAVA_HOME

PlantUML 依赖 Java 运行环境。装 JDK 17 或 21 都行，装完在终端验证：

java -version

能打印出版本号就说明 PATH 通了。接着确认JAVA_HOME指向 JDK 根目录（不是 bin 目录）：

# Windows PowerShell echo $env:JAVA_HOME # macOS / Linux echo $JAVA_HOME

如果为空，就手动设一下。Windows 在「系统属性 → 环境变量」里新建JAVA_HOME，值类似C:\Program Files\Java\jdk-21；macOS/Linux 在~/.zshrc或~/.bashrc里加：

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home export PATH=$JAVA_HOME/bin:$PATH

2.2 安装 Graphviz 并确认 dot 可用

Graphviz 提供dot布局引擎。Windows 下载 msi 安装包，安装时勾选「Add Graphviz to the system PATH」；macOS 用brew install graphviz；Linux 用apt install graphviz。装完验证：

dot -V

输出类似dot - graphviz version 12.0.0就对了。记住dot可执行文件的完整路径，Windows 一般是C:\Program Files\Graphviz\bin\dot.exe，后面配置要用。

2.3 下载 plantuml.jar

去 PlantUML 官网下载plantuml.jar，放到一个固定目录，比如D:\tools\plantuml\plantuml.jar或~/tools/plantuml/plantuml.jar。这个 jar 就是渲染核心，插件会调用它。

2.4 TaoToken 统一 Key 的获取与定位

TaoToken 在这里的角色是「统一模型通道」：你在 VS Code 里可能同时用多个 AI 插件（写注释、生成 PlantUML 片段、解释类图），如果每个插件都单独配 Key，管理起来很乱。用 TaoToken 一个 Key 走一个 Base URL，就能统一收口。

获取入口在官网控制台，注册后进 API Keys 页面创建：

• 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

创建后你会拿到一个形如sk-xxxx的 Key。Base URL 统一用https://taotoken.net/api（注意这个地址不加 UTM 参数，是给程序调用的）。Model ID 按你需要的模型填，比如claude-sonnet-4-5、gpt-4o这类，具体以文档里的模型列表为准。

注意：Key 只显示一次，创建后立刻复制保存。不要把它硬编码进会提交到 Git 的文件里，建议用环境变量或 VS Code 的 secrets 机制。

到这里，画图三件套（JDK、Graphviz、plantuml.jar）和模型通道（TaoToken Key + Base URL + Model ID）都齐了。下一节开始配 VS Code。

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

这一节是全文最核心的部分，所有片段都能直接复制。VS Code 里画 PlantUML 主流有两个插件方向：一个是老牌的jebbs.plantuml（功能全、导出强），另一个是偏轻量的预览插件。我建议用jebbs.plantuml，它对 Graphviz 和导出 PNG/SVG 支持最完整。

3.1 安装插件

在 VS Code 扩展面板搜索PlantUML，认准作者jebbs，点安装。装完重载窗口。这个插件支持.puml、.plantuml、.pu、.wsd、.iuml等后缀，预览快捷键默认Alt+D。

3.2 settings.json 完整片段

按Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入Open User Settings (JSON)，把下面这段合并进去。路径按你自己的实际安装位置改：

{ "plantuml.render": "Local", "plantuml.java": "java", "plantuml.jar": "D:/tools/plantuml/plantuml.jar", "plantuml.commandArgs": [], "plantuml.dotPath": "C:/Program Files/Graphviz/bin/dot.exe", "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.render设为Local，表示用本地 jar 渲染，不依赖远程服务器，离线也能用。
• plantuml.jar用正斜杠/或双反斜杠\\，不要用单反斜杠，否则 JSON 转义会出错。
• plantuml.dotPath指向 Graphviz 的dot.exe，这是类图布局整齐的关键。
• plantuml.exportFormat可改svg，矢量图放进文档更清晰。
• plantuml.server只在render设为PlantUMLServer时才生效，本地渲染时它只是备用。

3.3 用环境变量兜底（可选）

如果你不想在 settings.json 里写死路径，也可以用环境变量，插件会优先读配置、读不到再读环境变量：

# Windows PowerShell（临时会话） $env:PLANTUML_JAR="D:\tools\plantuml\plantuml.jar" $env:GRAPHVIZ_DOT="C:\Program Files\Graphviz\bin\dot.exe" # macOS / Linux export PLANTUML_JAR=~/tools/plantuml/plantuml.jar export GRAPHVIZ_DOT=/opt/homebrew/bin/dot

3.4 TaoToken 通道配置（供 AI 插件复用）

如果你在 VS Code 里用 Cline、Continue 这类 AI 插件辅助写 PlantUML，可以统一填 TaoToken 的三件套。以常见的 OpenAI 兼容配置为例：

{ "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoTokenKey", "model": "claude-sonnet-4-5" }

三件套对应关系必须写全，缺一个就连不上：

提示：如果你用的是 Claude Code 这类工具，配置项名称可能是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，值同样指向 TaoToken 的 API 地址和你的 Key，Model ID 填对应模型。具体字段名以接入文档为准。

配置写完，保存。下一节直接验证。

4. 三步验证：本地预览、导出 PNG/SVG、切换模型通道重跑

配置对不对，跑一遍就知道。这一节给三个验证步骤，每步都有明确的成功标志。

4.1 第一步：本地预览成功

新建一个文件docs/uml/collection.puml，写入下面这段类图（JDK 集合框架的简化版）：

@startuml abstract class AbstractCollection { {abstract} +int size() {abstract} +Iterator<E> iterator() } abstract class AbstractList { +Iterator<E> iterator() } interface Collection interface List interface Set class ArrayList class LinkedList class HashSet Collection <|-- List Collection <|-- Set Collection <|.. AbstractCollection List <|.. AbstractList List <|.. ArrayList List <|.. LinkedList Set <|.. HashSet AbstractCollection <|-- AbstractList @enduml

按Alt+D打开预览。成功标志：右侧出现一张类图，继承关系是空心三角实线，实现关系是空心三角虚线，节点自动排布不重叠。如果图出来了但线条乱，多半是 Graphviz 没配好，回到 3.2 检查dotPath。

4.2 第二步：导出 PNG 和 SVG

在.puml文件里按Ctrl+Shift+P，输入PlantUML: Export Current Diagram，选择导出格式。或者用命令面板里的Export Workspace Diagrams批量导出。

导出成功后，去docs/uml/out目录看，应该有collection.png。再导一次 SVG，对比一下：PNG 适合贴聊天工具，SVG 放大不糊，适合放进技术文档。成功标志：两个文件都能正常打开，SVG 用浏览器打开缩放后线条依然锐利。

4.3 第三步：切换模型通道后重跑一次

这一步验证 TaoToken 通道是否通。在 AI 插件里让它生成一段 PlantUML 时序图描述，比如「生成一个用户登录的 PlantUML 时序图」。如果插件返回了正常的 PlantUML 代码，说明 Base URL + Key + Model ID 三件套生效。

你也可以直接用 curl 验证通道：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "用一句话说明PlantUML是什么"}] }'

成功标志：返回 JSON 里有choices字段和正常文本内容。拿到返回后，把生成的 PlantUML 代码贴回.puml文件，再按Alt+D预览一次——如果图正常渲染，说明「模型通道 + 绘图工作流」整条链路都通了。

注意：如果 curl 报 401，先检查 Key 有没有复制全、有没有多余空格；如果报 model not found，去文档核对 Model ID 拼写。

5. 本篇常见报错排查：401、local proxy failed、reading choices、OAuth

这一节按真实报错来对，遇到哪个查哪个。

5.1 预览报Cannot find java或JAVA_HOME not set

现象：按Alt+D后弹出错误，提示找不到 Java。原因：插件调java命令失败。排查顺序：终端跑java -version是否正常；JAVA_HOME是否指向 JDK 根目录；VS Code 是否在改环境变量之前就打开了（改完要重启 VS Code，让它重新读环境变量）。如果还不行，在 settings.json 里把plantuml.java写成 java 可执行文件的绝对路径。

5.2 报local proxy failed或dot executable not found

现象：预览能出图但布局很乱，或者直接报 dot 找不到。原因：Graphviz 路径不对。排查：终端跑dot -V；确认plantuml.dotPath指向的是dot.exe而不是bin目录；Windows 路径用正斜杠。修好后重载窗口再预览。

5.3 API 返回 401 Unauthorized

现象：curl 或 AI 插件报 401。原因：Key 无效或格式不对。排查：确认 Key 是sk-开头且完整；确认请求头是Authorization: Bearer sk-xxx；确认 Base URL 是https://taotoken.net/api而不是带 UTM 的官网地址。如果 Key 是在别的项目里用过的，去控制台确认它没被删除或禁用。

5.4 返回体里reading 'choices'报错

现象：代码里访问response.choices[0]时报Cannot read properties of undefined (reading 'choices')。原因：返回体结构和你预期的不一样，通常是请求失败返回了错误对象，而不是正常的 chat completion。排查：先把原始返回console.log出来，看有没有error字段；检查 Model ID 是否拼错；检查请求体 JSON 是否合法。修好请求后，choices自然就有了。

5.5 OAuth 相关报错

现象：某些 CLI 工具（如 Claude Code）报 OAuth 或认证失败。原因：这类工具默认走官方 OAuth 流程，需要改成 API Key 模式。排查：在工具配置里把认证方式切到 API Key，填 TaoToken 的 Base URL 和 Key。如果工具支持auth.json或环境变量，按文档把ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY指向 TaoToken。改完重跑一次验证请求。

5.6 导出中文乱码

现象：导出的 PNG 里中文变成方块。原因：PlantUML 默认字体不含中文。解决：在.puml里加一行skinparam defaultFontName "Microsoft YaHei"（Windows）或"PingFang SC"（macOS），再重新导出。

6. 把这条链路用顺：统一 Key 与绘图工作流的长期搭配

走到这里，你应该已经能在 VS Code 里稳定地写 PlantUML、预览、导出 PNG/SVG，并且模型通道也验证通过了。最后聊几个我实际用下来觉得值得固化的习惯，帮你把这条链路用顺。

第一，把 UML 源文件当代码管理。.puml文件放docs/uml，导出的图放docs/uml/out，.gitignore里忽略 out 目录，只提交源文件。这样每次改图都有 diff，评审时能看清改了哪个类、哪条关系。

第二，统一 Key 的价值在「少配一次」。VS Code 里 AI 插件、终端里的 CLI 工具、甚至你本地跑的小脚本，只要都指向https://taotoken.net/api这一个 Base URL，换模型时只改 Model ID，不用每个工具翻一遍配置。长期编码或跑 Agent 任务的话，可以看看 Coding Plan 这类方案，把额度集中管理：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite

第三，验证模型通道时用模型对话页面最直观。不想写 curl 的时候，直接在网页里发一句话看返回：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite

第四，排障优先看两个地方：VS Code 的「输出」面板选 PlantUML，能看到插件调用 java 和 dot 的完整命令；API 报错先看原始返回体，别急着改代码。这两个习惯能省掉大半排查时间。

如果你还没创建 Key，从 API Keys 页面开始：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

配置字段拿不准就翻接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

需要看整体能力入口就去官网：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

最后留一个我踩过的坑：改完settings.json一定要重载 VS Code 窗口（Ctrl+Shift+P→Reload Window），插件不会热读所有配置项，尤其是plantuml.jar和dotPath这种路径类配置。重载一次，比反复猜哪里配错快得多。