基于PyInstaller onedir的树莓派Debian应用打包安装路径及优化咨询

你选的PyInstaller onedir模式做Debian包分发的思路本身完全可行，之前运行失效、不符合目录规范的问题，本质是没有遵循Debian文件系统层级的路径规则，不是打包方向错了。
之前的失效原因很好定位：PyInstaller onedir模式的可执行文件启动时，是基于自身二进制文件的实际存放路径查找同目录下的所有依赖库、配置文件的。你之前把所有应用文件直接堆在/usr/lib根目录下，再在/usr/bin创建软链接的时候，程序解析自身路径会优先识别软链接所在的/usr/bin目录，根本找不到实际存放依赖的位置，自然启动失败。

按照Debian包的规范和FHS标准，推荐的安装结构是：

• 应用所有的核心文件（PyInstaller生成的dist目录下全部内容，包括主程序、依赖库、模型文件、配置），统一存放在 /usr/lib/<你的应用专属命名> 路径下，比如应用叫tf-data-collector，就建一个/usr/lib/tf-data-collector/的专属目录，把所有文件完整放进去，设置root:root属主，只读权限给所有用户读取。
• 不要把文件直接堆在/usr/lib的根层级，这个目录下的文件都是系统包管理器维护的系统级库，同名库文件冲突很容易直接搞崩系统的其他组件。
• 软链接要使用绝对路径创建：在/usr/bin下生成指向实际可执行文件的软链接，比如执行 ln -s /usr/lib/tf-data-collector/主程序文件名 /usr/bin/tf-data-collector，不要用相对路径写软链接的目标，避免路径解析出错。

• /usr/bin：仅适合存放单文件的可执行程序，绝对不能放带依赖库的整个应用目录，会污染系统可执行文件路径，不符合Debian包的规范。
• /usr/lib：是系统第三方应用的标准存放位置，但必须给应用单独建专属子目录，不能直接把文件堆在根级。这种路径下的文件会被Debian包管理器追踪，安装、升级、卸载的时候不会残留文件，是最适配deb分发的选择。
• /usr/local/lib：是给手动编译安装的非系统源程序预留的路径，合规但存在缺陷——这个路径下的文件默认不会被Debian包管理器纳入校验范围，后续升级卸载时很容易留下残留的旧版本库文件，不推荐给deb包分发的场景使用。

除了修正路径的问题，你还可以通过几个调整进一步解决之前onefile模式下的启动慢、体积大的问题：

• 不要把TensorFlow全量依赖打进PyInstaller的安装包。现在树莓派适用的Debian bullseye/bookworm源中，已经有适配armhf/arm64架构的官方python3-tensorflow包，你只需要在deb包的控制文件里声明这个依赖，打包时剔除PyInstaller抓取的TensorFlow相关文件，能把安装包体积减少300MB以上，同时因为系统源的TensorFlow是专门做过ARM指令集优化的，实际运行速度还会比PyInstaller抓的通用编译版本更快。
• 打包时给PyInstaller加--contents-directory . 参数，让所有依赖文件直接和主可执行文件放在同一层目录，避免深层嵌套的路径在树莓派低速SD卡上的读取开销，启动速度还能再提一截，也不会出现路径解析出错的问题。
• 如果应用带大量静态资源（比如TensorFlow训练好的模型文件，单文件就上百MB），可以把这些资源文件单独放在/usr/share/<应用名>路径下，在PyInstaller打包时通过--add-data参数指定运行时的资源查找路径，能进一步减少核心程序目录的文件数量，降低SD卡的随机读写消耗。

补充说明：之前onefile模式启动慢、临时目录占空间的问题，在onedir模式下会自然消失——onedir模式跳过了每次启动时全量解压文件到_MEI开头临时目录的步骤，启动时间会从原来的5分钟级压缩到10秒以内，也不会产生残留的临时文件占用磁盘，是比onefile更适配树莓派场景的打包模式。

内容的提问来源于stack exchange，提问作者Enorio