TurboWarp Desktop 构建指南:用 electron-builder 打包 Windows、macOS 与 Linux 全平台

原创2026-11-13 09:39:081,649 阅读
文章标签:桌面应用

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 桌面版应用图标

📦 构建流程一览

TurboWarp Desktop 基于 Electron 开发,整体打包分为三步:

  1. 安装依赖:npm ci 安装全部开发依赖(含 Electron 与 electron-builder)
  2. 拉取资源:npm run fetch 下载积木扩展库、Packager 组件与内置扩展
  3. 生产构建 + 打包: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 说明。

📁 关键文件索引


至此你已经掌握了 TurboWarp Desktop 从源码到全平台安装包(Windows NSIS/便携版、macOS DMG、Linux deb/AppImage/tar.gz)的完整构建方法。日常只需记住三步:npm ci → npm run fetch → npm run webpack:prod + electron-builder 命令,即可在任意一个操作系统上产出对应平台的可分发包。

登录后查看全文
desktop