项目打包教程

概述

UnifyPy是一个强大的自动化解决方案，能将Python项目打包成跨平台的独立可执行文件和安装程序。小智客户端已配置了相应的打包配置文件，本教程将指导您如何使用UnifyPy进行打包。

准备工作

1. 安装py-xiaozhi项目依赖

首先，确保您已安装py-xiaozhi项目的所有依赖：

bash

# Windows
pip install -r requirements.txt

# macOS
pip install -r requirements_mac.txt

# Linux
pip install -r requirements.txt

2. 克隆UnifyPy仓库

bash

git clone https://github.com/huangjunsen0406/UnifyPy.git

3. 安装平台特定工具

Windows平台

安装Inno Setup（用于创建安装程序）
安装后，在build.json中配置Inno Setup路径，或设置环境变量INNO_SETUP_PATH
把UnifyPy下的ChineseSimplified.isl复制到inno setup安装目录下language里（windows）

macOS平台

安装create-dmg（用于创建DMG镜像）：
bash
```
brew install create-dmg
```

Linux平台

根据需要的打包格式，安装相应的工具：

bash

# DEB格式(Debian/Ubuntu)
sudo apt-get install dpkg-dev

# RPM格式(Fedora/CentOS)
sudo dnf install rpm-build

# AppImage格式(通用Linux)
wget -c https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
chmod a+x appimagetool-x86_64.AppImage
sudo mv appimagetool-x86_64.AppImage /usr/local/bin/appimagetool

打包配置详解

小智客户端已经提供了预配置的build.json文件，以下是各配置项的详细说明：

基本配置

json

{
    "name": "xiaozhi",                  // 应用程序名称，将用于可执行文件和安装程序名称
    "version": "1.0.0",                 // 应用程序版本号
    "publisher": "Junsen",              // 发布者名称
    "entry": "main.py",                 // 程序入口文件
    "icon": "assets/xiaozhi_icon.ico",  // 应用图标路径
    "hooks": "hooks",                   // PyInstaller钩子目录
    "onefile": false,                   // 是否生成单文件模式的可执行文件
    
    // PyInstaller通用参数，适用于所有平台
    "additional_pyinstaller_args": "--add-data assets;assets --add-data libs;libs --add-data src;src --add-data models;models --hidden-import=PyQt5",
    
    // Inno Setup路径（Windows平台需要）
    "inno_setup_path": "E:\\application\\Inno Setup 6\\ISCC.exe",
    
    // 其他配置...
}

注意：JSON文件不支持注释，上述代码中的注释仅用于说明，实际配置文件中不应包含注释。

平台特定配置

Windows平台配置

json

"windows": {
    "format": "exe",                  // 输出格式
    "additional_pyinstaller_args": "--add-data assets;assets --add-data libs;libs --add-data src;src --add-data models;models --hidden-import=PyQt5 --noconsole",
    "desktop_entry": true,            // 是否创建桌面快捷方式
    "installer_options": {
        "languages": ["ChineseSimplified", "English"],  // 安装程序支持的语言
        "license_file": "LICENSE",                      // 许可证文件
        "readme_file": "README.md",                     // 自述文件
        "create_desktop_icon": true,                    // 是否创建桌面图标
        "allow_run_after_install": true                 // 安装后是否允许立即运行
    }
}

Linux平台配置

json

"linux": {
    "format": "deb",                  // 输出格式，可选值：deb, rpm, appimage
    "desktop_entry": true,            // 是否创建桌面快捷方式
    "categories": "Utility;Development;",  // 应用程序类别
    "description": "小智Ai客户端",          // 应用描述
    "requires": "libc6,libgtk-3-0,libx11-6,libopenblas-dev",  // 依赖项
    "additional_pyinstaller_args": "--add-data assets:assets --add-data libs:libs --add-data src:src --add-data models:models --hidden-import=PyQt5"
}

macOS平台配置

json

"macos": {
    "format": "app",                  // 输出格式，可选值：app, dmg
    "additional_pyinstaller_args": "--add-data assets:assets --add-data libs:libs --add-data src:src --add-data models:models --hidden-import=PyQt5 --windowed",
    "app_bundle_name": "XiaoZhi.app", // 应用包名称
    "bundle_identifier": "com.junsen.xiaozhi",  // 应用标识符
    "sign_bundle": false,             // 是否签名应用包
    "create_dmg": true,               // 是否创建DMG镜像
    "installer_options": {
        "license_file": "LICENSE",    // 许可证文件
        "readme_file": "README.md"    // 自述文件
    }
}

