Skip to content

BUILD.md

Latest commit

 

History

History
419 lines (307 loc) · 8.74 KB

BUILD.md

File metadata and controls

419 lines (307 loc) · 8.74 KB
Raw

打包说明文档

本文档详细说明如何将二维码生成器打包为桌面应用。

环境要求

  • Node.js 16.x 或更高版本
  • npm 或 yarn
  • （可选）Docker - 用于跨平台打包

打包命令

基础命令

# 安装依赖
npm install

# 打包当前平台（根据操作系统自动选择）
npm run dist

# 打包 Mac 版本
npm run build:mac

# 打包 Windows 版本
npm run build:win

# 打包 Linux 版本
npm run build:linux

# 打包所有平台
npm run build:all

平台特定说明

Mac 平台

打包命令

npm run build:mac

输出文件

  • electron-dist/二维码生成器-1.0.0.dmg - DMG 安装包
  • electron-dist/二维码生成器-1.0.0-mac.zip - ZIP 压缩包

安装方式

  1. 下载 .dmg 文件
  2. 双击打开，将应用拖拽到 Applications 文件夹
  3. 在 Launchpad 或 Applications 中找到应用并打开

签名和公证（可选）

如需分发到 Mac App Store 或进行公证，需要配置签名：

// package.json
{
  "build": {
    "mac": {
      "identity": "Developer ID Application: Your Name",
      "hardenedRuntime": true,
      "gatekeeperAssess": false,
      "entitlements": "build/entitlements.mac.plist",
      "entitlementsInherit": "build/entitlements.mac.plist"
    }
  }
}

Windows 平台

打包命令

npm run build:win

输出文件

  • electron-dist/二维码生成器 Setup 1.0.0.exe - NSIS 安装程序
  • electron-dist/二维码生成器-1.0.0-win.zip - ZIP 压缩包

安装方式

  1. 下载 .exe 文件
  2. 双击运行安装程序
  3. 按照提示完成安装
  4. 在开始菜单或桌面找到应用图标

NSIS 配置

当前配置：

  • 允许用户选择安装目录
  • 创建桌面快捷方式
  • 创建开始菜单快捷方式

Linux 平台

打包命令

# 同时打包 AppImage + deb + rpm（需在 Linux 主机或已安装相应工具链）
npm run build:linux

# 单独打包 deb（Debian/Ubuntu）
npm run build:deb

# 单独打包 rpm（RedHat/Fedora，需本地 rpmbuild）
npm run build:rpm

输出文件

  • electron-dist/qrcodegen_1.0.0_amd64.deb - Debian/Ubuntu 包 (x64)
  • electron-dist/qrcodegen_1.0.0_arm64.deb - Debian/Ubuntu 包 (arm64)
  • electron-dist/qrcodegen-1.0.0.x86_64.rpm - RedHat/Fedora 包 (x64)
  • electron-dist/qrcodegen-1.0.0.aarch64.rpm - RedHat/Fedora 包 (arm64)
  • electron-dist/QrCodeGen-1.0.0.AppImage - AppImage 通用格式

安装方式

AppImage（推荐，通用）：

chmod +x QrCodeGen-1.0.0.AppImage
./QrCodeGen-1.0.0.AppImage

Debian/Ubuntu：

sudo dpkg -i qrcodegen_1.0.0_amd64.deb
# 或
sudo apt install ./qrcodegen_1.0.0_amd64.deb

RedHat/Fedora：

sudo rpm -i qrcodegen-1.0.0.x86_64.rpm

Linux Docker 打包（推荐跨平台方案）

在 macOS / Windows / 任意 Linux 上使用 Docker 容器打包 Linux 包， 无需本地安装 dpkg-deb / rpmbuild 工具链。脚本会自动检测 Docker， 若未安装则按平台自动安装（使用国内镜像源加速）。

支持的格式

格式 Docker 支持 说明
deb ✅ Debian/Ubuntu 包，完全支持 Docker
AppImage ✅ 通用 Linux 格式，完全支持 Docker
rpm ❌ electron-builder 限制，必须本地 rpmbuild

打包命令

# 打包 deb（默认当前架构）
npm run build:linux:docker:deb

# 打包 deb x64
npm run build:linux:docker:deb:x64

# 打包 deb arm64
npm run build:linux:docker:deb:arm64

# 同时打包 deb x64 + arm64
npm run build:linux:docker:deb:all

# 打包 AppImage
npm run build:linux:docker:appimage

# 同时打包 AppImage x64 + arm64
npm run build:linux:docker:appimage:all

# 默认打包 deb（同 build:linux:docker:deb）
npm run build:linux:docker

直接运行脚本

也可以直接调用脚本，更灵活：

