需安装PlantUML插件、Graphviz及配置本地渲染路径，确保文件为.puml格式并含@startuml/@enduml，使用UTF-8无BOM编码且语法正确。
如果您在 VSCode 中使用 PlantUML 插件编写架构图代码，但预览窗口未渲染图形或显示空白，则可能是由于插件配置缺失、Graphviz 未安装或语法错误导致。以下是解决此问题的步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、确认并安装 PlantUML 插件与依赖
VSCode 中的 PlantUML 渲染依赖于插件本身及后端渲染引擎（如 Graphviz 或 PlantUML 服务器）。仅安装插件不足以启用本地绘图功能，必须确保底层工具链完整。
1、打开 VSCode 扩展市场，搜索 PlantUML，安装由 jebbs 发布的官方插件。
2、在终端中执行 dot -V 验证 Graphviz 是否已安装；若提示命令未找到，则需通过 Homebrew 安装：brew install graphviz。
3、重启 VSCode，确保插件激活状态为已启用。
二、配置 VSCode 的 PlantUML 设置项
默认情况下，PlantUML 插件可能未启用本地 Graphviz 渲染，需手动指定可执行路径，否则会回退至在线服务（受网络与防火墙限制）。
1、按下 Cmd + , 打开设置界面，在搜索框输入 plantuml.render。
2、将 PlantUML: Render 设置为 local。
3、继续搜索 plantuml.java，点击 Edit in settings.json，添加如下行："plantuml.java": "/opt/homebrew/opt/openjdk/bin/java"（路径需根据本机 OpenJDK 实际位置调整）。
三、验证 PlantUML 代码语法与文件关联
PlantUML 文件必须以正确扩展名保存且首行声明语言类型，否则插件无法识别为可渲染源码，预览功能将失效。
1、新建文件，保存为 architecture.puml（扩展名必须为 .puml 或 .pu）。
2、在文件顶部第一行写入 @startuml，末尾写入 @enduml。
3、在两者之间插入标准架构图示例，例如：[Web Server] --> [API Gateway]。
四、启用实时预览并排除编码干扰
VSCode 默认不自动开启预览窗格，需手动触发；同时，UTF-8 BOM 或非 ASCII 字符编码可能导致解析中断，需统一为无 BOM 的 UTF-8。
1、右键编辑器内 PlantUML 文件内容，选择 Preview PlantUML，或使用快捷键 Cmd + Shift + P 后输入 PlantUML: Preview Current Diagram。
2、点击右下角编码标识（如 UTF-8），选择 Reopen with Encoding → UTF-8，确保无 BOM。
3、检查文件中是否混用全角标点（如中文顿号、引号），全部替换为半角符号。