其他重要配置项

json

"build_installer": true  // 是否构建安装程序，设为false只生成可执行文件

自定义安装程序模板

当打包Windows安装程序时，UnifyPy使用setup.iss.template文件作为Inno Setup的脚本模板。需要注意的是，模板中的AppId需要更换为自己的唯一标识符：

[Setup]
; 应用程序信息
AppId={{05DBB87C-AE34-4F2F-AEC5-3CD2AFE9DC90}}  ; 需要替换为你自己生成的GUID

重要：请勿直接使用示例中的AppId，这可能导致与其他应用程序冲突。您可以使用在线GUID生成工具（如Online GUID Generator）来生成自己的唯一标识符。

执行打包

基本打包命令

建议UnifyPy放在和py-xiaozhi项目同级目录下, 直接 python ../UnifyPy/main.py. --config build.json 即可

bash

# 导航到UnifyPy目录
cd 到当前py-xiaozhi项目目录下

# 执行打包命令
# UnifyPy_路径/main.py 是UnifyPy的项目路径
# . 表示当前项目目录
# --config build.json 表示使用当前目录下的build.json配置文件
python UnifyPy_路径/main.py . --config build.json

针对不同平台的打包命令

Windows平台

bash

python C:\路径\到\UnifyPy\main.py . --config build.json

macOS平台

bash

python /路径/到/UnifyPy/main.py . --config build.json

Linux平台

Linux平台下打包有两种主要格式：DEB和AppImage。根据需要选择其中一种格式。

DEB格式打包（适用于Debian/Ubuntu系统）

准备环境

bash

# 更新系统并安装必要的依赖
sudo apt update
sudo apt install -y build-essential python3-dev python3-pip python3-setuptools libopenblas-dev liblapack-dev gfortran patchelf autoconf automake libtool cmake libssl-dev libatlas-base-dev

执行打包
确保build.json中linux.format设置为"deb"，然后执行：
bash
```
python3 /路径/到/UnifyPy/main.py . --config build.json
```

AppImage格式打包（适用于通用Linux系统）

AppImage格式需要特别注意NumPy库的编译，以下是完整步骤：

升级pip和基本构建工具

bash

python -m pip install --upgrade pip setuptools wheel

安装必要的系统依赖

bash

sudo apt update
sudo apt install -y build-essential python3-dev python3-pip python3-setuptools libopenblas-dev liblapack-dev gfortran patchelf autoconf automake libtool cmake libssl-dev libatlas-base-dev

安装Meson和Ninja构建系统

bash

pip install meson ninja
sudo apt install -y meson ninja-build

准备NumPy编译环境

bash

# 卸载现有NumPy
pip uninstall numpy -y

# 设置环境变量
export BLAS=openblas
export LAPACK=openblas
export NPY_NUM_BUILD_JOBS=$(nproc)  # 使用所有CPU核心加速编译

# 从源码编译安装NumPy
pip install numpy==1.26.4 --no-binary :all:

执行打包
确保build.json中linux.format设置为"appimage"，然后执行：
bash
```
python3 /路径/到/UnifyPy/main.py . --config build.json
```

打包输出

成功打包后，将在项目根目录下的dist文件夹中找到打包的应用程序：

Windows:
- 可执行文件(.exe)位于dist/xiaozhi目录
- 安装程序位于dist/installer目录，命名为xiaozhi-1.0.0-setup.exe
macOS:
- 应用程序包(.app)位于dist/xiaozhi目录
- 磁盘镜像(.dmg)位于dist/installer目录，命名为xiaozhi-1.0.0.dmg
Linux:
- 可执行文件位于dist/xiaozhi目录
- 安装包位于dist/installer目录：
  - DEB格式：xiaozhi-1.0.0.deb
  - RPM格式：xiaozhi-1.0.0.rpm
  - AppImage格式：xiaozhi-1.0.0.AppImage

高级配置选项

PyInstaller参数

在additional_pyinstaller_args字段中，您可以添加任何PyInstaller支持的参数。以下是一些常用参数：

