Python 打包成独立运行的 EXE 文件

Python 打包成独立运行的 EXE 文件，核心原理是 **将 Python 解释器、你的脚本、依赖库、资源文件（如图片、配置）打包为一个整体**，无需用户额外安装 Python 环境。主流工具中，**PyInstaller** 兼容性最好、功能最全（推荐优先使用），其次是简化操作的 GUI 工具 **auto-py-to-exe**，以及跨平台的 **cx_Freeze**。

一、前提准备
1. **环境配置**：确保已安装 Python（3.6+ 版本兼容性最佳），且 `pip` 可用（默认随 Python 安装）。
– 验证：打开 cmd/终端，输入 `python –version` 和 `pip –version`，能显示版本号即正常。
2. **依赖整理**：如果脚本依赖第三方库（如 `requests`、`pyqt5`），建议先在项目目录下生成依赖清单（方便后续打包时自动包含）：
“`bash
# 生成依赖清单（requirements.txt）
pip freeze > requirements.txt
# 安装依赖（若需在新环境打包，先执行此命令）
pip install -r requirements.txt
“`

二、主流打包工具（按新手友好度排序）
1. auto-py-to-exe（GUI 工具，新手首选）
基于 PyInstaller 封装的可视化工具，无需记命令，点点鼠标即可完成打包。

步骤：
1. **安装工具**：
“`bash
pip install auto-py-to-exe
“`
2. **启动工具**：
在 cmd/终端输入 `auto-py-to-exe`，会自动打开 GUI 窗口。
3. **核心配置（关键步骤）**：
– **Script Location**：选择你的 Python 主脚本（如 `main.py`）。
– **Onefile**：勾选 = 生成单个 EXE 文件（方便分发）；不勾选 = 生成文件夹（包含 EXE 和依赖，运行更快）。
– **Console Window**：
– 勾选 = 运行时显示命令行窗口（适合调试、控制台程序）；
– 不勾选 = 无命令行窗口（适合 GUI 程序，如 PyQt、Tkinter 项目）。
– **Icon**：可选，设置 EXE 图标（需是 `.ico` 格式，可网上找图标转换工具将图片转 ico）。
– **Additional Files**：添加资源文件（如图片、配置文件），点击「Add Files」选择文件，确保脚本中使用 **相对路径** 访问这些资源。
4. **开始打包**：
点击右下角「Convert .py to .exe」，等待打包完成（底部会显示进度）。
– 输出路径：默认在 `output` 文件夹（可在「Advanced」→「Output Directory」修改）。

优势：
– 零命令操作，可视化配置，新手无压力；
– 自动处理依赖，无需手动配置。

2. PyInstaller（命令行工具，功能最强）
最主流的打包工具，支持单文件/多文件、GUI/控制台程序、自定义图标、加密源码等，兼容性覆盖 Python 3.6+ 所有主流版本。
步骤：
1. **安装工具**：
“`bash
pip install pyinstaller
“`

2. **基础打包（单脚本，快速上手）**：
打开 cmd/终端，切换到脚本所在目录（如 `cd D:\my_project`），执行命令：
“`bash
# 基础命令（生成文件夹，含 EXE 和依赖）
pyinstaller main.py

# 常用参数组合（推荐）
pyinstaller -F -w -i myicon.ico main.py
“`

3. **进阶打包（多文件/含资源/复杂依赖）**：
若项目是多脚本（如 `main.py` 依赖 `utils.py`）或含资源文件（如 `data.json`、图片），需用 **spec 文件** 配置（更灵活）：
– 第一步：生成默认 spec 文件：
“`bash
pyinstaller -F -w -i myicon.ico main.py –name myapp # 先执行基础命令，会生成 myapp.spec
“`
– 第二步：编辑 spec 文件（关键）：
用记事本/VS Code 打开 `myapp.spec`，主要修改 `datas`（添加资源文件）和 `hiddenimports`（添加缺失的依赖）：
“`python
# myapp.spec 示例
a = Analysis(
[‘main.py’, ‘utils.py’], # 所有依赖的脚本文件
pathex=[‘D:\\my_project’], # 项目目录
binaries=[],
# 添加资源文件：(源文件路径, 打包后存放的文件夹名)
datas=[(‘img/*.png’, ‘img’), (‘config.json’, ‘.’)], # 示例：img文件夹下的png图→打包后img文件夹；config.json→打包后根目录
hiddenimports=[‘requests’, ‘numpy’], # 若打包后提示“模块缺失”，在此添加依赖库
hookspath=[],
hooksconfig={},
runtime_hooks=[],
excludes=[],
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
noarchive=False,
)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
pyz,
a.scripts,
a.binaries,
a.zipfiles,
a.datas, # 必须包含，否则资源文件不会被打包
[],
name=’myapp’, # EXE 文件名
debug=False,
bootloader_ignore_signals=False,
strip=False,
upx=True, # 启用 UPX 压缩（减小 EXE 体积）
console=False, # False=无命令行窗口，True=显示
icon=’myicon.ico’, # 图标路径
)
“`
– 第三步：用 spec 文件打包：
“`bash
pyinstaller myapp.spec # 执行 spec 文件，而非直接执行脚本
“`

