TurboWarp Desktop 构建指南:用 electron-builder 打包 Windows、macOS 与 Linux 全平台
TurboWarp Desktop 构建指南:用 electron-builder 打包 Windows、macOS 与 Linux 全平台
TurboWarp Desktop 是一款更好用的离线版 Scratch 3 编辑器,它内置了编译器、深色模式与大量增强插件。本文将带你完整掌握如何用 electron-builder 从源码构建 TurboWarp Desktop,分别打包出 Windows 安装包、macOS DMG 和 Linux 发行版(deb、AppImage、tar.gz),并介绍项目自带的发布自动化脚本。
📦 构建流程一览
TurboWarp Desktop 基于 Electron 开发,整体打包分为三步:
- 安装依赖:
npm ci安装全部开发依赖(含 Electron 与 electron-builder) - 拉取资源:
npm run fetch下载积木扩展库、Packager 组件与内置扩展 - 生产构建 + 打包:
npm run webpack:prod生成优化后的渲染进程代码,再用 electron-builder 输出最终安装包
这些步骤都在 README.md 的 Development 与 Final production-ready builds 章节中有详细说明。
🛠️ 一键搭建开发环境
克隆仓库时需要带上子模块(编辑器核心 scratch-gui 以子模块形式引入):
git clone --recursive https://gitcode.com/gh_mirrors/desktop8/desktop turbowarp-desktop
cd turbowarp-desktop
npm ci
npm run fetch
⚠️ 每次从仓库拉取新代码后,都要重新执行上面三组命令。
本地运行验证环境是否正常:
npm run webpack:compile
npm run electron:start
开发时推荐开两个终端:一个跑 npm run webpack:watch 监听代码变更,一个跑 npm run electron:start,渲染层改动按 Ctrl+R 即可刷新。
📋 读懂 electron-builder 配置
所有平台打包配置都集中在 package.json 的 build 字段,几个关键点值得新手关注:
| 平台 | 打包目标 | 产物命名规则 |
|---|---|---|
| Windows | nsis 安装器 + portable 便携版(x64) |
TurboWarp Portable 1.17.0 x64.exe |
| macOS | dmg 通用版(Intel + Apple Silicon) |
TurboWarp-Setup-1.17.0.dmg |
| Linux | deb + appimage + tar.gz |
TurboWarp-linux-x64-1.17.0.deb |
此外配置里还包含:
- 文件关联:打包后的应用会自动关联
.sb、.sb2、.sb3三种 Scratch 工程文件 - 应用图标:通过
extraResources附带 art/icon.png 等图标资源 - macOS 安全策略:启用
hardenedRuntime(强化运行时)与权限声明(摄像头、麦克风用途说明)
🚀 三种平台的最快打包命令
先执行生产级 webpack 构建(比开发构建更小更快):
npm run webpack:prod
然后直接用 electron-builder CLI 打包,产物统一输出到 dist/ 目录:
# Windows 安装包(需在 Windows 系统上运行)
npx electron-builder --windows nsis --x64
# macOS 通用版 DMG(需在 macOS 上运行)
npx electron-builder --mac dmg --universal
# Linux Debian 包(需在 Linux 上运行)
npx electron-builder --linux deb
💡 经验法则:在哪个系统上就只能打包哪个系统的发行版(macOS 可以借助 universal 目标同时产出双架构版本)。
如果只想验证打包逻辑而不生成安装包,可以先打一个未压缩的目录版本调试:
npm run electron:package:dir
对应 package.json 中的 electron:package:dir 脚本,等价于 electron-builder --dir。
🤖 进阶:使用项目自带的发布自动化脚本
正式发布时,团队使用 release-automation/ 下的自动化脚本(说明见 release-automation/README.md),它会一次性构建"平台 × 架构"的完整矩阵。常用参数包括:
- 选平台:
--windows、--windows-portable、--mac、--debian、--appimage、--tarball,以及各平台的-dir调试模式 - 选架构:
--x64(默认)、--ia32、--arm64、--armv7l、--universal - 发布模式:
--production启用更新检查器、开启 macOS 公证等
例如 --windows --windows-portable --x64 --arm64 会一次产出 4 个构建。
Linux 侧的完整发布流水线脚本是 release-automation/linux.sh,它串联了 Flatpak、AUR、Snap 和 Debian apt 仓库(debian/everything.sh)的更新;macOS 端还额外提供了 Microsoft Store(appx)与 Mac App Store(mas)的配置,见 package.json 中的 appx 与 mas 字段。
🐞 常见问题速查
Linux 开发时报 chrome-sandbox 沙盒错误怎么办? Debian 10 及更早、Ubuntu 24.04 及更新版本上运行开发版 Electron 时可能出现该报错,可临时开启非特权用户命名空间(重启后失效,打包好的正式 .deb / Snap / Flatpak 不受影响):
sudo sysctl -w kernel.unprivileged_userns_clone=1
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
Linux 开发版应用图标不显示? 这是已知现象,打包后的正式版会正常显示图标。
Mac App Store 打包报签名证书错误? 需要配置 Apple 的 Developer ID / Mac App Distribution 证书与 Provisioning Profile,详见 release-automation/README.md 的 Mac App Store 章节的 Troubleshooting 说明。
📁 关键文件索引
- 入口文件:src-main/entrypoint.js(Electron 主进程)
- webpack 构建配置:webpack.config.cjs
- 资源拉取脚本:scripts/download-library-files.mjs、scripts/prepare-extensions.mjs
- 发布自动化说明:release-automation/README.md
- 自动更新检查器源码:src-main/update-checker.js
至此你已经掌握了 TurboWarp Desktop 从源码到全平台安装包(Windows NSIS/便携版、macOS DMG、Linux deb/AppImage/tar.gz)的完整构建方法。日常只需记住三步:npm ci → npm run fetch → npm run webpack:prod + electron-builder 命令,即可在任意一个操作系统上产出对应平台的可分发包。