PyInstaller进阶指南：巧用--add-data打包多类型资源文件

1. 为什么需要--add-data参数

刚开始用PyInstaller打包Python程序时，我踩过一个坑：程序在本机运行好好的，发给同事却报错找不到配置文件。折腾半天才发现，原来程序依赖的config.json根本没被打包进去。这就是--add-data参数存在的意义——它专门用来处理那些非.py的资源文件。

常见的资源文件类型包括但不限于：

• 图片资源：程序图标(.ico)、界面素材(.png/.jpg)
• 配置文件：JSON/XML/INI等格式的配置文件
• 数据文件：CSV数据集、SQLite数据库等
• 模型文件：机器学习模型(.pth/.h5)
• 文档资源：使用说明(.md)、许可协议(.txt)

这些文件有个共同特点：它们不会被PyInstaller自动编译打包。如果不做特殊处理，打包后的程序就像搬家时只带了家具没带日用品——看起来完整，实际根本没法用。

2. --add-data的基本用法

2.1 参数格式解析

--add-data的完整语法是这样的：

bash复制pyinstaller your_script.py --add-data="源路径;目标路径"

这里有个平台差异需要特别注意：

• Windows使用分号;分隔路径
• Linux/macOS使用冒号:分隔路径

举个实际例子，假设项目结构如下：

code复制project/
├── src/
│   └── main.py
├── config/
│   └── settings.json
└── images/
    └── logo.png

要把config和images都打包进去，命令应该是：

bash复制# Windows
pyinstaller src/main.py --add-data="config/*;config" --add-data="images/*;images"

# Linux/macOS
pyinstaller src/main.py --add-data="config/*:config" --add-data="images/*:images"

2.2 路径书写技巧

我总结了几种常见场景的路径写法：