EchoMusic 多平台打包与 CI 发布完整指南一次推送如何生成 arm64/x64 安装包【免费下载链接】EchoMusic 一个简约的第三方酷狗概念版音乐播放器项目地址: https://gitcode.com/gh_mirrors/ec/EchoMusicEchoMusic 是一款基于 Electron 的简约第三方酷狗概念版音乐播放器。它的多平台打包由 GitHub Actions 构建矩阵自动完成推送版本 Tag 后六组并行任务会在 macOS、Linux、Windows 的 arm64 与 x64 环境上分别用 electron-builder 生成 DMG、NSIS 安装包和 Linux 多格式包并自动发布到 Releases。本文带你完整看懂这条 CI 发布流水线。打包全流程一图看懂Vite 打包、Rust 编译、electron-builder 组装EchoMusic 的一个安装包由三层产物拼成这也是理解整个 CI 流程的钥匙前端与主进程Vite 把渲染进程、主进程和 preload 脚本打包进dist与dist-electron见 vite.config.mts。Rust Native 模块音频播放、音频采集、媒体控制、SQLite 存储、DLNA/UPnP、AirPlay 等能力由 7 个 Rust 模块提供用 napi-rs 编译成.node文件见 native/。electron-builder 组装把前两层加上服务端依赖、图标、许可证组装成各平台安装包。⚠️ 关键点.node产物不随源码提交且x64 与 arm64 的.node文件不能互换。这就是 CI 必须为每种架构单独编译的原因。GitHub Actions 构建矩阵6 个平台目标并行出包主发布流程定义在 build.yml由两类事件触发推送v*格式的 Tag自动发版手动workflow_dispatch演练/补包构建矩阵定义在 build.yml 第 50~106 行fail-fast: false保证某个平台失败不会连累其他平台目标产物Runnerelectron-builder 参数架构EchoMusic-macOS-arm64macos-14--mac --arm64ad-hoc 签名arm64EchoMusic-macOS-x64macos-14--mac --x64ad-hoc 签名x64EchoMusic-Linux-x64ubuntu-22.04默认x64EchoMusic-Linux-arm64ubuntu-22.04-arm--linux --arm64arm64EchoMusic-Windows-x64windows-latest--win --x64x64EchoMusic-Windows-arm64windows-11-arm--win --arm64arm64每个任务内部还有几个值得学习的细节缓存三连pnpm 依赖缓存、Rust workspace 缓存、electron-builder 二进制缓存显著缩短构建时间。Native 模块并行编译用 shell 后台任务并行构建 6~7 个模块任一失败整体报错build.yml 第 154~182 行。FFmpeg 链接校验用otool -L/ldd检查播放器模块没有意外链接到系统 FFmpeg保证播放器自包含build.yml 第 184~216 行。打包后验证逐个检查.node是否真的进了resources/native/Windows 还会校验任务栏辅助程序是否随包分发build.yml 第 267~295 行。electron-builder 打包配置目标格式与附加资源一览所有打包规则集中在 package.json 的build字段几个对新手最实用的要点各平台安装格式macOS 输出dmgzipWindows 输出 NSIS 安装包Linux 一次产出AppImage、deb、pacman、rpm、tar.gz五种格式linux target。统一命名模板artifactName统一为${productName}-${version}-${os}-${arch}.${ext}保证 artifact 名可预测、易于下载脚本识别。extraResources所有.node文件、图标目录、CHANGELOG.md、LICENSE和服务端server/node_modules都通过 extraResources 配置 塞进包内Windows 额外携带echo-platform-adaptor.node和任务栏布局辅助 exe。macOS 权限声明extendInfo中声明了麦克风、音频采集、本地网络等用途描述CI 里还会用codesign验证签名与 entitlementsbuild.yml 第 297~313 行。npmRebuild: false打包时只复制现有 Native 产物、不重新编译所以架构必须提前对齐。 打包产物清单macOS 为dmg/zipWindows 为exe (nsisx64/arm64)Linux 为deb/rpm/AppImage/tar.gz等。草稿 Release让自动更新永远看不到半成品这是整条流水线里最精巧的设计。electron-updater 靠latest.ymlWindows、latest-mac.yml等元数据文件判断新版本如果 Release 里出现了安装包却缺元数据客户端会误报更新失败。release job 的处理策略先把已存在的同名 Release 设为draft隐藏上传全部 artifact 并写入从 CHANGELOG.md 自动提取的当前版本更新日志全部上传成功后才取消 draft对外转正发布版本号含-时自动标记为预发布prerelease。发布成功后流水线还会把新增 N · 优化 N · 修复 N的摘要推送到 Telegram 和 QQ 群notify job。单独编译 Native 模块Build Native Addons 手动工作流如果你不需要完整安装包只想为本地打包准备.node产物可以用独立的 build-native.yml 工作流手动触发时可分别勾选 macOS arm64/x64、Linux arm64/x64、Windows arm64/x64未勾选的目标不会启动选中的目标在独立矩阵任务中并行编译矩阵生成逻辑每个平台上传一个 artifact如EchoMusic-native-windows-arm64解压到仓库根目录即可恢复本地构建所需的目录布局该流程只上传 artifact不创建 Release也不是完整安装包。Linux 包含 6 个通用模块macOS/Windows 额外包含echo-platform-adaptor任务栏与窗口合成适配Linux 无需构建。常见打包问题速查现象原因与对策Cannot find module .../echo-*.node对应 Native 模块未编译或产物路径错误检查native/模块/模块名.node是否存在Unable to find libclangLLVM/libclang 未安装或LIBCLANG_PATH未指向库目录打包后应用启动崩溃大概率是.node架构与打包目标不一致x64 与 arm64 不能混用macOS 应用被系统拦截ad-hoc 签名限制可执行xattr -cr与codesign --force --deep --sign -重新签名详见 README自动更新检查失败macOS 发行版为 ad-hoc 签名暂不支持 Squirrel.Mac 自动安装更新需手动替换 DMG更多打包细节依赖瘦身策略、体积对比、Electron 升级回归清单可参阅 docs/packaging.md编译发布的完整说明见 README.md 编译发布章节。相关资源导航主发布工作流.github/workflows/build.ymlNative 模块专用工作流.github/workflows/build-native.ymlelectron-builder 打包配置package.json打包依赖与产物文档docs/packaging.mdNative 模块总览native/掌握这条流水线的核心思路后你可以把同样的构建矩阵 并行 Native 编译 草稿 Release模式复制到自己的 Electron 项目中一次推送就能稳定产出全平台、全架构的安装包。【免费下载链接】EchoMusic 一个简约的第三方酷狗概念版音乐播放器项目地址: https://gitcode.com/gh_mirrors/ec/EchoMusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
EchoMusic 多平台打包与 CI 发布完整指南：一次推送如何生成 arm64/x64 安装包
EchoMusic 多平台打包与 CI 发布完整指南一次推送如何生成 arm64/x64 安装包【免费下载链接】EchoMusic 一个简约的第三方酷狗概念版音乐播放器项目地址: https://gitcode.com/gh_mirrors/ec/EchoMusicEchoMusic 是一款基于 Electron 的简约第三方酷狗概念版音乐播放器。它的多平台打包由 GitHub Actions 构建矩阵自动完成推送版本 Tag 后六组并行任务会在 macOS、Linux、Windows 的 arm64 与 x64 环境上分别用 electron-builder 生成 DMG、NSIS 安装包和 Linux 多格式包并自动发布到 Releases。本文带你完整看懂这条 CI 发布流水线。打包全流程一图看懂Vite 打包、Rust 编译、electron-builder 组装EchoMusic 的一个安装包由三层产物拼成这也是理解整个 CI 流程的钥匙前端与主进程Vite 把渲染进程、主进程和 preload 脚本打包进dist与dist-electron见 vite.config.mts。Rust Native 模块音频播放、音频采集、媒体控制、SQLite 存储、DLNA/UPnP、AirPlay 等能力由 7 个 Rust 模块提供用 napi-rs 编译成.node文件见 native/。electron-builder 组装把前两层加上服务端依赖、图标、许可证组装成各平台安装包。⚠️ 关键点.node产物不随源码提交且x64 与 arm64 的.node文件不能互换。这就是 CI 必须为每种架构单独编译的原因。GitHub Actions 构建矩阵6 个平台目标并行出包主发布流程定义在 build.yml由两类事件触发推送v*格式的 Tag自动发版手动workflow_dispatch演练/补包构建矩阵定义在 build.yml 第 50~106 行fail-fast: false保证某个平台失败不会连累其他平台目标产物Runnerelectron-builder 参数架构EchoMusic-macOS-arm64macos-14--mac --arm64ad-hoc 签名arm64EchoMusic-macOS-x64macos-14--mac --x64ad-hoc 签名x64EchoMusic-Linux-x64ubuntu-22.04默认x64EchoMusic-Linux-arm64ubuntu-22.04-arm--linux --arm64arm64EchoMusic-Windows-x64windows-latest--win --x64x64EchoMusic-Windows-arm64windows-11-arm--win --arm64arm64每个任务内部还有几个值得学习的细节缓存三连pnpm 依赖缓存、Rust workspace 缓存、electron-builder 二进制缓存显著缩短构建时间。Native 模块并行编译用 shell 后台任务并行构建 6~7 个模块任一失败整体报错build.yml 第 154~182 行。FFmpeg 链接校验用otool -L/ldd检查播放器模块没有意外链接到系统 FFmpeg保证播放器自包含build.yml 第 184~216 行。打包后验证逐个检查.node是否真的进了resources/native/Windows 还会校验任务栏辅助程序是否随包分发build.yml 第 267~295 行。electron-builder 打包配置目标格式与附加资源一览所有打包规则集中在 package.json 的build字段几个对新手最实用的要点各平台安装格式macOS 输出dmgzipWindows 输出 NSIS 安装包Linux 一次产出AppImage、deb、pacman、rpm、tar.gz五种格式linux target。统一命名模板artifactName统一为${productName}-${version}-${os}-${arch}.${ext}保证 artifact 名可预测、易于下载脚本识别。extraResources所有.node文件、图标目录、CHANGELOG.md、LICENSE和服务端server/node_modules都通过 extraResources 配置 塞进包内Windows 额外携带echo-platform-adaptor.node和任务栏布局辅助 exe。macOS 权限声明extendInfo中声明了麦克风、音频采集、本地网络等用途描述CI 里还会用codesign验证签名与 entitlementsbuild.yml 第 297~313 行。npmRebuild: false打包时只复制现有 Native 产物、不重新编译所以架构必须提前对齐。 打包产物清单macOS 为dmg/zipWindows 为exe (nsisx64/arm64)Linux 为deb/rpm/AppImage/tar.gz等。草稿 Release让自动更新永远看不到半成品这是整条流水线里最精巧的设计。electron-updater 靠latest.ymlWindows、latest-mac.yml等元数据文件判断新版本如果 Release 里出现了安装包却缺元数据客户端会误报更新失败。release job 的处理策略先把已存在的同名 Release 设为draft隐藏上传全部 artifact 并写入从 CHANGELOG.md 自动提取的当前版本更新日志全部上传成功后才取消 draft对外转正发布版本号含-时自动标记为预发布prerelease。发布成功后流水线还会把新增 N · 优化 N · 修复 N的摘要推送到 Telegram 和 QQ 群notify job。单独编译 Native 模块Build Native Addons 手动工作流如果你不需要完整安装包只想为本地打包准备.node产物可以用独立的 build-native.yml 工作流手动触发时可分别勾选 macOS arm64/x64、Linux arm64/x64、Windows arm64/x64未勾选的目标不会启动选中的目标在独立矩阵任务中并行编译矩阵生成逻辑每个平台上传一个 artifact如EchoMusic-native-windows-arm64解压到仓库根目录即可恢复本地构建所需的目录布局该流程只上传 artifact不创建 Release也不是完整安装包。Linux 包含 6 个通用模块macOS/Windows 额外包含echo-platform-adaptor任务栏与窗口合成适配Linux 无需构建。常见打包问题速查现象原因与对策Cannot find module .../echo-*.node对应 Native 模块未编译或产物路径错误检查native/模块/模块名.node是否存在Unable to find libclangLLVM/libclang 未安装或LIBCLANG_PATH未指向库目录打包后应用启动崩溃大概率是.node架构与打包目标不一致x64 与 arm64 不能混用macOS 应用被系统拦截ad-hoc 签名限制可执行xattr -cr与codesign --force --deep --sign -重新签名详见 README自动更新检查失败macOS 发行版为 ad-hoc 签名暂不支持 Squirrel.Mac 自动安装更新需手动替换 DMG更多打包细节依赖瘦身策略、体积对比、Electron 升级回归清单可参阅 docs/packaging.md编译发布的完整说明见 README.md 编译发布章节。相关资源导航主发布工作流.github/workflows/build.ymlNative 模块专用工作流.github/workflows/build-native.ymlelectron-builder 打包配置package.json打包依赖与产物文档docs/packaging.mdNative 模块总览native/掌握这条流水线的核心思路后你可以把同样的构建矩阵 并行 Native 编译 草稿 Release模式复制到自己的 Electron 项目中一次推送就能稳定产出全平台、全架构的安装包。【免费下载链接】EchoMusic 一个简约的第三方酷狗概念版音乐播放器项目地址: https://gitcode.com/gh_mirrors/ec/EchoMusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
