3分钟掌握跨平台打包：MusicFreeDesktop全平台安装程序构建指南

准备工作

环境要求

确保系统已安装Node.js和npm，推荐使用Node.js 16.x或更高版本。克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/mu/MusicFreeDesktop
cd MusicFreeDesktop

安装项目依赖：

npm install

项目使用Electron Forge作为打包工具，相关配置可在package.json中查看。核心打包脚本定义如下：

"scripts": {
  "start": "electron-forge start",
  "package": "electron-forge package",
  "make": "electron-forge make",
  "publish": "electron-forge publish"
}

项目打包配置

主要打包配置文件为forge.config.ts，该文件定义了各平台的打包参数、图标设置和资源包含等信息。

打包流程

1. 基础打包命令

执行以下命令生成未签名的应用程序包：

npm run package

该命令会根据当前操作系统生成对应平台的包，输出目录为out/MusicFree-{platform}-{arch}。

2. 生成安装程序

执行以下命令生成各平台的安装程序：

npm run make

打包配置在forge.config.ts的makers数组中定义，目前支持的平台包括：

• Windows：通过MakerSquirrel生成exe安装包（当前配置已注释）
• macOS：通过MakerDMG生成dmg镜像
• Linux：通过MakerDeb生成deb安装包

3. 平台特定配置

Windows平台

Windows平台打包需要设置图标和安装程序信息，相关配置如下：

// forge.config.ts 中 Windows 配置示例
new MakerSquirrel({
  exe: "MusicFree",
  setupIcon: path.resolve(__dirname, "res/logo.ico"),
  setupMsi: "MusicFreeInstaller",
})

macOS平台

macOS平台配置了应用Bundle ID和DMG格式：

// forge.config.ts 中 macOS 配置
packagerConfig: {
  appBundleId: "fun.upup.musicfree",
  // 其他配置...
}
makers: [
  new MakerDMG({ format: "ULFO" }, ["darwin"]),
]

Linux平台

Linux平台通过Debian包格式分发：

// forge.config.ts 中 Linux 配置
new MakerDeb({
  options: {
    name: "MusicFree",
    bin: "MusicFree",
    mimeType: ["x-scheme-handler/musicfree"],
  },
})

自定义打包设置

图标配置

应用图标通过forge.config.ts中的icon字段指定：

packagerConfig: {
  icon: path.resolve(__dirname, "res/logo"),
}

项目图标文件位于res/目录下，包含多种格式以适应不同平台：

• res/logo.ico：Windows图标
• res/logo.icns：macOS图标
• res/logo.png：通用图标

资源文件包含

需要打包到应用中的资源文件通过extraResource配置指定：

packagerConfig: {
  extraResource: [path.resolve(__dirname, "res")],
}

这确保了res/目录下的所有资源文件（如图片、语言文件等）都被正确包含到最终的安装程序中。

协议注册

应用注册了自定义URL协议musicfree://，允许从浏览器启动应用，相关配置如下：

packagerConfig: {
  protocols: [
    {
      name: "MusicFree",
      schemes: ["musicfree"],
    },
  ],
}

故障排除

常见问题解决

依赖问题

如果遇到原生模块编译问题，尝试重新构建依赖：

npm rebuild

资源缺失

确保所有必要的资源文件都已正确包含在res/目录中，特别是应用图标和语言文件。

平台兼容性

某些模块可能需要针对特定平台进行额外配置，可在webpack.main.config.ts和webpack.renderer.config.ts中进行Webpack配置调整。

打包结果示例

成功打包后，输出文件位于out/make目录下，不同平台的输出结果如下：

• Windows：out/make/squirrel.windows/x64/MusicFreeSetup.exe
• macOS：out/make/dmg/x64/MusicFree-{version}.dmg
• Linux：out/make/deb/x64/musicfree_{version}_amd64.deb

应用主界面截图：

总结

本教程介绍了MusicFreeDesktop项目的打包流程，包括环境准备、基础打包命令、平台特定配置和自定义设置。通过forge.config.ts和package.json两个核心配置文件，可以灵活控制打包过程，生成适合不同操作系统的安装程序。

更多详细信息可参考项目README.md和官方文档。