ddddocr 打包说明文档（PyInstaller）

打包背景

ddddocr依赖非纯 Python 资源，包括 ONNX 模型文件、二进制扩展库和隐式导入模块。常规 PyInstaller 打包可能引发“模型文件缺失”或“模块导入失败”等问题，需通过显式收集依赖资源解决。

核心打包原理

PyInstaller 默认仅静态分析显式导入的纯 Python 代码，无法识别动态依赖。需使用 collect_all() 函数全量收集以下资源：

• datas：模型文件（.onnx）、配置文件等数据文件；
• binaries：二进制扩展文件（.pyd/.so）；
• hiddenimports：运行时动态导入的隐式依赖模块。

通用打包脚本模板

# -*- mode: python ; coding: utf-8 -*-
from PyInstaller.utils.hooks import collect_all

datas = []
binaries = []
hiddenimports = []

required_libs = [
    'ddddocr',
    'onnxruntime',
    'cv2',
    'requests',
    'bs4',
    'lxml',
    'urllib3',
    'certifi',
    'charset_normalizer',
    'idna',
    'soupsieve'
]

for lib in required_libs:
    tmp_ret = collect_all(lib)
    datas += tmp_ret[0]
    binaries += tmp_ret[1]
    hiddenimports += tmp_ret[2]

a = Analysis(
    ['gui.py'],
    pathex=[],
    binaries=binaries,
    datas=datas,
    hiddenimports=hiddenimports,
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    noarchive=False,
    optimize=0,
)
pyz = PYZ(a.pure)

exe = EXE(
    pyz,
    a.scripts,
    [],
    exclude_binaries=True,
    name='gui',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    console=False,
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon=['icon.ico'],
)

coll = COLLECT(
    exe,
    a.binaries,
    a.datas,
    strip=False,
    upx=True,
    upx_exclude=[],
    name='gui',
)

打包步骤

1. 环境准备
   安装依赖库：

   pip install pyinstaller ddddocr opencv-python onnxruntime requests bs4
   

2. 保存脚本
   将模板保存为 .spec 文件（如 gui.spec），替换主程序入口和文件名称等配置。

3. 执行打包
   运行命令：

   pyinstaller gui.spec
   

4. 验证结果
   运行 dist/gui/gui.exe，确认无“模型缺失”或“模块导入失败”错误。

常见问题及解决方案

问题现象	原因	解决方案
运行时报“找不到 det.onnx”	未收集 ddddocr 的 datas	确保调用 collect_all('ddddocr')
导入 onnxruntime 失败	未收集 onnxruntime 依赖	增加 collect_all('onnxruntime')
ImportError: 缺少依赖	隐式依赖未收集	检查 required_libs 并补充对应库
打包后程序闪退	console=False 导致日志丢失	临时将 console 改为 True 查看报错

关键注意事项

• 核心依赖必加：ddddocr、onnxruntime、cv2 必须通过 collect_all 收集。
• 批量收集维护：使用循环遍历 required_libs 替代逐行复制，新增依赖时仅需扩展列表。
• 环境一致性：打包前确保本地已安装所有必需库（如 opencv-python）。
• 跨平台适配：需在目标系统（Windows/macOS/Linux）上执行打包。

总结

ddddocr 打包需通过 collect_all() 全量收集模型文件、二进制文件和隐式依赖。核心是包含 ddddocr 及其上下游依赖（如 onnxruntime、cv2）的 collect_all 调用，批量收集方式可提升可维护性。

在使用 PyInstaller 打包包含ddddocr（带带弟弟 OCR）的 Python 项目时，很多同学会遇到模型文件缺失、模块导入失败、程序闪退等问题。这是因为ddddocr并非纯 Python 库，其依赖的 ONNX 模型文件、二进制扩展库无法被 PyInstaller 默认的静态分析识别。本文将详细讲解打包成功的核心原理，并提供可直接复用的通用打包模板，彻底解决该问题。