动态库找不到的典型错误是运行时提示“xxx.dll was not found”或静默失败；需用--include-binary-files显式打包非python二进制文件，并确保路径正确、架构匹配、依赖完整。
动态库找不到的典型错误现象
运行生成的 demo.exe 时弹窗提示“The code execution cannot proceed because xxx.dll was not found.”，或直接闪退无日志；用 dependency walker（Windows）或 ldd（Linux）检查 demo.dist/demo.exe 或对应 .so 文件，发现高亮标红的未解析依赖项；某些功能（如 OpenCV 视频读取、PyTorch CUDA 初始化）在打包后静默失败。
--include-binary-files 是最直接的解决方式
Nuitka 不会自动扫描并打包非 Python 文件（如 .dll、.so、.dylib），必须显式声明。使用 --include-binary-files 可将单个或通配路径下的二进制文件复制进 .dist 目录，并保持相对路径结构：
-
--include-binary-files=lib/opencv_world455.dll=lib/：把项目中lib/opencv_world455.dll复制到输出目录的lib/子目录下 -
--include-binary-files=venv/Lib/site-packages/torch/lib/*.dll=torch/lib/：Windows 下批量包含 PyTorch 的 DLL，目标路径为torch/lib/ - 注意等号左右不能有空格，目标路径末尾斜杠决定是否创建子目录
- 该参数不支持递归目录，如需整个目录请改用
--include-raw-dir
第三方包自带的 DLL 需要定位到真实路径
很多包（如 cv2、torch、geos）安装后会在 site-packages 下带自己的 .dll 或 .so。这些文件不会被 --follow-imports 自动识别，必须手动找出来：
华为云 Python SDK 查询工具。自动发现已安装 SDK 的服务包、Client类、API 方法、入参详情、类信息（__init__ 参数、属性、类型、描述），支持关键字搜索，快速定位目标 API 使用方法。
- 先运行
python -c "import cv2; print(cv2.__file__)"定位cv2模块位置，通常其同级目录有opencv_python.libs/或直接含.dll - 对
torch，查torch.__path__[0]后进入lib/子目录，里面全是*.dll - 不要依赖
PATH中的系统级 DLL（如 Windows 的msvcp140.dll），Nuitka 打包后环境无全局 PATH，必须一并包含 - 若用 MinGW64 编译，还需确认是否缺
libgcc_s_seh-1.dll、libstdc++-6.dll—— 这些可从 MinGW64 安装目录的bin/下提取
避免重复打包和路径错位的关键细节
动态库路径错位是运行时报错的隐形元凶。即使文件已复制，如果没放在运行时能加载的位置，依然失败：
- Windows 下，DLL 必须与
.exe同目录，或在其子目录（如lib/xxx.dll），但不能放在父目录或任意其他路径 - Linux/macOS 下，
.so默认只从LD_LIBRARY_PATH或可执行文件所在目录搜索，所以--include-binary-files的目标路径建议设为.（当前目录）或./lib/，并在代码中用os.add_dll_directory()（Win）或ctypes.CDLL("./lib/xxx.so")显式加载 - 多个包共用同一 DLL（如
libglib-2.0-0.dll）时，只打包一份即可，重复会导致.dist体积膨胀且可能冲突 - 调试阶段加
--show-progress --show-memory，观察编译日志里是否出现 “Copying binary file” 行，确认包含动作确实触发
真正麻烦的不是找不到 DLL，而是它被找到了却加载失败——比如架构不匹配（32 位 exe 加载 64 位 dll）、依赖链断裂（A.dll 依赖 B.dll，但只打了 A）、或运行时路径没被正确注入。每次添加 --include-binary-files 后，务必用 ldd 或 dependency walker 重新验证最终输出目录里的完整依赖图。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
