====== PyInstaller 使用教程 (Python 打包指南) ======

PyInstaller 是一个非常流行的 Python 打包工具，它可以将 Python 脚本及其依赖项打包成一个独立的可执行文件（如 Windows 下的 .exe），使得在没有安装 Python 环境的机器上也能运行程序。

===== 1. 环境准备与安装 =====

在开始之前，建议创建一个干净的虚拟环境，以避免打包不必要的库，从而减小文件体积。

==== 1.1 安装 PyInstaller ====

在终端（CMD 或 PowerShell）中执行以下命令：

<code bash>
pip install pyinstaller
</code>

若需升级到最新版本：

<code bash>
pip install --upgrade pyinstaller
</code>

===== 2. 快速开始 =====

假设您的入口脚本名为 ''main.py''。

==== 2.1 最简单的打包 ====

<code bash>
pyinstaller main.py
</code>

执行后，会生成两个文件夹（''build'' 和 ''dist''）和一个文件（''main.spec''）。
  * **dist/main/** 文件夹中包含可执行文件和所有依赖文件。
  * 运行 ''dist/main/main.exe'' 即可启动程序。

==== 2.2 打包成单个文件 (常用) ====

如果您希望只有一个独立的 .exe 文件，使用 ''-F'' 参数：

<code bash>
pyinstaller -F main.py
</code>

  * 生成的文件位于 ''dist/main.exe''。
  * **注意**：单文件启动速度稍慢，因为运行时需要解压临时文件。

===== 3. 常用参数详解 =====

下表列出了最常用的命令行参数：

^ 参数 ^ 简写 ^ 说明 ^
| ''--onefile'' | ''-F'' | 将所有内容打包成一个单独的可执行文件。 |
| ''--noconsole'' | ''-w'' | **隐藏控制台窗口**。适用于 GUI 程序（如 PyQt, Tkinter）。如果程序出错，将看不到报错信息，建议调试阶段不要加此参数。 |
| ''--icon=FILE'' | ''-i'' | 指定可执行文件的图标（Windows 下需为 .ico 格式）。 |
| ''--name=NAME'' | ''-n'' | 指定生成的可执行文件的名称。 |
| ''--clean'' |  | 在构建之前清理 PyInstaller 缓存并删除临时文件。 |
| ''--add-data'' |  | 添加非代码资源文件（如图片、配置文件）。格式为 ''源路径;目标路径'' (Windows) 或 ''源路径:目标路径'' (Linux/Mac)。 |

**示例：打包一个带图标的 GUI 程序**

<code bash>
pyinstaller -F -w -i "logo.ico" -n "我的爬虫工具" main.py
</code>

===== 4. 高级用法：处理资源文件 =====

如果您的代码中读取了外部文件（如 ''config.yaml'' 或图片），打包后可能会报错“找不到文件”。这是因为打包后的运行路径发生了变化。

==== 4.1 代码调整 ====

在 Python 代码中，需要使用以下函数来获取资源的绝对路径：

<code python>
import sys
import os

def resource_path(relative_path):
    """ 获取资源绝对路径，适用于开发环境和 PyInstaller 打包后的环境 """
    if hasattr(sys, '_MEIPASS'):
        # PyInstaller 打包后，文件会被解压到 sys._MEIPASS 临时目录
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)

# 使用示例
config_path = resource_path("config.yaml")
</code>

==== 4.2 打包命令 ====

使用 ''--add-data'' 将文件包含进去。注意 Windows 使用分号 '';'' 分隔。

<code bash>
# 格式: --add-data "源文件;打包后的内部路径"
pyinstaller -F --add-data "config.yaml;." main.py
</code>

===== 5. 使用 Spec 文件 (推荐) =====

第一次运行 PyInstaller 命令后，会自动生成一个 ''name.spec'' 文件。您可以直接编辑这个文件来管理复杂的打包配置，而不需要每次都敲很长的命令。

编辑 ''main.spec'' 文件中的 ''Analysis'' 部分：

<code python>
a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[('config.yaml', '.'), ('images/', 'images/')], # 在这里添加资源文件
    hiddenimports=['pandas'], # 在这里手动添加未被识别的库
    ...
)
</code>

**使用 Spec 文件打包：**

<code bash>
pyinstaller main.spec
</code>

===== 6. 常见问题与解决方案 =====

==== 6.1 路径包含中文或特殊字符 ====
**现象**：报错 ''UnicodeDecodeError'' 或构建中断。
**解决**：
  - 确保项目路径**全英文**，且**无空格**。
  - 尽量不要把项目放在层级过深的目录（如 ''E:\工作\2025\项目\...\''）。
  - 建议移动到 ''C:\Build\Project'' 目录下进行打包。

==== 6.2 缺少模块 (ModuleNotFoundError) ====
**现象**：打包成功，但运行时提示找不到某个库（常见于 pandas, numpy 或动态导入的库）。
**解决**：
  - 使用 ''--hidden-import'' 参数手动指定：
    <code bash>
    pyinstaller -F --hidden-import=pandas._libs.tslibs.base main.py
    </code>
  - 或者在 spec 文件的 ''hiddenimports'' 列表中添加。

==== 6.3 文件体积过大 ====
**现象**：一个简单的脚本打包后有几百 MB。
**解决**：
  - **使用虚拟环境**：这是最主要的原因。如果在全局环境打包，PyInstaller 可能会把 Anaconda 中所有无关的库都打进去。
  - 使用 ''pipenv'' 或 ''venv'' 创建纯净环境，只安装必要的库。
  - 排除不需要的模块：''--exclude-module matplotlib''。

==== 6.4 被杀毒软件误报 ====
**现象**：打包出的 exe 被 Windows Defender 或 360 删除。
**解决**：
  - 这是 PyInstaller 的已知问题（Bootloader 特征码）。
  - 尝试重新编译 PyInstaller 的 Bootloader（较复杂）。
  - 或者向杀毒软件厂商提交误报申诉。
  - 尝试使用 Nuitka 作为替代方案（虽然 Nuitka 配置更难，但被杀毒软件拦截的概率较低）。

===== 7. 总结 =====

  - 简单脚本：直接用 ''pyinstaller -F main.py''。
  - GUI 程序：加上 ''-w'' 去除黑框。
  - 复杂项目：学会修改和使用 ''.spec'' 文件。
  - **切记**：保持路径纯净（无中文、无空格），使用虚拟环境。