PY-XIAOZHI

Appearance

项目打包教程 ​

概述 ​

UnifyPy 2.0 是一个跨平台Python应用打包工具，支持将Python项目打包为Windows (EXE)、macOS (DMG)、Linux (DEB)平台的原生安装包。

核心特性：交互式配置向导、智能路径处理、自动权限管理、并行构建、回滚系统。

📚 完整文档：UnifyPy GitHub仓库

环境准备 ​

1. 安装项目依赖 ​

bash
# 进入项目目录
cd /path/to/py-xiaozhi

# 安装项目依赖
pip install -r requirements.txt        # Windows/Linux
pip install -r requirements_mac.txt    # macOS

2. 安装UnifyPy ​

bash
pip install unifypy

说明：UnifyPy使用PyInstaller打包，需要访问当前环境中的所有Python包。确保UnifyPy和项目依赖在同一环境中安装。

3. 平台特定工具 ​

Windows平台 ​

安装 Inno Setup（用于创建安装程序）

  • 安装后，在build.json中配置路径，或设置环境变量 INNO_SETUP_PATH

macOS平台 ​

  • 无需额外安装（UnifyPy内置create-dmg工具）

Linux平台 ​

安装打包工具：

bash
# DEB格式打包工具
sudo apt-get install dpkg-dev fakeroot

安装编译环境（重要）：

bash
# 安装开发工具和库（NumPy等依赖需要）
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

# 安装构建系统
pip install meson ninja
sudo apt install -y meson ninja-build

NumPy编译环境配置：

bash
# 设置环境变量
export BLAS=openblas
export LAPACK=openblas
export NPY_NUM_BUILD_JOBS=$(nproc)

# 验证NumPy可用
python -c "import numpy; print('NumPy version:', numpy.__version__)"

提示：建议使用conda环境，可避免大部分编译问题：

bash
conda create -n build_env python=3.9
conda activate build_env
conda install numpy scipy openblas-devel
pip install unifypy

快速开始 ​

方式一：交互式向导（推荐首次使用） ​

bash
# 在项目目录启动配置向导
cd /path/to/py-xiaozhi
unifypy . --init

向导会引导你完成：

  1. 基础信息配置（名称、版本、入口文件）
  2. 目标平台选择（Windows/macOS/Linux）
  3. PyInstaller配置（单文件/窗口模式、数据目录）
  4. 平台特定配置（权限、图标、安装选项）
  5. 自动生成 build.json 并可选择立即构建

方式二：使用现有配置 ​

项目已包含预配置的 build.json，直接打包：

bash
# 基本打包
unifypy . --config build.json

# 清理重新构建
unifypy . --config build.json --clean

# 详细输出（推荐）
unifypy . --config build.json --verbose

# 只生成可执行文件
unifypy . --config build.json --skip-installer

# 并行构建多种格式
unifypy . --config build.json --parallel --max-workers 4

各平台打包命令 ​

Windows ​

bash
unifypy . --config build.json

输出：

  • 可执行文件：dist/xiaozhi/
  • 安装程序：dist/installer/xiaozhi-1.0.0-setup.exe

macOS ​

bash
# 开发模式（自动配置权限）
unifypy . --config build.json --development

# 生产模式
unifypy . --config build.json

输出：

  • 应用程序包：dist/xiaozhi/XiaoZhi.app
  • 磁盘镜像：dist/installer/xiaozhi-1.0.0.dmg

Linux ​

bash
unifypy . --config build.json

输出：

  • 可执行文件：dist/xiaozhi/
  • DEB安装包：dist/installer/xiaozhi-1.0.0.deb

Linux平台特殊说明 ​

NumPy编译问题 ​

症状：出现编译错误、缺少BLAS/LAPACK库等

解决方案：

bash
# 方案1: 检查并安装缺失的开发库
sudo apt install -y libopenblas-dev liblapack-dev gfortran

# 方案2: 使用预编译wheel包（推荐）
pip install numpy --force-reinstall

# 方案3: 设置环境变量后重装
export BLAS=openblas
export LAPACK=openblas
export NPY_NUM_BUILD_JOBS=4
pip install numpy --no-cache-dir

# 方案4: 使用conda环境（最稳定）
conda install numpy scipy openblas-devel

依赖兼容性 ​

打包后的程序在其他Linux系统上无法运行？

解决方案：在较老的Linux发行版上构建，推荐使用：

  • Ubuntu 18.04 LTS 或 20.04 LTS
  • CentOS 7

或使用静态链接：

bash
pip install staticx

常见问题 ​

Q1: 首次使用不知道如何配置？ ​

bash
unifypy . --init  # 使用交互式向导

Q2: 打包失败？ ​

bash
# 清理后重试，启用详细输出
unifypy . --config build.json --clean --verbose

Q3: macOS权限配置问题？ ​

bash
# 使用开发模式自动生成权限文件
unifypy . --config build.json --development --verbose

Q4: 依赖冲突？ ​

bash
# 创建统一环境
conda create -n packaging python=3.9
conda activate packaging
pip install unifypy
pip install -r requirements.txt

Q5: 配置文件路径找不到？ ​

UnifyPy 2.0使用智能路径处理，配置文件中的相对路径会自动解析为相对于项目目录的绝对路径。

示例：

json
{
  "icon": "assets/icon.png"  // 自动解析为 /path/to/project/assets/icon.png
}

高级功能 ​

回滚系统 ​

bash
# 列出可用回滚会话
unifypy . --list-rollback

# 回滚到指定会话
unifypy . --rollback SESSION_ID

并行构建 ​

bash
# 多格式并行构建
unifypy . --config build.json --parallel --max-workers 4

macOS权限自动管理 ​

UnifyPy自动生成entitlements.plist和更新Info.plist：

bash
# 开发模式（包含调试权限）
unifypy . --config build.json --development

# 生产模式（仅必要权限）
unifypy . --config build.json --production

更多信息 ​

最佳实践 ​

  1. 环境管理：使用conda创建专用打包环境
  2. 首次使用：使用 --init 向导快速生成配置
  3. 调试构建：始终使用 --verbose 参数
  4. 清理构建：定期使用 --clean 确保构建干净
  5. Linux打包：在Ubuntu 18.04/20.04上构建以确保兼容性
  6. macOS打包：开发阶段使用 --development 模式