2026/9/7 15:18:24
FEATURED · 精选文章 
简介一份基于PaddleOCR打造并已打包成exe的离线文字识别工具面向需要在无Python环境下快速提取图片文字的普通用户、运维人员或嵌入式场景解决OCR功能部署繁琐的问题。资源包含完整的运行依赖与核心脚本共2000个文件压缩包大小约279.22MB其中以Python源码py、字节码pyc、扩展模块pyd和动态链接库dll为主辅以配置、文本及时区数据文件构成了闭环的离线运行环境可确保工具不依赖外部网络和Python解释器。使用时只需双击exe并输入图片路径即可调用PaddleOCR内置模型完成识别结果自动保存为txt文件同时保留源码便于二次修改或替换模型。目前已有3774人学习下载适合希望直接获得免环境部署方案或想研究PyInstaller打包PaddleOCR应用细节的开发者。其中还包含了PaddleOCR常用依赖让使用者不必自行处理复杂的环境匹配问题。 最近一直有朋友问PaddleOCR训练好的模型怎么给现场同事用总不能每次交付都让对方装Python、配环境、pip install一堆依赖吧。有一次客户那边连外网都不通模型下不下来原本半小时能演示的功能折腾了一整天。从那之后我就养成了习惯凡是拿PaddleOCR做的识别小工具一律先打包成exe离线工具再交付。下面我完整记录一次打包过程目标很明确一个基于PaddleOCR的识别脚本通过PyInstaller打包成exe放在任意一台没安装Python的Windows电脑上断网也能直接运行。适合给客户交付OCR工具的开发者、想把自己的小工具分享给同事的测试工程师以及刚接触Python打包、总在缺DLL和缺模型上翻车的朋友。本文环境以Windows 10、Python 3.9、PaddleOCR 2.6.x为例其他版本思路一致照着做基本能一次跑通。1. 为什么“离线工具”需求这么普遍1.1 三个最典型的落地场景我遇到过的需求大致能分成三类。第一类是客户现场对方电脑是普通办公机没有Python环境公司域控还限制安装软件你不可能让客户去敲命令行。第二类是生产环境服务器在内网无法连接外网pip install一律禁止但业务上有大量图片要识别必须有一份能直接丢进去的离线程序。第三类是给同事用同事只想快速识别一批截图你给他Anaconda他也不会用给个exe双击就行省得天天来找你配环境。这三类场景的共性是你不能要求使用方会Python、能联网、能处理依赖。打包成exe的核心价值就是把环境复杂度全部吞掉让使用者看到的只是一个可执行文件。这也是“离线工具”这四个字真正的含义不是简单把.py变成.exe而是把模型、运行库、依赖全部装进一个可复制、可移动的部署包里。1.2 打包工具选型为什么还是PyInstaller开始之前总会有人问不用PyInstaller行不行当然可以我实际试过Nuitka、cx_Freeze和py2exe但最后固定用PyInstaller。原因很实际PyInstaller对第三方库的hook最全PaddleOCR、shapely、Pillow这些打包时容易出问题的库在社区里都有大量踩坑记录出事了能查到方案。Nuitka编译成C之后启动确实更快、体积也更小但编译时间特别长运行时报错更底层对刚接触打包的新手不友好cx_Freeze的配置偏手动PaddleOCR这种带原生DLL和多层数据文件的库很容易漏文件。如果你追求极致性能等流程跑通后可以再研究Nuitka第一版老老实实用PyInstaller最省心。对了打包机最好选一台干净的Windows机器所有操作都在虚拟环境里做避免本机装了太多无关Python包结果全被PyInstaller收集进exe体积大得离谱。1.3 离线工具到底包含哪些东西很多新手容易误解以为打包完就只有一个exe文件。PaddleOCR有一点特别坑模型文件默认在首次运行时从官网下载离线环境根本拉不下来。所以一个真正能交付的“离线工具”至少包含四部分一是可执行exe主程序二是PaddleOCR运行时需要的所有Python依赖和原生DLL库这部分由PyInstaller自动收集三是中文识别模型文件包括检测(det)、识别(rec)、方向分类(cls)四是目标机器可能缺失的VC运行库。交付前最好把这几样打包成一个zipzip内部固定目录结构而不是发一个光秃秃的exe过去。这个习惯帮我省掉了很多售后问题因为单文件的PaddleOCR在离线环境下十有八九会栽在模型文件缺失上。2. 环境准备先在本地把识别脚本跑通2.1 Python版本与虚拟环境打包前先别急着写界面第一步是把识别能力在本地跑通。Python版本我建议用3.8或3.9PaddlePaddle 2.4.x对3.10以上版本的支持虽然也在推进但配合PyInstaller时偶尔会遇到莫名其妙的兼容问题而3.8/3.9是目前最稳妥的搭配。先用命令行创建虚拟环境py -3.9 -m venv .venv .venv\Scripts\activate打包必须在虚拟环境里做而且要保证这个虚拟环境尽量干净。如果本机装过torch、opencv、numpy等一堆包PyInstaller会顺着import关系把这些东西带进产物哪怕你完全没用到体积照样飙升。2.2 安装PaddlePaddle和PaddleOCR激活虚拟环境后安装CPU版Paddle和PaddleOCR。这里强调一定要装CPU版GPU版会额外引入CUDA相关库打包出来的体积巨大而且客户机器没有对应显卡驱动反而跑不起来pip install -U pip pip install paddlepaddle2.4.2 -i https://pypi.tuna.tsinghua.edu.cn/simple pip install paddleocr2.6.1.3 -i https://pypi.tuna.tsinghua.edu.cn/simple我选择把版本号固定住而不是直接pip install paddleocr装最新版目的是保持可复现。新版本可能引入新的依赖和行为变化可能导致我之前调好的打包参数失效固定版本能让交付物长期可控。CPU版在普通文档识别场景跑起来已经很快一张A4图片识别时间在两三秒左右完全够用。2.3 模型文件提前下好别指望自动下载PaddleOCR初始化时会检查本地有没有模型没有就从官方地址下载。离线环境下这个下载逻辑会一直卡住或报超时所以必须在打包前手动下载模型固定放到工程目录的models文件夹里。代码里这么指定模型路径ocr PaddleOCR( use_angle_clsTrue, langch, det_model_dirmodels/det, rec_model_dirmodels/rec, cls_model_dirmodels/cls )模型文件从PaddleOCR官方文档里找到对应下载链接通常每个模型是一个tar包解压后会有model、params这些文件解压到的目录名要跟上面代码里的路径对应上。注意不同版本参数名可能有差异2.6.x这样写是没问题的。我第一次打包就忘了放模型到客户机器上界面正常打开但识别结果一直不出来最后排查发现模型还躺在开发机的C盘缓存目录里非常尴尬。3. 脚本设计的几个细节3.1 命令行版本先跑通正式写界面之前先写一个main.py命令行版本接收一个图片路径、输出识别文本这样能最快验证模型和依赖是否正确。代码很短import argparse from paddleocr import PaddleOCR import json parser argparse.ArgumentParser() parser.add_argument(image) args parser.parse_args() ocr PaddleOCR( use_angle_clsTrue, langch, det_model_dirmodels/det, rec_model_dirmodels/rec, cls_model_dirmodels/cls ) result ocr.ocr(args.image, clsTrue) lines [] for line in result[0]: lines.append(line[1][0]) print(json.dumps(lines, ensure_asciiFalse))命令行版非常适合调试脚本报错时能把完整traceback打到控制台。本地随便找张带文字的图片跑一下确认能识别出内容再进行下一步。3.2 加一个tkinter小界面如果交付给不会打开命令行的人必须有个可视化界面。我不建议为了界面引入PyQt或PySide库体积会增大几十MB而且PyInstaller打包时需要额外处理Qt插件目录复杂度上升。tkinter完全够用Windows自带tk打包也简单。核心逻辑就是一个“选择图片”按钮加一个结果文本框识别函数复用上面那段。这里有个易踩的坑如果用--windowed模式打包控制台是隐藏的print内容根本看不见所以代码里要把识别结果实时写到文本框或者自动保存到一个output.txt文件。第一次做界面打包的时候我点按钮没有反应而系统也没有任何提示就是因为打印在控制台的内容全被吞了。3.3 资源路径要考虑到“打包后”新手最容易踩的坑是路径问题。脚本在开发环境用相对路径没问题但打包成exe后当前工作目录可能是系统目录也可能是你双击exe时所在的目录完全不可控。我固定用以下方式定位exe所在目录import sys from pathlib import Path if getattr(sys, frozen, False): BASE_DIR Path(sys.executable).resolve().parent else: BASE_DIR Path(__file__).resolve().parent DET_MODEL_DIR BASE_DIR / models / det REC_MODEL_DIR BASE_DIR / models / rec CLS_MODEL_DIR BASE_DIR / models / cls这样无论exe放在哪个文件夹都从exe所在目录找models开发阶段则从脚本目录找。后面的打包环节里只需把整个models文件夹复制到exe旁边就能生效。3.4 异常处理和中文路径问题正式交付前要把文件不存在、模型目录缺失、识别结果为空这些异常情况处理掉。不能用户选了一张损坏图片程序直接崩溃。旧版Paddle对中文路径的支持不太好如果工具被放在“新建文件夹(副本)”这种目录下可能报错或识别不到内容。最稳妥的办法是在部署说明里明确要求目录不要包含中文。4. PyInstaller打包实战4.1 安装PyInstaller在同一个虚拟环境里安装PyInstaller版本也固定避免新版hook变化影响结果pip install pyinstaller5.13.24.2 打包命令参数一个个解释我推荐用onedir模式也就是生成一个文件夹而不是单个exe文件。下面这条命令是我反复调整后固定下来的一套参数适用于PaddleOCR加CPU版Paddlepyinstaller --noconfirm --clean --onedir --console \ --name OCROffline \ --collect-all paddleocr \ --collect-all shapely \ --hidden-import pyclipper \ --exclude-module matplotlib \ --exclude-module PyQt5 \ main.py拆开说明一下。--noconfirm --clean是每次打包都从零开始避免缓存导致的奇怪问题。--onedir是生成目录而不是单文件启动更快、方便排查也减少被杀毒软件误报的概率。--console保留控制台窗口在客户机器上出现问题能看到报错等稳定后再改成--windowed。--collect-all paddleocr很关键PyInstaller默认只收集Python模块但PaddleOCR内部还带一些配置文件和字体资源必须把整个包的数据文件都收进来--collect-all shapely同理shapely在做多边形框计算时会用到几何数据DLL漏掉它必然运行时报错--hidden-import pyclipper是因为这个Cython扩展有时扫描不到。最后排除的matplotlib和PyQt5都是PaddleOCR可能间接引入但我们实际用不到的重型库排除之后体积能小不少。4.3 打包后的目录整理打包完成后dist/OCROffline/就是我们要交付的目录。把models目录复制进去和OCROffline.exe平级最终目录结构大致是这样的dist/ └─ OCROffline/ ├─ OCROffline.exe ├─ models/ │ ├─ det/ │ ├─ rec/ │ └─ cls/ ├─ _internal/ │ ├─ paddleocr/ │ ├─ paddle/ │ └─ ... └─ vc_redist.x64.exevc_redist.x64.exe是VC运行库安装包有些客户机器缺少它会出现DLL报错。对离线工具来说把这个运行库安装包一起放进部署目录部署说明里写清楚要装比客户出问题时再远程指导省心得多。4.4 缺少DLL的兜底思路当目标机器报“DLL load failed while importing”这类错误时优先安装VC运行库。如果装完仍然报这个错打开dist/OCROffline/_internal到paddle或shapely的目录里找找有没有对应DLL把缺的DLL复制到exe同级目录有时候也能解决。但这是排查兜底手段不是常规做法不能在每台客户机器上都这么操作否则说明打包时collect参数不完整。5. 离线环境验证与常见问题5.1 在干净虚拟机测试打包完成先别急着交付一定要在干净的Windows环境里做一次离线验证。我通常开一台Windows虚拟机不安装Python、不配置任何环境把dist/OCROffline整个目录拷贝进去断开虚拟机的网络双击exe选一张测试图片跑一遍。这一步能模拟最终用户的使用场景比开发机上跑一百遍都管用。另外要把部署目录放在带中文的路径下再试一次验证中文路径问题是否会影响结果。5.2 常见问题速查表我把这段时间踩过的坑整理成了一张表方便排查现象可能原因解决方式控制台报 No module named paddleocr--collect-all没生效或打包时不在正确的虚拟环境重新检查打包命令确认dist/OCROffline/_internal里存在paddleocr目录ImportError: DLL load failed while importing缺少VC运行库或Paddle依赖的动态库安装vc_redist.x64.exe或从打包机的paddle目录复制缺失DLL识别结果乱码或空白模型文件没加载到或路径不对检查models目录是否在exe同级确认det/rec/cls路径有效中文字符输出乱码控制台编码问题文本保存用utf-8必要时在代码里设置sys.stdout.reconfigure(encodingutf-8)打包后体积超过1GB把GPU版Paddle或无关库混进来了重装CPU版用--exclude-module排除无用库杀毒软件报毒或删除exePyInstaller打包程序常见误报对exe做数字签名或在目标机器添加白名单5.3 排查技巧打包排查阶段我会先写一个几行的最小脚本专门import关键模块比如只加载PaddleOCR并识别一张图单独打包验证哪个模块缺就补哪个hidden-import。这种做法比直接打包完整工具快很多。另外客户机器上如果不小心关闭了控制台窗口看不到报错可以让他们在CMD里手动输入exe的完整路径再运行错误信息就会留在命令行窗口里。还有一个我自己的习惯build过程中看日志里有没有“missing module”的警告那是问题最早出现的信号比等到运行时报错再返工快得多。6. 体积、启动速度与后续优化6.1 启动慢的根源PaddleOCR的exe启动速度确实比普通程序慢CPU版也经常要两三秒才弹出界面。原因是它需要加载Paddle推理库、多个模型文件和一堆依赖DLL再加上杀毒软件对DLL的扫描启动时间就上去了。这是框架特点没法完全消除只能尽量优化。6.2 可落地的优化措施如果你对体积和速度不满意可以从三个方向优化。第一确认用的是CPU版PaddleGPU版会多出几百兆第二如果业务场景不涉及倾斜矫正把use_angle_clsFalse这样不会加载cls模型启动会快一点第三业务场景只识别英文数字的话把lang改成en并使用对应英文模型模型体积会明显更小。另外代码里尽量不要import用不到的库PyInstaller会顺着模块依赖关系把所有import到的内容都带进去。6.3 把工具再往前推一步这套打包流程稳定后可以继续扩展。比如把exe做成图片右键菜单在资源管理器里右键图片就能调起识别或者把识别能力封装成本地HTTP服务供局域网内其他机器调用。不管怎么扩展核心的打包思路和参数不会有太大变化都是在同一个产物基础上做加法。最后再分享一点个人经验。我在这个流程上反复折腾了一个多月现在固定成“准备部署说明加一键打包脚本”的模式项目里直接跑build.bat十分钟后拿dist目录走人。真正让我长记性的是两件事不要在打包机上验证完就觉得没问题一定要在干净虚拟机里断网测一遍也别指望单个exe能搞定PaddleOCR离线工具是一个整体exe、模型目录、VC运行库一样都不能少。交付前把部署说明写好路径别带中文、运行库要安装、models目录别删这几句话说清楚后续的售后问题能少一大半。本文还有配套的精品资源点击获取
PaddleOCR模型打包exe离线工具：从环境配置到交付的全流程指南
简介一份基于PaddleOCR打造并已打包成exe的离线文字识别工具面向需要在无Python环境下快速提取图片文字的普通用户、运维人员或嵌入式场景解决OCR功能部署繁琐的问题。资源包含完整的运行依赖与核心脚本共2000个文件压缩包大小约279.22MB其中以Python源码py、字节码pyc、扩展模块pyd和动态链接库dll为主辅以配置、文本及时区数据文件构成了闭环的离线运行环境可确保工具不依赖外部网络和Python解释器。使用时只需双击exe并输入图片路径即可调用PaddleOCR内置模型完成识别结果自动保存为txt文件同时保留源码便于二次修改或替换模型。目前已有3774人学习下载适合希望直接获得免环境部署方案或想研究PyInstaller打包PaddleOCR应用细节的开发者。其中还包含了PaddleOCR常用依赖让使用者不必自行处理复杂的环境匹配问题。 最近一直有朋友问PaddleOCR训练好的模型怎么给现场同事用总不能每次交付都让对方装Python、配环境、pip install一堆依赖吧。有一次客户那边连外网都不通模型下不下来原本半小时能演示的功能折腾了一整天。从那之后我就养成了习惯凡是拿PaddleOCR做的识别小工具一律先打包成exe离线工具再交付。下面我完整记录一次打包过程目标很明确一个基于PaddleOCR的识别脚本通过PyInstaller打包成exe放在任意一台没安装Python的Windows电脑上断网也能直接运行。适合给客户交付OCR工具的开发者、想把自己的小工具分享给同事的测试工程师以及刚接触Python打包、总在缺DLL和缺模型上翻车的朋友。本文环境以Windows 10、Python 3.9、PaddleOCR 2.6.x为例其他版本思路一致照着做基本能一次跑通。1. 为什么“离线工具”需求这么普遍1.1 三个最典型的落地场景我遇到过的需求大致能分成三类。第一类是客户现场对方电脑是普通办公机没有Python环境公司域控还限制安装软件你不可能让客户去敲命令行。第二类是生产环境服务器在内网无法连接外网pip install一律禁止但业务上有大量图片要识别必须有一份能直接丢进去的离线程序。第三类是给同事用同事只想快速识别一批截图你给他Anaconda他也不会用给个exe双击就行省得天天来找你配环境。这三类场景的共性是你不能要求使用方会Python、能联网、能处理依赖。打包成exe的核心价值就是把环境复杂度全部吞掉让使用者看到的只是一个可执行文件。这也是“离线工具”这四个字真正的含义不是简单把.py变成.exe而是把模型、运行库、依赖全部装进一个可复制、可移动的部署包里。1.2 打包工具选型为什么还是PyInstaller开始之前总会有人问不用PyInstaller行不行当然可以我实际试过Nuitka、cx_Freeze和py2exe但最后固定用PyInstaller。原因很实际PyInstaller对第三方库的hook最全PaddleOCR、shapely、Pillow这些打包时容易出问题的库在社区里都有大量踩坑记录出事了能查到方案。Nuitka编译成C之后启动确实更快、体积也更小但编译时间特别长运行时报错更底层对刚接触打包的新手不友好cx_Freeze的配置偏手动PaddleOCR这种带原生DLL和多层数据文件的库很容易漏文件。如果你追求极致性能等流程跑通后可以再研究Nuitka第一版老老实实用PyInstaller最省心。对了打包机最好选一台干净的Windows机器所有操作都在虚拟环境里做避免本机装了太多无关Python包结果全被PyInstaller收集进exe体积大得离谱。1.3 离线工具到底包含哪些东西很多新手容易误解以为打包完就只有一个exe文件。PaddleOCR有一点特别坑模型文件默认在首次运行时从官网下载离线环境根本拉不下来。所以一个真正能交付的“离线工具”至少包含四部分一是可执行exe主程序二是PaddleOCR运行时需要的所有Python依赖和原生DLL库这部分由PyInstaller自动收集三是中文识别模型文件包括检测(det)、识别(rec)、方向分类(cls)四是目标机器可能缺失的VC运行库。交付前最好把这几样打包成一个zipzip内部固定目录结构而不是发一个光秃秃的exe过去。这个习惯帮我省掉了很多售后问题因为单文件的PaddleOCR在离线环境下十有八九会栽在模型文件缺失上。2. 环境准备先在本地把识别脚本跑通2.1 Python版本与虚拟环境打包前先别急着写界面第一步是把识别能力在本地跑通。Python版本我建议用3.8或3.9PaddlePaddle 2.4.x对3.10以上版本的支持虽然也在推进但配合PyInstaller时偶尔会遇到莫名其妙的兼容问题而3.8/3.9是目前最稳妥的搭配。先用命令行创建虚拟环境py -3.9 -m venv .venv .venv\Scripts\activate打包必须在虚拟环境里做而且要保证这个虚拟环境尽量干净。如果本机装过torch、opencv、numpy等一堆包PyInstaller会顺着import关系把这些东西带进产物哪怕你完全没用到体积照样飙升。2.2 安装PaddlePaddle和PaddleOCR激活虚拟环境后安装CPU版Paddle和PaddleOCR。这里强调一定要装CPU版GPU版会额外引入CUDA相关库打包出来的体积巨大而且客户机器没有对应显卡驱动反而跑不起来pip install -U pip pip install paddlepaddle2.4.2 -i https://pypi.tuna.tsinghua.edu.cn/simple pip install paddleocr2.6.1.3 -i https://pypi.tuna.tsinghua.edu.cn/simple我选择把版本号固定住而不是直接pip install paddleocr装最新版目的是保持可复现。新版本可能引入新的依赖和行为变化可能导致我之前调好的打包参数失效固定版本能让交付物长期可控。CPU版在普通文档识别场景跑起来已经很快一张A4图片识别时间在两三秒左右完全够用。2.3 模型文件提前下好别指望自动下载PaddleOCR初始化时会检查本地有没有模型没有就从官方地址下载。离线环境下这个下载逻辑会一直卡住或报超时所以必须在打包前手动下载模型固定放到工程目录的models文件夹里。代码里这么指定模型路径ocr PaddleOCR( use_angle_clsTrue, langch, det_model_dirmodels/det, rec_model_dirmodels/rec, cls_model_dirmodels/cls )模型文件从PaddleOCR官方文档里找到对应下载链接通常每个模型是一个tar包解压后会有model、params这些文件解压到的目录名要跟上面代码里的路径对应上。注意不同版本参数名可能有差异2.6.x这样写是没问题的。我第一次打包就忘了放模型到客户机器上界面正常打开但识别结果一直不出来最后排查发现模型还躺在开发机的C盘缓存目录里非常尴尬。3. 脚本设计的几个细节3.1 命令行版本先跑通正式写界面之前先写一个main.py命令行版本接收一个图片路径、输出识别文本这样能最快验证模型和依赖是否正确。代码很短import argparse from paddleocr import PaddleOCR import json parser argparse.ArgumentParser() parser.add_argument(image) args parser.parse_args() ocr PaddleOCR( use_angle_clsTrue, langch, det_model_dirmodels/det, rec_model_dirmodels/rec, cls_model_dirmodels/cls ) result ocr.ocr(args.image, clsTrue) lines [] for line in result[0]: lines.append(line[1][0]) print(json.dumps(lines, ensure_asciiFalse))命令行版非常适合调试脚本报错时能把完整traceback打到控制台。本地随便找张带文字的图片跑一下确认能识别出内容再进行下一步。3.2 加一个tkinter小界面如果交付给不会打开命令行的人必须有个可视化界面。我不建议为了界面引入PyQt或PySide库体积会增大几十MB而且PyInstaller打包时需要额外处理Qt插件目录复杂度上升。tkinter完全够用Windows自带tk打包也简单。核心逻辑就是一个“选择图片”按钮加一个结果文本框识别函数复用上面那段。这里有个易踩的坑如果用--windowed模式打包控制台是隐藏的print内容根本看不见所以代码里要把识别结果实时写到文本框或者自动保存到一个output.txt文件。第一次做界面打包的时候我点按钮没有反应而系统也没有任何提示就是因为打印在控制台的内容全被吞了。3.3 资源路径要考虑到“打包后”新手最容易踩的坑是路径问题。脚本在开发环境用相对路径没问题但打包成exe后当前工作目录可能是系统目录也可能是你双击exe时所在的目录完全不可控。我固定用以下方式定位exe所在目录import sys from pathlib import Path if getattr(sys, frozen, False): BASE_DIR Path(sys.executable).resolve().parent else: BASE_DIR Path(__file__).resolve().parent DET_MODEL_DIR BASE_DIR / models / det REC_MODEL_DIR BASE_DIR / models / rec CLS_MODEL_DIR BASE_DIR / models / cls这样无论exe放在哪个文件夹都从exe所在目录找models开发阶段则从脚本目录找。后面的打包环节里只需把整个models文件夹复制到exe旁边就能生效。3.4 异常处理和中文路径问题正式交付前要把文件不存在、模型目录缺失、识别结果为空这些异常情况处理掉。不能用户选了一张损坏图片程序直接崩溃。旧版Paddle对中文路径的支持不太好如果工具被放在“新建文件夹(副本)”这种目录下可能报错或识别不到内容。最稳妥的办法是在部署说明里明确要求目录不要包含中文。4. PyInstaller打包实战4.1 安装PyInstaller在同一个虚拟环境里安装PyInstaller版本也固定避免新版hook变化影响结果pip install pyinstaller5.13.24.2 打包命令参数一个个解释我推荐用onedir模式也就是生成一个文件夹而不是单个exe文件。下面这条命令是我反复调整后固定下来的一套参数适用于PaddleOCR加CPU版Paddlepyinstaller --noconfirm --clean --onedir --console \ --name OCROffline \ --collect-all paddleocr \ --collect-all shapely \ --hidden-import pyclipper \ --exclude-module matplotlib \ --exclude-module PyQt5 \ main.py拆开说明一下。--noconfirm --clean是每次打包都从零开始避免缓存导致的奇怪问题。--onedir是生成目录而不是单文件启动更快、方便排查也减少被杀毒软件误报的概率。--console保留控制台窗口在客户机器上出现问题能看到报错等稳定后再改成--windowed。--collect-all paddleocr很关键PyInstaller默认只收集Python模块但PaddleOCR内部还带一些配置文件和字体资源必须把整个包的数据文件都收进来--collect-all shapely同理shapely在做多边形框计算时会用到几何数据DLL漏掉它必然运行时报错--hidden-import pyclipper是因为这个Cython扩展有时扫描不到。最后排除的matplotlib和PyQt5都是PaddleOCR可能间接引入但我们实际用不到的重型库排除之后体积能小不少。4.3 打包后的目录整理打包完成后dist/OCROffline/就是我们要交付的目录。把models目录复制进去和OCROffline.exe平级最终目录结构大致是这样的dist/ └─ OCROffline/ ├─ OCROffline.exe ├─ models/ │ ├─ det/ │ ├─ rec/ │ └─ cls/ ├─ _internal/ │ ├─ paddleocr/ │ ├─ paddle/ │ └─ ... └─ vc_redist.x64.exevc_redist.x64.exe是VC运行库安装包有些客户机器缺少它会出现DLL报错。对离线工具来说把这个运行库安装包一起放进部署目录部署说明里写清楚要装比客户出问题时再远程指导省心得多。4.4 缺少DLL的兜底思路当目标机器报“DLL load failed while importing”这类错误时优先安装VC运行库。如果装完仍然报这个错打开dist/OCROffline/_internal到paddle或shapely的目录里找找有没有对应DLL把缺的DLL复制到exe同级目录有时候也能解决。但这是排查兜底手段不是常规做法不能在每台客户机器上都这么操作否则说明打包时collect参数不完整。5. 离线环境验证与常见问题5.1 在干净虚拟机测试打包完成先别急着交付一定要在干净的Windows环境里做一次离线验证。我通常开一台Windows虚拟机不安装Python、不配置任何环境把dist/OCROffline整个目录拷贝进去断开虚拟机的网络双击exe选一张测试图片跑一遍。这一步能模拟最终用户的使用场景比开发机上跑一百遍都管用。另外要把部署目录放在带中文的路径下再试一次验证中文路径问题是否会影响结果。5.2 常见问题速查表我把这段时间踩过的坑整理成了一张表方便排查现象可能原因解决方式控制台报 No module named paddleocr--collect-all没生效或打包时不在正确的虚拟环境重新检查打包命令确认dist/OCROffline/_internal里存在paddleocr目录ImportError: DLL load failed while importing缺少VC运行库或Paddle依赖的动态库安装vc_redist.x64.exe或从打包机的paddle目录复制缺失DLL识别结果乱码或空白模型文件没加载到或路径不对检查models目录是否在exe同级确认det/rec/cls路径有效中文字符输出乱码控制台编码问题文本保存用utf-8必要时在代码里设置sys.stdout.reconfigure(encodingutf-8)打包后体积超过1GB把GPU版Paddle或无关库混进来了重装CPU版用--exclude-module排除无用库杀毒软件报毒或删除exePyInstaller打包程序常见误报对exe做数字签名或在目标机器添加白名单5.3 排查技巧打包排查阶段我会先写一个几行的最小脚本专门import关键模块比如只加载PaddleOCR并识别一张图单独打包验证哪个模块缺就补哪个hidden-import。这种做法比直接打包完整工具快很多。另外客户机器上如果不小心关闭了控制台窗口看不到报错可以让他们在CMD里手动输入exe的完整路径再运行错误信息就会留在命令行窗口里。还有一个我自己的习惯build过程中看日志里有没有“missing module”的警告那是问题最早出现的信号比等到运行时报错再返工快得多。6. 体积、启动速度与后续优化6.1 启动慢的根源PaddleOCR的exe启动速度确实比普通程序慢CPU版也经常要两三秒才弹出界面。原因是它需要加载Paddle推理库、多个模型文件和一堆依赖DLL再加上杀毒软件对DLL的扫描启动时间就上去了。这是框架特点没法完全消除只能尽量优化。6.2 可落地的优化措施如果你对体积和速度不满意可以从三个方向优化。第一确认用的是CPU版PaddleGPU版会多出几百兆第二如果业务场景不涉及倾斜矫正把use_angle_clsFalse这样不会加载cls模型启动会快一点第三业务场景只识别英文数字的话把lang改成en并使用对应英文模型模型体积会明显更小。另外代码里尽量不要import用不到的库PyInstaller会顺着模块依赖关系把所有import到的内容都带进去。6.3 把工具再往前推一步这套打包流程稳定后可以继续扩展。比如把exe做成图片右键菜单在资源管理器里右键图片就能调起识别或者把识别能力封装成本地HTTP服务供局域网内其他机器调用。不管怎么扩展核心的打包思路和参数不会有太大变化都是在同一个产物基础上做加法。最后再分享一点个人经验。我在这个流程上反复折腾了一个多月现在固定成“准备部署说明加一键打包脚本”的模式项目里直接跑build.bat十分钟后拿dist目录走人。真正让我长记性的是两件事不要在打包机上验证完就觉得没问题一定要在干净虚拟机里断网测一遍也别指望单个exe能搞定PaddleOCR离线工具是一个整体exe、模型目录、VC运行库一样都不能少。交付前把部署说明写好路径别带中文、运行库要安装、models目录别删这几句话说清楚后续的售后问题能少一大半。本文还有配套的精品资源点击获取 
