draw.io 桌面版上手指南：安装、命令行导出与常见坑-平芜编程栈

draw.io 桌面版上手指南：安装、命令行导出与常见坑

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

draw.io 桌面版（drawio-desktop）是基于 Electron 封装的官方桌面绘图工具，把 draw.io 网页编辑器装进了本地应用，支持离线打开和编辑 .drawio、.vsdx、Mermaid 等文件，也能通过命令行批量导出 PDF、PNG、SVG。读完这篇，你会知道该选哪个安装包、怎么从源码跑起来，以及它的安全边界在哪里。

桌面版是什么，适合谁用

它和浏览器版的功能基本一致，但有两个关键区别：所有数据留在本机，不需要登录账号就能保存文件；应用默认与互联网隔离，只有更新检查会联网。Apache 2.0 协议，免费商用。

典型使用场景：内网电脑不能访问网页版、需要把 Visio 的 .vsdx 文件导入继续编辑、或者想批量把图表导出成图片放进文档。当前版本 31.3.2，基于 Electron 42 构建。

选对 Windows 安装包：三种形态别装错

如果你用 Windows，releases 里会同时放出三个安装包，区别在于安装范围和权限要求，选错会被管理员权限卡住：

安装包	安装位置	是否需要管理员权限
`*-windows-installer.exe`（NSIS）	Program Files，全机器	需要
`*.msi`	当前用户目录	不需要
`*-windows-no-installer.exe`（便携版）	免安装直接运行	不需要，但不注册文件关联

公司电脑上没有管理员权限时，直接用 MSI 或便携版。另外，本地存储位置是固定的：Windows 在C:\Users\<用户名>\AppData\Roaming\draw.io\，macOS 在~/Library/Application Support/draw.io，备份配置时去这里找。

源码构建：三步把 drawio-desktop 跑起来

想改默认行为或验证新功能，可以直接从源码启动，不需要打安装包。前提是有 Node.js 22.12 以上（官方构建用 Node 24）。注意 draw.io 编辑器本体是 git 子模块，clone 时必须加--recursive，否则构建会失败：

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

npm start会直接以开发模式启动应用。调试时可以加--enable-logging参数，或设置DRAWIO_ENV=dev打开 DevTools。一个容易踩的坑：draw.io 只允许每个用户单实例运行，如果官方正式版已在运行，启动你的副本只会往正式版的窗口里开新标签——先退出所有 draw.io 再启动。

用命令行批量导出图表

桌面版自带 CLI 导出模式，参数都定义在 src/main/args.js，用--help能看全。输入除了 .drawio，还支持 .vsdx、.csv、Mermaid（.mmd/.mermaid）；输入可以是文件，也可以是文件夹（配--recursive递归子目录）。几个常用参数：

drawio --export -f pdf diagram.drawio # 单文件导出 PDF drawio --export -r -o out/ ./charts # 递归导出目录，输出到 out/

几个细节：导出多文件时输出必须是文件夹；-p指定页码，从 1 开始数（v27.0.2 之前是 0 开始，老脚本要注意）；-t让 PNG/SVG 背景透明；-a把 PDF/HTML 的所有页都导出；-e可在导出图片里嵌入原始图表数据，方便后续再编辑。

离线与数据安全：它实际做了什么

README 里对安全有明确承诺，可以对照验证：Content Security Policy 禁止运行远程加载的 JavaScript，应用自身网络请求被限制为指向自己，图表数据不会外传，也没有任何使用统计上报。想彻底关掉启动时的更新检查，设置环境变量DRAWIO_DISABLE_UPDATE=true或启动时加--disable-update，这对统管机器的内网部署很实用。

有一个例外要知道：图表里如果引用了外部图片、字体等 URL 资源，打开时仍会发起请求以正确渲染，这会把你的 IP 暴露给那台服务器（不会传图表内容本身）。来源不明的文件建议先在隔离环境里打开一次。

常见坑排查

clone 后启动报错找不到编辑器代码：多半是漏了--recursive，补一句git submodule update --init即可。
启动副本却弹出现在有窗口里：单实例限制，见上文，先退出官方版本。
改完代码没生效：npm start读的是源码树，确认你改的是src/main/下的文件而不是 node_modules 里的副本。
个人构建想打包成安装包：设置DRAWIO_UNSIGNED=true跳过代码签名，但产物是未签名的，系统会拦截提示，且不支持官方支持，详见 doc/BUILDING_FOR_PERSONAL_USE.md 里 macOS/Windows/Linux 的具体命令。
想持续跟踪上游：合并前先git checkout -- package.json src/main/disableUpdate.js，因为这两个文件会被构建脚本重写，直接合并会被 git 拒绝。