drawio-desktop 完整指南：批量导出图表、离线编辑 VSDX 与跨平台协作-平芜编程栈

drawio-desktop 完整指南：批量导出图表、离线编辑 VSDX 与跨平台协作

【免费下载链接】drawio-desktopOfficial electron build of draw.io项目地址: https://gitcode.com/GitHub_Trending/dr/drawio-desktop

drawio-desktop 是 draw.io 官方团队用 Electron 打包的桌面版图表编辑器，专为需要在 Windows、macOS、Linux 三端之间传递 Visio 文件、把整目录图表批量转成 PNG/PDF 的团队设计。它支持直接打开.vsdx、.mmd（Mermaid）、.csv文件并在线编辑，内置命令行导出引擎，默认不联网、不采集任何使用数据。Apache 2.0 许可，个人与商用均无费用。

它解决了什么问题：与常见替代方案的对比

对比维度	商业绘图套件（如 Visio）	在线转换网站	drawio-desktop
VSDX 打开后可编辑	仅 Windows	多为只读预览或样式丢失	形状、连线、图层均可改
批量导出整目录	需逐文件手动操作	通常单次上传	一条 CLI 命令递归处理
离线 / 内网可用	部分功能依赖云端	必须联网	默认完全离线，CSP 禁止加载远程脚本
数据是否外发	视厂商策略	文件上传到第三方服务器	图表数据仅存本机，不发送任何分析数据
平台覆盖	主要 Windows	任意（需网络）	Windows / macOS / Linux 本地运行
许可	按席位收费	免费但受配额限制	Apache 2.0，免费商用

核心差异点：Visio 的 VSDX 文件离开 Windows 后往往只能"看"不能"改"，在线工具则把文件传到远端处理。drawio-desktop 把解析和渲染都放在本地进程内完成，改完直接存回.vsdx或导出为其他格式。

快速上手：安装与首次运行

方式 A：下载预构建安装包

从项目 Releases 页面获取对应平台的二进制文件。Windows 提供三种形态：

NSIS 安装版（-windows-installer.exe）：装到Program Files，需要管理员权限，适合个人电脑。
MSI 安装版（.msi）：装到用户目录，无需管理员权限，适合公司统一管控的机器。
便携版（-windows-no-installer.exe）：解压即可运行，不注册文件关联，适合 U 盘携带或无权限环境。

macOS 提供.dmg和.zip，Linux 提供.AppImage、.deb、.rpm、.snap。

方式 B：从源码构建

适合想改壳层代码（如窗口标题、导出默认参数）的开发者。前提：Node.js ≥ 22.12.0。

git clone --recursive https://gitcode.com/GitHub_Trending/dr/drawio-desktop cd drawio-desktop npm install npm start

--recursive不可省略——核心编辑器drawio是以 git submodule 嵌入的，缺少它构建会直接失败。如果已经 clone 过，补一句git submodule update --init即可。

首次启动后界面分为三栏：左侧是形状搜索与分类库，中间是带网格的画布，右侧是当前选中对象的属性面板（颜色、字体、连线样式等）。操作逻辑与 Visio 接近，拖入形状后在右侧调整属性即可。

按使用频率拆解核心功能

1. 打开并编辑 VSDX 文件

场景：产品经理在 Windows 上用 Visio 画好架构图，发给 Mac / Linux 同事，对方双击文件提示"无关联程序"或只能看到只读预览。

做法：在 drawio-desktop 中通过文件 → 打开选择.vsdx，或直接拖入窗口。编辑器会解析出形状、连线、分组和图层，全部变成可拖拽、可改色的对象。改完后文件 → 另存为可以选择存回.vsdx（Windows 同事能继续编辑）或导出为.png/.pdf/.svg。

收益：不再需要"截个图 → 群里发 → 对方用截图 PPT 里贴一下"的链路；改一个标注只需几秒，存回后对方在 Visio 里看到的就是更新后的版本。

除了.vsdx，导出模式的输入同样接受.drawio、.xml、.csv、.mmd/.mermaid，详见下文批量导出部分。

2. 命令行批量导出整目录图表

场景：文档仓库里有一百张.drawio流程图需要转成 PNG 嵌进 PDF 手册，逐张打开 → 导出 → 命名，半天就没了。

做法：桌面版内置了 CLI 导出引擎（参数解析逻辑见 src/main/args.js），在终端里执行：

drawio -x -f png -r -o ./exported ./diagrams

参数	含义
`-x`	进入导出模式（不打开 GUI）
`-f png`	输出格式，可选`pdf`、`png`、`jpg`、`svg`、`xml`、`html`
`-r`	递归子目录
`-o ./exported`	输出目录（必须是文件夹，多文件时）