--noconsole: 不显示控制台窗口（仅适用于图形界面程序）
--windowed: 等同于--noconsole
--hidden-import=MODULE: 添加隐式导入的模块
--add-data SRC;DEST: 添加数据文件（Windows平台使用分号分隔）
--add-data SRC:DEST: 添加数据文件（macOS/Linux平台使用冒号分隔）
--icon=FILE.ico: 设置应用程序图标

处理特殊依赖

某些Python库可能需要特殊处理才能正确打包，可以通过以下方式解决：

使用钩子文件：在hooks目录中创建自定义钩子，处理特殊导入情况
添加隐式导入：使用--hidden-import参数显式包含隐式导入的模块
添加数据文件：使用--add-data参数包含程序运行所需的数据文件

常见问题及解决方案

Windows平台常见问题

找不到Inno Setup
解决方案：确保已安装Inno Setup，并在build.json中正确配置路径，或设置环境变量INNO_SETUP_PATH
缺少隐式导入的模块
解决方案：在additional_pyinstaller_args中添加--hidden-import=模块名称
打包后无法找到资源文件
解决方案：确保使用相对路径访问资源文件，并使用--add-data参数正确包含资源文件

macOS平台常见问题

创建DMG出错
解决方案：确保已安装create-dmg工具，并有正确的权限
签名问题
解决方案：如果需要签名，在配置文件中启用sign_bundle并提供有效的开发者身份
动态库加载问题
解决方案：确保代码中正确处理库路径，特别是使用sys._MEIPASS路径

Linux平台常见问题

缺少依赖库
解决方案：在Linux配置中的requires字段中添加所需的系统依赖
打包工具不可用
解决方案：确保已安装相应格式的打包工具(dpkg-dev, rpmbuild, appimagetool)
权限问题
解决方案：确保脚本有正确的执行权限，对某些资源目录可能需要特别处理
NumPy编译失败
解决方案：确保已安装所有必要的开发库，特别是OpenBLAS、LAPACK和Fortran编译器
找不到appimagetool
解决方案：确保已正确安装并设置appimagetool的可执行权限

最佳实践

清理项目：打包前移除临时文件、缓存和不必要的大型文件
测试依赖：确保所有依赖都正确安装并可以导入
确认文件路径：检查代码中的文件路径是否使用相对路径或资源路径
验证配置：确保build.json中的配置与您的环境一致
多平台测试：如果条件允许，在多个平台上测试打包的应用程序
保存配置：为不同的打包场景保存不同版本的配置文件，方便复用
版本管理：每次发布前更新版本号，保持版本一致性

项目打包教程 ​

概述 ​

准备工作 ​

1. 安装py-xiaozhi项目依赖 ​

2. 克隆UnifyPy仓库 ​

3. 安装平台特定工具 ​

Windows平台 ​

macOS平台 ​

Linux平台 ​

打包配置详解 ​

基本配置 ​

平台特定配置 ​

Windows平台配置 ​

Linux平台配置 ​

macOS平台配置 ​

其他重要配置项 ​

自定义安装程序模板 ​

执行打包 ​

基本打包命令 ​

针对不同平台的打包命令 ​

Windows平台 ​

macOS平台 ​

Linux平台 ​

DEB格式打包（适用于Debian/Ubuntu系统） ​

AppImage格式打包（适用于通用Linux系统） ​

打包输出 ​

高级配置选项 ​

PyInstaller参数 ​

处理特殊依赖 ​

常见问题及解决方案 ​

Windows平台常见问题 ​

macOS平台常见问题 ​

Linux平台常见问题 ​

最佳实践 ​

项目打包教程

概述

准备工作

1. 安装py-xiaozhi项目依赖

2. 克隆UnifyPy仓库

3. 安装平台特定工具

Windows平台

macOS平台

Linux平台

打包配置详解

基本配置

平台特定配置

Windows平台配置

Linux平台配置

macOS平台配置

其他重要配置项

自定义安装程序模板

执行打包

基本打包命令

针对不同平台的打包命令

Windows平台

macOS平台

Linux平台

DEB格式打包（适用于Debian/Ubuntu系统）

AppImage格式打包（适用于通用Linux系统）

打包输出

高级配置选项

PyInstaller参数

处理特殊依赖

常见问题及解决方案

Windows平台常见问题

macOS平台常见问题

Linux平台常见问题

最佳实践