使用PyInstaller打包Python项目过程_Python

一、为什么需要打包python程序？

当你用python开发了一个桌面应用（如gui工具、小游戏、自动化程序等），直接分享.py源码给用户显然不友好。

用户可能没有python环境，也不懂如何配置依赖库。

pyinstaller能将你的代码、资源文件、依赖库全部打包成单个.exe文件，真正做到“开箱即用”。

二、环境准备：pycharm中安装pyinstaller

打开pycharm，进入你的项目。
调出终端：点击下方菜单栏的 terminal（或快捷键 alt+f12）。
安装pyinstaller：

pip install pyinstaller -i https://pypi.tuna.tsinghua.edu.cn/simple

提示：使用清华镜像源加速下载。

三、核心命令解析：一行代码实现高级打包

以用户提供的命令为例：

pyinstaller --noconsole --add-data "d:\professioncode_py\bb\cfg.py;." --add-data "d:\professioncode_py\bb\1.jpg;." --add-data "d:\professioncode_py\bb\music.mp3;." --add-data "d:\professioncode_py\bb\harmonyos_sans_sc_black.ttf;." --onefile zhu.py

关键参数详解：

--noconsole : 运行exe时不显示控制台窗口（适用于gui程序）。
--onefile : 所有内容打包成单个exe文件，便于分发。

--add-data "源路径;目标路径" :

源路径：资源文件的绝对或相对路径。
目标路径：在exe中的存储位置，.表示与exe同级目录。
注意：windows中使用分号;，linux/macos使用冒号:。

路径处理技巧：

推荐使用相对路径避免绝对路径依赖：

--add-data "assets/1.jpg;assets"

特殊字符路径需加引号，如包含空格时："c:/my project/image.png;."

四、资源文件在代码中的正确引用方式

打包后资源文件会被解压到临时目录，直接使用原始路径将导致错误！需通过以下方法获取正确路径：

import sys
import os

def resource_path(relative_path):
    """ 获取资源的绝对路径 """
    if hasattr(sys, '_meipass'):
        base_path = sys._meipass
    else:
        base_path = os.path.abspath(".")
    return os.path.join(base_path, relative_path)

# 示例：加载图片
img_path = resource_path("1.jpg")
image = pygame.image.load(img_path)

# 示例：加载字体
font_path = resource_path("harmonyos_sans_sc_black.ttf")
font = pygame.font.font(font_path, 24)

五、实战案例：打包一个带图片、音乐、字体的游戏

假设项目结构如下：

project/
├── src/
│   ├── main.py
│   └── config.py
├── assets/
│   ├── bg.jpg
│   ├── bgm.mp3
│   └── font.ttf
└── spec/

打包命令：

pyinstaller --noconsole --add-data "assets/*;assets" --onefile src/main.py

代码调整：

# config.py中读取资源
cfg_music = resource_path("assets/bgm.mp3")
cfg_font = resource_path("assets/font.ttf")

六、常见问题与解决方案

exe文件过大？

使用虚拟环境安装仅需依赖库。
使用upx压缩（下载upx，添加--upx-dir参数）。

运行闪退？

命令行中运行exe查看错误信息（去掉--noconsole）。
检查资源路径是否正确。

杀毒软件误报？

使用代码签名证书签名exe。
提交到virustotal白名单。

跨平台兼容性？

linux/macos打包需在对应系统中执行命令。
注意文件路径大小写敏感问题。

七、进阶技巧：使用spec文件定制打包流程

对于复杂项目，可生成.spec文件进行配置：

pyinstaller zhu.spec

示例spec文件：

a = analysis(
    ['zhu.py'],
    pathex=['d:/project'],
    binaries=[],
    datas=[
        ('assets/*.jpg', 'assets'),
        ('fonts/*.ttf', 'fonts')
    ],
    hiddenimports=[],
    ...
)