常用扩展参数：

参数	作用
`-t`/`--transparent`	PNG/SVG 透明背景
`-s 2`/`--scale 2`	2 倍缩放，适合 Retina 截图
`--width 800`/`--height 600`	按指定尺寸等比适配
`-b 20`/`--border 20`	图四周留白像素
`-a`/`--all-pages`	PDF/HTML 导出时包含所有页
`-p 2`/`--page-index 2`	只导出第 2 页（1-based）
`-l 0,2`/`--layers 0,2`	只导出第 0、2 层
`-k`/`--check`	不覆盖已存在的输出文件
`-c`/`--create`	无输入文件时创建空文件

写进 Makefile 或 CI 脚本后，每次提交自动重新渲染配图，几秒钟完成。

3. 默认离线运行，数据不出本机

场景：保密项目不允许图表经过任何第三方服务器；或者部署在无外网的内网机房。

做法：drawio-desktop 的主进程在启动时通过 CSP 头（见 src/main/electron.js 中onHeadersReceived拦截逻辑）禁止界面加载任何远程 JavaScript，网络请求被限制为应用自身。所有图表数据存储在本地文件系统，不发送分析数据。

如果连启动时的版本检查也要关掉，有两种方式：

# 方式一：环境变量 export DRAWIO_DISABLE_UPDATE=true drawio # 方式二：启动参数 drawio --disable-update

对应的判断逻辑在 src/main/disableUpdate.js 和 src/main/electron.js 中。个人构建打包时还可通过npm run sync -- disableUpdate让版本永久跳过自动更新（见个人构建指南）。

适用场景与边界

适合

团队成员跨 Windows / macOS / Linux 传递 Visio 文件，且需要"打开即编辑"而非"只读预览"。
文档 / 代码仓库中维护大量图表，需要 CI 批量重新渲染。
内网或保密环境，不允许数据经过第三方服务器。
习惯用 Git 管理图表版本（.drawio是 XML 文本，可直接 diff）。

不适合 / 需要注意

复杂 Visio 工程（数百页、大量自定义形状模板、ActiveX 控件）的 1:1 还原——draw.io 解析 VSDX 时会尽量保留结构，但 Visio 私有扩展属性可能丢失。
需要 Visio 独占的高级功能（如 stencil 数据库、数据链接到 Excel）不在支持范围内。
项目对社区 PR 持封闭策略（见 README 的 "Not open-contribution" 一节），可以 fork 后自行修改构建，但上游不接收功能 PR。
图表中若嵌入了外部 URL 引用的图片/字体，打开时仍会向该 URL 发起请求（这是渲染需要，不是数据上报）。

速查表

CLI 常用命令

用途	命令
批量导出目录为 PNG	`drawio -x -f png -r -o ./out ./diagrams`
导出单个文件为 PDF，带 30px 边距	`drawio -x -f pdf -b 30 file.drawio`
导出透明背景 SVG，2 倍缩放	`drawio -x -f svg -t -s 2 file.drawio`
导出所有页为 HTML	`drawio -x -f html -a file.drawio`
查看版本	`drawio -V`
查看帮助	`drawio -h`

环境变量与启动参数

名称	说明
`DRAWIO_DISABLE_UPDATE=true`	关闭启动时版本检查
`--disable-update`	同上，命令行形式
`--no-silent-update`	下载更新前弹窗确认，而非静默替换
`--disable-acceleration`	禁用硬件加速（兼容旧显卡）
`DRAWIO_ENV=dev`	开发模式，自动打开 DevTools
`DRAWIO_UNSIGNED=true`	个人构建时跳过代码签名（见构建文档）

窗口记忆

桌面版自动记录窗口大小、位置和最大化/全屏状态（逻辑见 src/main/window-bounds.js）。多显示器拔插后，如果上次位置已不可见，窗口会自动回退到主屏居中，避免"窗口跑到不存在的屏幕上"。

本地数据路径

平台	路径
macOS	`~/Library/Application Support/draw.io`
Windows	`C:\Users\<用户名>\AppData\Roaming\draw.io\`

下一步

先装一个预构建包，打开手里那份.vsdx确认能正常编辑，再决定是否需要从源码构建。
把导出命令写进团队的 CI 或 Makefile，让图表随代码一起版本化。
遇到个性化需求（改窗口标题、定制默认导出参数、内网部署），阅读 doc/BUILDING_FOR_PERSONAL_USE.md 中的 fork 构建流程，设好DRAWIO_UNSIGNED=true即可在本地打包签名。

关键文件索引：