draw.io 架构图源文件、导出与版本治理手册
draw.io 适合需要精确布局、丰富图形和人工编辑的架构图。官方推荐的可维护格式是 .drawio，它保存完整 XML 图源；PNG、SVG 和 PDF 还可以选择嵌入图源，使阅读文件重新变得可编辑。这个便利也构成数据边界：公开一张图片时，可能同时公开隐藏页面、内部链接和完整图形结构。
先选择信任边界清楚的入口
网页编辑器便于协作，桌面版适合离线和受限数据，Confluence 等集成则继承宿主平台的权限。三者不是同一个运行环境。敏感架构图优先使用受控桌面版或自建入口，普通团队图可以使用网页端，但要明确存储位置、账号来源和外部分享策略。
安装或启用桌面版后，不要把“能打开”当作完成。应记录版本来源、自动更新策略、默认存储目标和允许的外部资源。VS Code 扩展不是 draw.io Desktop 本身，进入标准工具链前要单独审查维护者与权限。
源文件和导出物双轨保存
仓库保存 .drawio 作为事实源，站点使用 SVG 或 PNG 作为消费输出。两者放在可推导的位置，并通过命名保持对应关系。图源变化与导出物应在同一提交，评审者既看 XML diff，也看渲染结果。
architecture/
sources/payment-context.drawio
exports/payment-context.svg
README.mdXML diff 不总是友好，因此要控制页面尺寸、字体、主题和压缩设置，减少无关重排。多人同时编辑同一个画布容易形成难以合并的冲突；大型图应按系统边界拆分，并指定单次变更的写入 owner。
用可复现导出建立正向验证
桌面应用支持命令行导出时，可以把源到输出接进项目脚本。配置影响包括页面选择、裁切、缩放、透明背景、字体与是否嵌入图源。公开输出通常关闭嵌入图源，内部交接输出则可以保留可编辑数据。
draw.io --export --format svg --crop --output architecture/exports/payment-context.svg architecture/sources/payment-context.drawio正向实验要确认输出尺寸、文字可读、连线完整、链接符合策略，并在干净环境中重新生成。若仓库提交导出物，CI 执行生成后应得到空 diff。这个结果证明图源和输出一致，比检查文件时间更可靠。
反向实验揭示隐藏数据
反例可以在图源中加入一个隐藏页面、一条内部 URL 和一张外部图片，再分别导出带嵌入数据与不带嵌入数据的 SVG。检查文件内容和重新导入行为，确认公开配置不会携带完整图源。另一个失败实验是只修改 SVG，不改 .drawio，门禁应通过重建差异发现分叉。
导出错误先检查页选择、边界框、字体和外部资源。网页端正常、CI 缺图通常意味着资源只存在浏览器缓存或外部地址；SVG 文字错位多半来自字体替换；命令返回成功但图被裁切，则是导出参数与画布边界不一致。保留原始源、命令和失败输出，便于视觉复核。
权限、发布与数据清理
图形中的系统名、网络区、账号、客户标识和内部链接都可能敏感。公开前不仅看画布可见区域，还要检查页面、图层、备注、超链接、附件和嵌入 XML。图片元数据与链接白名单应进入发布检查，不能依赖作者记忆。
共享存储的权限由文件平台决定，在线协作链接则可能绕过仓库权限。团队治理需要统一入口：可编辑图源留在受控仓库或空间，只读输出进入公开站点，临时分享设置到期时间。成本和容量关注大图、内嵌图片、历史版本与导出频率，避免把二进制资源无限复制进 Git。
清理、回滚与退出
删除旧图之前先查询页面引用和文档链接，再保留重定向或替代说明。清理嵌入图片时，必须先证明导出仍能离线重建。升级后出现大面积布局变化时，回滚桌面版本与字体环境，不能用手工微调每个节点掩盖工具变化。
退出 draw.io 时，恢复目标是图源可继续编辑、只读输出可查看、链接关系可追踪。先批量导出标准 SVG/PDF，再保存原始 .drawio 和版本信息，最后用目标工具抽样导入并验证文字、分组与连线。迁移不是得到一批截图，而是保住可编辑结构和业务语义。