#python项目生成exe相关了解-优快云博客

本文链接：https://blog.youkuaiyun.com/weixin_48668249/article/details/146991956

在 Windows 上将 Python 项目 生成 EXE 可执行文件，主要使用 pyinstaller。以下是完整步骤：

📌 1. 安装 PyInstaller

pip install pyinstaller

如果已安装，可执行以下命令检查版本：

pyinstaller --version

📌 2. 进入 Python 项目目录

cd your_project_directory

确保 main.py 是项目的入口文件。

📌 3. 生成 EXE 文件

✅ 单文件模式（适用于小型项目）

pyinstaller --onefile main.py

--onefile：生成 单个 EXE 文件，所有依赖会被打包进这个 EXE。

✅ 目录模式（适用于大型项目，减少 EXE 启动时间）

pyinstaller -D main.py

-D（--onedir）：将 EXE 及所有依赖放入 dist/ 目录。

✅ 无控制台模式（GUI 应用）

如果你的程序是 图形界面（如 PyQt、Tkinter），可以隐藏终端窗口：

pyinstaller --onefile --windowed main.py

--windowed（-w）：不显示终端黑窗口，仅适用于 GUI 程序。

✅ 指定图标

pyinstaller --onefile --windowed --icon=myicon.ico main.py

--icon=myicon.ico：EXE 使用指定图标。

📌 4. 运行生成的 EXE

生成的文件位于 dist/ 目录：

cd dist
main.exe

可直接拷贝 main.exe 到其他 Windows 电脑运行（无需 Python 环境）。

📌 5. 解决 EXE 运行问题

🔹 避免 EXE 被误报为病毒

原因：PyInstaller 使用 UPX 压缩，部分杀毒软件误判。

解决：

pyinstaller --onefile --noconsole --noupx main.py

--noupx：禁用 UPX 压缩。

🔹 修复 EXE 运行时报 `Failed to execute script`

尝试 清理缓存后重新打包：

pyinstaller --clean --onefile main.py

🔹 依赖模块丢失

如果运行时提示 ModuleNotFoundError，需要手动指定：

pyinstaller --onefile --hidden-import=<module_name> main.py

📌 6. 让 EXE 更便携

如果要 支持拷贝到其他电脑直接运行：

pyinstaller --onefile --add-data "config.json;." --add-data "assets/;assets/" main.py

--add-data：确保额外资源（如配置文件、图片）一并打包。

📌 7. 结论

安装 PyInstaller
进入 Python 项目目录
执行 pyinstaller 生成 EXE
拷贝 dist/main.exe 到其他电脑直接运行 🚀

🎯 适用于 Tkinter、PyQt、PySide、pygame 等 GUI 应用，打包后可脱离 Python 运行！

在 pyinstaller 命令中，--add-data 选项用于将额外的文件或目录打包到 EXE 文件中。

📌 解释 `"config.json;."` 的含义

--add-data "config.json;."

拆解说明：

config.json：指的是当前目录下的 config.json 文件（打包前的位置）。
.（分号 ; 后面的 .）：表示打包后，这个文件应该放到 EXE 解压后的 工作目录（运行时的 sys._MEIPASS 目录）。

📌 作用：
👉 让 config.json 在 EXE 运行时仍然可用，就像它原本在当前目录一样。

📌 解释 `"assets/;assets/"`

--add-data "assets/;assets/"

拆解说明：

assets/：打包前的文件夹路径（当前目录下的 assets/ 文件夹）。
assets/（分号 ; 后面的路径）：表示打包后，它仍然应该放到 assets/ 这个目录里。

📌 作用：
👉 确保 assets/ 目录及其所有内容都被正确打包，并在运行 EXE 时保持相对路径不变。

📌 为什么用分号 `;`？

🔹 在 Windows 下，PyInstaller 需要使用 ; 分隔源路径和目标路径（Linux/macOS 用 :）。
🔹 在 macOS/Linux 上，写法如下：

--add-data "config.json:."
--add-data "assets/:assets/"

📌 代码示例：正确读取 `config.json`

打包后，EXE 运行时，所有被 --add-data 选项打包的文件会存放在 sys._MEIPASS 目录。
因此，你需要修改代码，动态获取文件路径：

