PyInstaller 打包后因 DLL/.so 缺失导致崩溃，需用 --add-binary 显式添加、编写钩子自动收集，并在代码中通过 sys._MEIPASS 动态构造路径且调用 os.add_dll_directory（Windows）或设置 LD_LIBRARY_PATH（Linux/macOS）确保系统级可见。

PyInstaller 找不到 DLL / .so 文件时的典型错误

运行打包后的程序直接崩溃，报错类似 ImportError: DLL load failed 或 OSError: [WinError 126] The specified module could not be found。这不是 Python 模块缺失，而是底层 C/C++ 动态链接库（如 opencv_world455.dll、libglib-2.0.so.0）没被正确包含或路径解析失败。

--add-binary 是最直接的补救方式

PyInstaller 不会自动扫描第三方库内部依赖的二进制文件，尤其当这些库通过 ctypes、shutil.load_library 或 C 扩展隐式加载时。必须显式告诉它“把哪个文件复制到哪”：

• --add-binary 格式为 "源路径;目标子目录"（Windows）或 "源路径:目标子目录"（Linux/macOS），注意分号/冒号是分隔符，不是路径一部分
• 例如 OpenCV 缺 DLL：先用 depends.exe（Windows）或 ldd cv2.cpython-*.so（Linux）查出缺失的 opencv_ffmpeg*.dll，再加参数：pyinstaller --add-binary "C:/path/to/opencv_ffmpeg455_64.dll;."
• 目标子目录填 . 表示跟可执行文件同级；填 cv2 表示放进 cv2/ 子目录——需和代码中 ctypes.CDLL("cv2/xxx.dll") 的路径一致

很多库需要配套的钩子（hooks）而非硬拷贝

手动 --add-binary 容易漏、难维护。更可靠的方式是启用或编写 PyInstaller 钩子：

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• 检查是否已有官方钩子：pip show pyinstaller 查安装路径，进入 hooks 目录看是否存在 hook-cv2.py 或 hook-PIL.py
• 若没有，可临时创建钩子文件（如 hook-mymodule.py），在其中调用 collect_dynamic_libs("mymodule") 或 collect_data_files("mymodule", includes=["*.dll"])
• 打包时用 --additional-hooks-dir=./my_hooks 指向自定义钩子目录
• 部分库（如 PyQt6、TensorFlow）的钩子会自动处理插件目录、CUDA 库等，比手动加 binary 更完整

运行时路径混乱才是根本隐患

即使 DLL 被打进包里，Python 运行时仍可能因 os.add_dll_directory() 或 PATH 未更新而找不到它。关键点：

立即学习“Python免费学习笔记（深入）”；

• 打包后，PyInstaller 会把所有二进制文件解压到一个临时目录（sys._MEIPASS），你的代码必须从这里加载 DLL，而不是写死绝对路径
• 正确做法：在代码开头动态构造路径：

  import os
  import sys
  if getattr(sys, 'frozen', False):
      base_path = sys._MEIPASS
  else:
      base_path = os.path.abspath(".")
  dll_path = os.path.join(base_path, "mylib.dll")
  ctypes.CDLL(dll_path)
  

• Windows 上还需在加载前调用 os.add_dll_directory(base_path)（Python ≥ 3.8），否则系统级 DLL 查找机制会忽略该路径

真正麻烦的从来不是“怎么加一个 DLL”，而是“怎么让整个加载链路在冻结状态下依然可信”。钩子解决的是收集问题，sys._MEIPASS 解决的是定位问题，而 add_dll_directory 或 LD_LIBRARY_PATH 设置解决的是操作系统级可见性问题——三者缺一不可。