./build-docker-linux.sh                  # 默认打包 deb
./build-docker-linux.sh deb              # 打包 deb
./build-docker-linux.sh deb x64          # 打包 deb x64
./build-docker-linux.sh deb arm64        # 打包 deb arm64
./build-docker-linux.sh deb all          # 打包 deb x64 + arm64
./build-docker-linux.sh appimage         # 打包 AppImage
./build-docker-linux.sh appimage all     # 打包 AppImage x64 + arm64
./build-docker-linux.sh --help           # 查看帮助

Docker 自动安装

脚本检测到未安装 Docker 时会按操作系统自动安装（国内源）：

  • macOS: 通过 Homebrew cask 安装 Docker Desktop
  • Debian/Ubuntu: 使用阿里云 Docker CE 源 (mirrors.aliyun.com)
  • Fedora/CentOS/RHEL: 使用阿里云 Docker CE 源
  • Arch/Manjaro: 通过 pacman 安装

安装后会自动启动 Docker 服务并将当前用户加入 docker 组（Linux）。

关于 rpm 的说明

electron-builder 打 rpm 时不支持 Docker 模式，需要本地 rpmbuild。 如需 rpm 包，请使用以下方式之一：

# 方式 1: macOS 本地安装 rpm 工具链
brew install rpm
npm run build:rpm

# 方式 2: 在 Linux 主机执行
npm run build:rpm

# 方式 3: 在 GitHub Actions 等 Linux CI 上执行

跨平台打包

使用 Docker

Docker 是最简单的跨平台打包方式。

安装 Docker

  • Mac: 下载 Docker Desktop
  • Windows: 下载 Docker Desktop
  • Linux: 使用包管理器安装

打包所有平台

npm run build:all

electron-builder 会自动使用 Docker 容器打包其他平台。

手动跨平台打包

Mac 上打包 Windows

需要安装 Wine 和 mono：

# macOS (使用 Homebrew)
brew install wine-stable mono

# 然后执行
npm run build:win

Windows 上打包 Mac

需要安装 macOS 虚拟机或使用云服务（如 MacStadium）。

Linux 上打包其他平台

# 打包 Windows
sudo apt-get install wine mono
npm run build:win

# 打包 Mac
# 需要安装 macOS SDK 或使用虚拟机

打包配置

package.json 配置

{
  "build": {
    "appId": "com.qrcode.generator",
    "productName": "二维码生成器",
    "copyright": "Copyright © 2026",
    "directories": {
      "output": "electron-dist"
    },
    "files": [
      "main.js",
      "index.html",
      "lib/**/*",
      "templates/**/*"
    ],
    "icon": "icon.png",
    "mac": {
      "target": ["dmg", "zip"],
      "category": "public.app-category.productivity"
    },
    "win": {
      "target": ["nsis", "zip"]
    },
    "linux": {
      "target": ["AppImage", "deb", "rpm"],
      "category": "Utility"
    },
    "nsis": {
      "oneClick": false,
      "allowToChangeInstallationDirectory": true,
      "createDesktopShortcut": true,
      "createStartMenuShortcut": true
    }
  }
}

图标要求

  • PNG: 512x512 像素（用于 Linux 和自动生成其他格式）
  • ICNS: Mac 专用格式（electron-builder 会自动从 PNG 生成）
  • ICO: Windows 专用格式（electron-builder 会自动从 PNG 生成）

当前项目使用 icon.png 作为源文件，electron-builder 会自动生成其他格式。

常见问题

打包失败

  1. 依赖未安装

    npm install

  2. 权限问题

    • Linux/Mac: 使用 sudo 或检查文件权限
    • Windows: 以管理员身份运行终端

  3. 磁盘空间不足

    • 确保至少有 2GB 可用空间

  4. 网络问题

    • 检查网络连接
    • 配置 npm 镜像源

打包文件过大

如果打包文件过大，可以：

  1. 检查是否包含了不必要的文件
  2. 使用 asar 压缩（默认启用）
  3. 排除开发依赖
{
  "build": {
    "asar": true,
    "asarUnpack": [
      "lib/**/*"
    ]
  }
}

应用无法启动

  1. Mac: 检查 Gatekeeper 设置

    xattr -cr 二维码生成器.app

  2. Windows: 检查杀毒软件是否拦截

  3. Linux: 检查文件权限

    chmod +x 二维码生成器-1.0.0.AppImage

分发

内部分发

直接分享打包好的安装文件：

  • Mac: 分享 .dmg 或 .zip
  • Windows: 分享 .exe 或 .zip
  • Linux: 分享 .AppImage

公开发布

  1. GitHub Releases

    • 上传打包文件到 Releases
    • 提供下载链接

  2. 应用商店

    • Mac: Mac App Store
    • Windows: Microsoft Store
    • Linux: Snap Store, Flathub

  3. 自建下载站

    • 搭建下载页面
    • 提供各平台版本

更新维护

版本号更新

修改 package.json 中的版本号：

{
  "version": "1.0.1"
}

自动更新（可选）

可以集成 electron-updater 实现自动更新：

npm install electron-updater

配置更新服务器和更新逻辑。

技术支持

如遇到打包问题，请参考：