在使用 `PyInstaller` 打包 Python 应用程序时，经常会遇到需要将外部数据文件（例如图片、配置文件等）嵌入到最终的可执行文件中。此时就可以使用 `--add-data` 参数来指定这些额外的数据文件。 --- ### **`--add-data` 的基本用法** #### 格式说明： ```bash pyinstaller [选项] your_script.py --add-data "<source>:<target>" ``` - `<source>`：表示源文件的实际路径（即你的项目中使用的外部文件路径）。可以是单个文件或整个目录。 - `<target>`：表示目标路径，也就是当应用程序运行时，文件会被解压到的目标目录名称。 注意： - 在 **Windows** 系统下，冒号 (`:`) 需要用分号 (`;`) 替代，格式为：`"<source>;<target>"`。 - 在 **macOS/Linux** 系统下，直接使用冒号 (`:`)，格式为：`"<source>:<target>"`。 --- ### **示例** 假设我们有以下场景： 1. 你的主脚本名为 `main.py`； 2. 脚本中引用了一个外部配置文件 `config.json`； 3. 还有一些图标文件存放在 `icons/` 目录下。 #### 情况 1：仅添加单一文件 如果你想将 `config.json` 包含进来，并将其放置在一个叫做 `data/` 的虚拟目录中： ```bash pyinstaller --onefile main.py --add-data "config.json:data/config.json" ``` 在 Windows 上应改为： ```bash pyinstaller --onefile main.py --add-data "config.json;data/config.json" ``` #### 情况 2：添加整个目录 若要将所有图标文件都包含进来，同时放入虚拟的 `resources/icons/` 目录： ```bash pyinstaller --onefile main.py --add-data "icons/:resources/icons/" ``` 在 Windows 上则是： ```bash pyinstaller --onefile main.py --add-data "icons\\;resources/icons/" ``` --- ### **注意事项** 1. **读取打包后的文件路径** 当使用 `--onefile` 打包时，临时提取出的资源不会位于当前工作目录中。你需要通过特殊变量获取正确的路径。可以在代码中定义类似这样的函数来帮助定位： ```python import sys, os def resource_path(relative_path): if hasattr(sys, '_MEIPASS'): return os.path.join(sys._MEIPASS, relative_path) else: return os.path.join(os.path.dirname(__file__), relative_path) config_file = resource_path("data/config.json") # 示例 print(config_file) ``` 2. **避免同名冲突** 如果多次调用了 `--add-data` 并且指定了相同的 `<target>`，可能会导致覆盖问题，请尽量保证每份资源都有唯一的存放位置。 ---