PyInstaller 打包指令教程

---

1. 写在前面

通常，在用 Python 编写完一个脚本后，需要将它部署并集成到一个更大的项目中。常见的集成方式有以下几种：

1. 使用 PyInstaller 打包。
2. 使用 Docker 打包。
3. 将 Python 嵌入到 C++ 代码中，并封装成类。
4. 将 Python 代码转换为 C++ 代码。

本文介绍其中一种方式——使用 PyInstaller 打包。通过 PyInstaller，可以将 Python 脚本打包成 .exe 文件（适用于 Windows）或适用于 macOS 和 Linux 的可执行文件，用户无需安装 Python 或任何相关依赖，便能直接运行程序。

主要优势：

• 将 Python 脚本打包成独立可执行文件，方便分发和运行。
• 支持单文件打包、图标定制、以及额外文件的捆绑。
• 可选隐藏控制台窗口，适合图形化应用（GUI）程序。

适用场景：

• 发布桌面工具或命令行程序。
• 让没有 Python 环境的用户也能使用你的工具。
• 分享自包含的 Python 项目，确保目标机器能够顺利运行。

---

2. 打包指令解析与参数详解

参数名	描述	示例	类型	必须	默认值
--onefile	将所有依赖文件打包为单个可执行文件。	pyinstaller --onefile example.py	bool	否	False
--noconsole	隐藏控制台窗口（适用于 GUI 应用）。	pyinstaller --noconsole gui_app.py	bool	否	False
--name	指定生成的可执行文件名称。	pyinstaller --name=my_app example.py	str	否	源文件名（无扩展）
--icon	设置可执行文件的图标（需提供 .ico 文件）。	pyinstaller --icon=app_icon.ico example.py	str	否	None
--add-data	捆绑额外文件（如配置文件、静态资源等）。	pyinstaller --add-data "config.yaml;." example.py	str	否	None
--clean	清理之前的构建缓存，强制重新打包。	pyinstaller --clean example.py	bool	否	False
--hidden-import	手动添加隐藏的依赖模块（通常是自动检测遗漏的依赖）。	pyinstaller --hidden-import=requests example.py	list	否	自动检测

---

3. 基础步骤

1. 安装 PyInstaller

在终端（或命令行）中运行以下命令，安装 PyInstaller：

pip install pyinstaller

2. 使用基础命令进行打包

假设你有一个 Python 脚本 example_script.py，使用下面的命令将其打包为一个独立的可执行文件：

pyinstaller --onefile example_script.py

• 该命令会将所有依赖项和代码打包成一个单一的 .exe 文件。
• 打包后，可以在 dist 目录下找到生成的可执行文件。

---

4. 常见的用法示例

示例 1：基础打包

将 example_script.py 打包为一个单文件可执行程序：

pyinstaller --onefile example_script.py

示例 2：自定义名称和图标

将输出文件命名为 my_program.exe，并指定图标文件为 app_icon.ico：

pyinstaller --onefile --name=my_program --icon=app_icon.ico example_script.py

示例 3：捆绑额外文件

将配置文件 config.yaml 一起捆绑进可执行文件：

pyinstaller --onefile --add-data "config.yaml;." example_script.py

注意：在 Windows 系统中，路径分隔符用分号 ;，而在 macOS/Linux 中使用冒号 :。

示例 4：解决缺失依赖问题

如果在运行时遇到某个模块丢失的错误，可以通过 --hidden-import 指定手动引入依赖：

pyinstaller --onefile --hidden-import=requests example_script.py

示例 5：隐藏控制台窗口

适用于图形界面（GUI）应用程序，运行时隐藏控制台窗口：

pyinstaller --onefile --noconsole gui_app.py

---

5. 注意事项（路径）

• 路径问题：使用 --add-data 时，不同操作系统的路径分隔符需特别注意。

  • Windows："source;destination"
  • macOS/Linux："source:destination"

• 文件路径问题：在代码中访问本地文件时，使用相对路径获取的文件可能会在打包后无法找到。此时，建议使用以下方式获取正确的文件路径：

BASE_DIR = os.path.dirname(os.path.realpath(sys.argv[0]))

---

6. 错误处理和日志记录

在打包的 Python 应用中，为了方便调试，可以加入错误处理代码，将错误信息记录到文件中，帮助定位问题。

try:
    # 代码逻辑
    pass
except Exception as e:
    print("An error occurred:", e)
    with open("error_log.txt", "w") as f:
        f.write(str(e))

如果可执行文件出现问题，能够在 error_log.txt 中查看详细的错误信息。
例如，

这就是一个文件路径错误的报错，原因在于生成的可执行文件是在 dist 目录下，但是文件路径是相对路径，在 ../ 上，知道问题就可以解决了。否则，有时候连报错都不知道在哪。
另外，如果想要更加优雅地打包python，建议配合以下教程食用：
Python 参数配置使用 XML 文件的教程：轻松管理你的项目配置