import os
import sys
import json

# 获取资源文件的正确路径
def resource_path(relative_path):
    """在开发环境返回原路径，在 EXE 运行时返回打包路径"""
    if getattr(sys, 'frozen', False):
        # 运行时（EXE模式）
        base_path = sys._MEIPASS
    else:
        # 开发环境
        base_path = os.path.abspath(".")

    return os.path.join(base_path, relative_path)

# 读取 config.json
config_path = resource_path("config.json")

with open(config_path, "r", encoding="utf-8") as f:
    config = json.load(f)

print("配置内容:", config)

📌 结论

选项	含义
`config.json;.`	把 `config.json` 放在 EXE 运行时的当前目录
`assets/;assets/`	把整个 `assets/` 目录打包，并保持其路径

🛠 这样做的好处：

确保 EXE 运行时能找到这些文件。
打包后，仍然可以使用 config.json 和 assets/ 目录。
支持跨平台（Windows 需要 ;，Linux/macOS 需要 :）。

🚀 这样打包后，EXE 运行时就能正确访问这些资源文件了！

📌 `pyinstaller -D main.py` 适用于大项目吗？

🔹 结论：可以，但建议做额外优化！ 🚀
pyinstaller -D main.py （等价于 --onedir） 会生成一个 dist/ 目录，包含 EXE 及所有依赖文件，适用于大项目，但可能会遇到以下问题：

📌 1. 适用于大项目的正确做法

对于大项目，推荐使用目录模式（-D）+ 额外参数优化：

pyinstaller -D --hidden-import=<module> --add-data "config.json;." --add-data "static/;static/" main.py

✅ 关键优化点

选项	作用
`-D` / `--onedir`	默认模式，在 `dist/` 目录生成多个依赖文件，不压缩，启动快
`--hidden-import=<module>`	如果 `PyInstaller` 误报缺少依赖，可手动添加
`--add-data`	打包额外资源（如 `config.json`、`static/` 目录）
`--clean`	清理历史缓存，避免异常
`--log-level=DEBUG`	调试模式，帮助排查问题

📌 2. 可能遇到的问题及解决方案

🔹 1. EXE 运行时报 `ModuleNotFoundError`

原因：pyinstaller 可能漏掉了一些动态导入的库（如 importlib、cv2、tensorflow）。
解决方案：

pyinstaller -D --hidden-import=<缺失模块> main.py

示例（补充 pandas 相关依赖）：

pyinstaller -D --hidden-import=pandas._libs.tslibs main.py

🔹 2. 运行后找不到 `config.json`、`static/` 等资源

原因：PyInstaller 默认不会打包非 Python 代码的文件。
解决方案：手动指定：

pyinstaller -D --add-data "config.json;." --add-data "static/;static/" main.py

📌 特别注意：

Windows 使用 ; 分隔源路径和目标路径（config.json;.）。
Linux/macOS 使用 :（config.json:.）。

🔹 3. `dist/` 目录过大，EXE 体积太大

原因：大项目依赖多，打包会包含整个 Python 运行环境。
解决方案：

排除不必要的库

pyinstaller -D --exclude-module numpy main.py

使用 UPX 压缩
```
pyinstaller -D --upx-dir=UPX_PATH main.py
```
⚠ 注意：某些杀毒软件会误报 UPX 压缩的 EXE 为病毒，慎用！

🔹 4. EXE 运行时报 `Failed to execute script`

解决方案：

pyinstaller -D --clean main.py

📌 如果仍然报错，请检查：

是否使用了相对路径（可以用 sys._MEIPASS 获取 PyInstaller 运行时目录）。
是否缺少必要的 --hidden-import。

📌 3. 总结

✅ pyinstaller -D main.py 适用于大项目，但建议做以下优化：

加 --add-data，确保资源文件被正确打包。
加 --hidden-import，避免 ModuleNotFoundError。
使用 --clean 清理，防止历史缓存导致问题。
优化 EXE 体积，可用 --exclude-module 及 UPX 压缩。

🎯 最终推荐命令：

pyinstaller -D --hidden-import=<module> --add-data "config.json;." --add-data "static/;static/" --clean main.py

🚀 这样能保证大项目正确打包，且运行时不会报错！