4. **打包结果**：
生成的 EXE 文件在项目目录的 `dist` 文件夹中（单文件模式直接是 `dist/myapp.exe`，多文件模式是 `dist/myapp/myapp.exe`）。

3. cx_Freeze（跨平台，支持多系统）
支持将 Python 脚本打包为 Windows（EXE）、Linux（可执行文件）、Mac（.app），适合需要跨平台分发的场景。

步骤：
1. **安装工具**：
“`bash
pip install cx_Freeze
“`
2. **创建配置文件**：
在项目目录下新建 `setup.py`（配置文件），内容如下：
“`python
from cx_Freeze import setup, Executable

# 配置打包选项
setup(
name=”MyApp”, # 程序名称
version=”1.0″,
description=”我的 Python 程序”,
executables=[
Executable(
“main.py”, # 主脚本
base=None, # 控制台程序用 None；GUI 程序用 “Win32GUI”（隐藏命令行）
icon=”myicon.ico”, # 图标（可选）
target_name=”myapp.exe” # 输出 EXE 文件名
)
]
)
“`
3. **执行打包**：
“`bash
# 生成文件夹（含 EXE 和依赖）
python setup.py build
“`
4. **打包结果**：
在 `build` 文件夹下，找到以系统命名的子文件夹（如 `exe.win-amd64-3.9`），里面的 `myapp.exe` 即为可执行文件。

三、关键注意事项（避坑必看）
1. **路径问题（最常见坑）**：
脚本中访问资源文件（图片、配置）时，必须用 **相对路径**，且打包时需将资源文件纳入（auto-py-to-exe 用「Additional Files」，PyInstaller 用 spec 文件的 `datas`）。
– 错误示例：`open(“C:\\Users\\xxx\\config.json”)`（绝对路径，换电脑失效）；
– 正确示例：`open(“config.json”)`（相对路径，与脚本同目录）。

2. **依赖缺失问题**：
若打包后运行提示“ModuleNotFoundError”，需：
– 确认依赖已安装（`pip install 缺失的库`）；
– 用 PyInstaller 时，在 spec 文件的 `hiddenimports` 中添加缺失的库（如 `hiddenimports=[‘requests’]`）。

3. **杀毒软件误报**：
部分打包后的 EXE 可能被杀毒软件误判为病毒（因为打包工具会修改可执行文件结构），可将 EXE 添加到杀毒软件信任列表。

4. **减小 EXE 体积**：
– 用 `-F` 单文件模式时，启用 UPX 压缩（PyInstaller 默认支持，需提前安装 UPX，官网：https://upx.github.io/）；
– 用 **虚拟环境** 打包：新建干净的虚拟环境，仅安装必要依赖（避免打包多余库）：
“`bash
# 新建虚拟环境
python -m venv myenv
# 激活虚拟环境（Windows）
myenv\Scripts\activate
# 激活虚拟环境（Linux/Mac）
source myenv/bin/activate
# 安装依赖和打包工具
pip install -r requirements.txt pyinstaller
# 打包
pyinstaller -F -w main.py
“`

5. **Python 版本兼容性**：
– 建议用 Python 3.8~3.10 打包（兼容性最好，高版本 Python 可能导致部分库打包失败）；
– 32 位 Python 打包的 EXE 可在 32/64 位 Windows 运行，64 位 Python 打包的 EXE 仅支持 64 位 Windows。

6. **GUI 程序特殊配置**：
若脚本是 PyQt、Tkinter、wxPython 等 GUI 程序，打包时需指定 `base=”Win32GUI”`（PyInstaller 用 `-w` 参数，cx_Freeze 用 `base=”Win32GUI”`），否则运行时会弹出多余的命令行黑框。

– 新手/快速需求：优先用 **auto-py-to-exe**；
– 复杂项目（多文件、多资源、需加密）：用 **PyInstaller + spec 文件**；
– 跨平台需求：用 **cx_Freeze**。

打包后的 EXE 仅支持对应系统（Windows 打包的 EXE 不能在 Linux/Mac 运行），若需多系统分发，需在对应系统上重新打包。