VSCode预览DOT文件需先安装Graphviz并确保dot命令可执行；推荐插件为Graphviz Preview，中文需在DOT中声明fontname；布局混乱时应简化参数或换引擎。
VSCode 能直接预览 DOT 文件，但前提是 Graphviz 引擎本身已正确安装并被系统识别——插件只是“调用者”，不是“执行者”。
dot 命令必须在终端里能直接运行
这是整个流程的基石。VSCode 插件（如 Graphviz Preview 或 Graphviz Interactive Preview）启动时会尝试执行 dot 命令；如果系统找不到它，预览必然失败，报错类似 Error: Failed to execute dot. Is Graphviz installed and in your path?。
验证方式很简单：打开任意终端（Windows 的 PowerShell/CMD、macOS/Linux 的 Terminal），输入：
dot -V
必须看到类似 dot - graphviz version 2.50.0 的输出。否则说明：
- Graphviz 根本没装（去官网下载或用包管理器装）
- 装了但没勾选“Add to PATH”（Windows）或没把
bin/目录加进 shell 的$PATH（macOS/Linux） - VSCode 没继承当前 shell 的环境变量（特别是 Windows 下从开始菜单启动的 VSCode，可能看不到你手动改的 PATH）
Windows 用户若已安装但 dot -V 失败，别依赖插件自动探测，直接在 VSCode 设置中手动指定路径：
"graphviz-interactive-preview.dotPath": "C:\Program Files\Graphviz\bin\dot.exe"
插件选 Graphviz Preview 就够用
VSCode 扩展市场里叫 “Graphviz” 的插件有好几个，真正专注预览、轻量且维护活跃的是 Graphviz Preview（作者是 joaompinto）。它不提供语法高亮或代码片段——那些由另一个插件 Graphviz (dot) language support 负责，两者可共存，但预览功能只靠前者。
安装后，新建一个文件，保存为 arch.dot（后缀必须是 .dot 或 .gv），内容例如：
digraph System {<br> A [label="API Gateway"];<br> B [label="Auth Service"];<br> C [label="User DB"];<br> A -> B;<br> B -> C;<br>}右上角会出现 “Open Preview” 按钮，点它即可实时渲染。不需要保存触发，编辑时就会自动刷新（部分旧版插件需手动保存，新版默认开启 live update）。
中文乱码、字体糊成方块？优先改 node 属性
架构图里节点带中文，一预览就显示为小方块，不是插件问题，是 Graphviz 渲染时找不到可用中文字体。它默认用 Helvetica，而该字体在多数 Linux/macOS 系统里不含中文，在 Windows 上也可能因区域设置失效。
最稳妥的做法是在 DOT 文件开头显式声明兼容字体：
digraph System {<br> node [fontname="Microsoft YaHei, SimSun, sans-serif"];<br> edge [fontname="Microsoft YaHei, SimSun, sans-serif"];<br> // 后续节点和边定义<br>}注意：fontname 值是逗号分隔的备选列表，Graphviz 会按顺序找第一个存在的字体。不要写绝对路径，也不要试图配置系统级字体缓存——DOT 文件内声明是最可控的方式。
子图、集群、布局参数调不好？先关掉 rankdir 再试
画分层架构图时，常想用 rankdir=TB（从上到下）控制流向，但一旦加上，节点可能挤成一团或连线交叉严重。这不是 bug，是 Graphviz 的 dot 布局器在约束条件下做的妥协。
调试建议：
- 先把
rankdir、nodesep、ranksep全部删掉，看默认布局是否可读 - 确认节点名没含空格或特殊字符（用下划线代替，如
DB_Server） - 子图必须用
subgraph cluster_xxx形式（cluster_是关键字前缀），普通subgraph不会加框也不影响层级 - 如果仍混乱，换布局引擎试试：
neato（力导向）、fdp（更松散的力导向）或circo（环形），只需把文件第一行改成strict digraph并在插件设置里指定引擎
真正容易被忽略的是：Graphviz 的“自动布局”本质是求解约束满足问题，它不保证每次结果都符合人眼直觉。复杂架构图与其硬调参数，不如拆成多个小图，用逻辑分组 + 显式 rank=same 控制对齐。
