EnlightenCode

基本目录结构 ​

your-project/
├── build/                  # 构建相关资源
│   ├── icon.icns          # macOS图标 (1024x1024)
│   ├── icon.ico           # Windows图标 (256x256)
│   └── icon.png           # Linux图标 (512x512)
├── src/                    # 前端源代码
├── electron/               
│   ├── main.js             # electron 主进程入口
│   └── preload.js         # electron 预加载脚本
├── public/                # 静态资源
└── package.json           # 项目配置文件

package.json 打包配置详解 ​

基础配置 ​

json
{
  "build": {
    "appId": "liuhuakawaii.icu",        // 应用程序ID,通常使用反向域名格式
    "productName": "Now",                // 产品名称,将显示在安装程序和应用程序中
    "copyright": "Copyright © 2024 Liuhuakawaii", // 版权信息
    "electronDownload": {
      "mirror": "https://npmmirror.com/mirrors/electron/" // electron下载镜像
    },
    "directories": {
      "output": "dist_electron",         // 打包输出目录
      "buildResources": "build"          // 构建资源目录
    },
    "files": [                           // 需要打包的文件
      "dist/**/*",                       // 构建后的前端文件
      "electron/**/*",                   // electron主进程文件
      "src/**/*"                         // 源代码文件
    ]
  }
}

平台特定配置 ​

json
{
  "build": {
    "mac": {
      "category": "public.app-category.productivity", // Mac App Store类别
      "icon": "build/now.ico",           // macOS应用图标
      "target": ["dmg", "zip"]           // 打包格式：dmg安装包和zip压缩包
    },
    "win": {
      "icon": "build/now.ico",           // Windows应用图标
      "target": [
        {
          "target": "nsis",              // NSIS安装包格式
          "arch": ["x64"]                // 仅支持64位架构
        },
        {
          "target": "portable"           // 便携版格式
        }
      ]
    },
    "linux": {
      "icon": "build/now.png",           // Linux应用图标
      "target": [
        "AppImage",                      // AppImage格式(类似于便携版)
        "deb"                            // Debian包格式
      ],
      "category": "Utility"              // Linux应用类别
    }
  }
}

NSIS 安装程序配置 ​

json
{
  "build": {
    "nsis": {
      "oneClick": false,                 // 是否一键安装
      "allowToChangeInstallationDirectory": true, // 允许用户修改安装目录
      "createDesktopShortcut": true,     // 创建桌面快捷方式
      "createStartMenuShortcut": true    // 创建开始菜单快捷方式
    }
  }
}
  • nsis：NSIS是一种用于创建Windows安装程序的工具，它提供了丰富的功能和灵活性。
    • oneClick：是否一键安装，默认为false，表示需要用户手动点击安装按钮。
    • allowToChangeInstallationDirectory：是否允许用户修改安装目录，默认为true，表示允许用户修改安装目录。
    • createStartMenuShortcut：是否创建开始菜单快捷方式，默认为true，表示创建开始菜单快捷方式。
    • portable：便携版格式，不需要安装，直接运行即可。

重要脚本配置 ​

json
{
  "scripts": {
    "start": "concurrently -k \"npm run start:vite\" \"npm run start:electron\"", // 并行启动vite和electron
    "start:vite": "vite",               // 启动vite开发服务器
    "start:electron": "wait-on tcp:5173 && electron .", // 等待vite启动后运行electron
    "build": "vite build && electron-builder", // 构建前端并打包electron应用
    "preview": "vite preview"           // 预览构建后的前端页面
  }
}

补充说明 ​

  1. appId: 应用程序的唯一标识符,建议使用反向域名格式
  2. productName: 决定了安装包名称和应用显示名称
  3. directories.output: 打包后的文件存放位置
  4. files: 指定哪些文件需要被打包进应用
  5. target: 不同平台的打包目标格式
    • Windows: nsis(安装包)、portable(便携版)
    • macOS: dmg(安装包)、zip(压缩包)
    • Linux: AppImage(便携版)、deb(debian包)
  6. icon: 各平台的图标要求不同
    • Windows: .ico文件
    • macOS: .icns文件
    • Linux: .png文件

打包问题 ​

下载 electron 卡住 ​

downloading url=https://github.com/electron/electron/releases/download/v33.2.1/electron-v33.2.1-win32-x64.zip size=115 MB parts=8

这个情况是正常的，electron-builder 正在下载 electron 的预编译包。解决方案：

  1. 设置 Electron 镜像：
bash
# .npmrc 文件中添加
ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
# 或者设置环境变量
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
  1. 手动下载对应文件，并放置到缓存目录：
  • Windows: %LOCALAPPDATA%\electron\Cache
  • macOS: ~/Library/Caches/electron

下载 winCodeSign 卡住 ​

• downloading url=https://github.com/electron-userland/electron-builder-binaries/releases/download/winCodeSign-2.6.0/winCodeSign-2.6.0.7z size=5.6 MB parts=1

解决方案：

  1. 设置镜像：
bash
export ELECTRON_BUILDER_BINARIES_MIRROR="https://npmmirror.com/mirrors/electron-builder-binaries/"
  1. 手动下载并放置到缓存目录：
  • Windows: %LOCALAPPDATA%\electron-builder\Cache
  • macOS: ~/.cache/electron-builder

网络代理问题 ​

Invalid configuration object. electron-builder 25.1.8 has been initialized using a configuration object that does not match the API schema.

这个错误通常是由配置文件格式问题导致。解决方案：

  1. 检查 package.json 中的 build 配置是否符合规范
  2. 设置代理：
bash
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

无法在 windows 上创建 dylib 符号链接 ​

⨯ cannot execute cause=exit status 2 out= 7-Zip (a) 21.07 (x64) : Copyright (c) 1999-2021 Igor Pavlov : 2021-12-26

解决方案：

  1. 在 package.json 中忽略 macOS 特定文件：
json
{
  "build": {
    "files": [
      "**/*",
      "!**/*.dylib"
    ]
  }
}
  1. 使用平台特定打包命令：
bash
npm run electron:build -- --win
  1. 用管理员运行，比如使用powershell（推荐）

常见打包命令 ​

bash
# 打包当前平台
npm run electron:build

# 指定平台打包
npm run electron:build -- --win
npm run electron:build -- --mac

# 打包并输出详细日志
npm run electron:build -- --debug

注意事项 ​

  1. 确保已安装对应平台的开发工具
    • Windows: Visual Studio Build Tools
    • macOS: Xcode
  2. 图标文件需符合平台要求
  3. 打包前先清理 dist 目录
  4. 建议使用 node 16+ 版本