简介：一套基于PaddleOCR的离线文字识别工具包，旨在帮助用户在无Python运行环境的设备上完成OCR识别。资源覆盖了模型调用、结果输出与程序封装环节，解决了常规OCR工具依赖联网环境、难以跨机分发的痛点。压缩包共包含2000个文件，大小约279MB，主要文件类型包括Python脚本、pyc/pyd编译模块、dll动态链接库等，这些组件共同组成可离线运行的识别基础；另外还含有数量较多的配置、消息和图片等辅助文件，用于支持模型加载与界面或输出逻辑。资源目前已有3789人学习下载，是被验证过的实用方案。通过该资源，使用者可以获得完整的PaddleOCR离线打包素材，参照内部结构自行生成独立可执行的识别程序，输入图片路径即可得到识别结果并保存为文本文件，适合文档扫描、批量图片转文字、本地OCR服务部署等多种应用场景。
1. 为什么碰 PaddleOCR 打包 exe：直接跑容易，交付才是分水岭
第一次把 PaddleOCR 跑出识别结果时，我一度以为这事已经结束了。直到某个需求方说“软件装在有摄像头的工控机上，那台机器不能联网，只要一个 exe”，我才发现模型跑通只是走完了 30%，剩下的 70% 全在打包、离线模型处理和交付环境适配里。市面上写 PaddleOCR 识别效果的文章很多，但讲清楚“怎么把它变成离线 exe 且不翻车”的实操记录很少。这篇笔记会按我实际拆过的流程走一遍，覆盖打包选型、模型内嵌、体积控制和五类高频故障，适合正在给内部工具做交付、或者准备把 OCR 能力塞进离线采集程序的开发者。顺手说一句，我用的是 PaddleOCR 的 Python 侧推理，不是 deploy 目录里的 C++ 方案，后者门槛完全不同，不在本文讨论范围。
2. 打包前先看懂链路：离线模型固化与 PyInstaller 选型
2.1 三段式推理链路为什么直接决定打包策略
PaddleOCR 一个基础中文识别任务不是单一模型，而是三段流水线：先是文本检测模型把图片里的文字行位置框出来，再是方向分类模型判断这一行有没有倒置（比如手机横竖屏拍出来的方向差异），最后才是文本识别模型把框好的区域翻译成字符串。这意味着打包时不能只带走一个模型文件，至少要带三个。我在代码里显式指定det_model_dir、rec_model_dir、cls_model_dir，就是不希望运行时依赖“首次联网下载模型”这个默认行为。
链条里有任何一个模型缺失，运行时报错往往不是“模型不存在”这种直白提示，而是paddleocr内部抛一段长 traceback，或者干脆尝试联网下载然后卡住。所以打包前的第一件事，就是先把三个 inference 模型下载到本地固定住。PaddleOCR 的模型库页面里能找到多种推理模型，选体积和精度都适中的中文模型即可，一般几十 MB 一个。注意下载的是inference.tar.gz解压后的文件，不是训练用的 checkpoint。
2.2 目录结构与模型路径约定
我习惯固定一个本地目录结构，打包脚本、推理脚本、模型目录都围绕它展开：
ocr_offline_tool/ ├── main.py ├── models/ │ ├── det/ # 检测模型解压后的全部文件 │ ├── rec/ # 识别模型解压后的全部文件 │ └── cls/ # 方向分类模型解压后的全部文件 └── requirements.txt用这种方式组织的结果是：在 PyInstaller 打包时，--add-data可以把整个 models 目录带进 exe 内部，或者拷贝到 exe 同级目录。代码里再做一个路径解析函数，保证源码环境和打包冻结环境都能找到模型目录，这部分会在第 5 章展开。
2.3 打包工具选型：没有悬念，PyInstaller 是首选
打包 Python 程序常见工具无非 PyInstaller、Nuitka、cx_Freeze 这几个。PaddleOCR 生态里绝大多数信息、踩坑记录、spec 示例都建立在 PyInstaller 基础上，这意味着你遇到问题时能搜到的参考最多。Nuitka 在纯 Python 代码上有编译收益，但对 PaddlePaddle 这种集成了大量动态库的开源框架，打包时异常处理比 PyInstaller 复杂得多。我的建议直接且务实：用 PyInstaller，版本选 6.x，不要追最新，等社区把新版本的坑填完再升。
打包形态上，--onefile和--onedir的抉择也很关键。--onefile看起来最接近“一个 exe 搞定”，但它启动时会先把内部资源解压到系统临时目录，PaddleOCR 这种体积的项目第一次启动慢到数秒甚至十几秒，而且容易被杀毒软件误报。--onedir会生成一个目录，里面是 exe 加一堆依赖 dll，启动更快、排查更容易。我交付时优先选--onedir，如果需求方坚持只要一个文件，再单独做--onefile版本并接受它的缺点。
2.4 依赖版本固定：这一步省掉整个午后
PaddleOCR 的依赖在 pip 安装时自动拉取，但自动拉取的版本有时反而不在线性兼容的区间。我最常踩的坑是shapely2.0 以后与 PaddleOCR 的多边形解析不兼容，报错信息极难索引。因此我每次新建环境都先固定这几个关键依赖：
pip install paddlepaddle==2.5.2 pip install paddleocr==2.7.0 pip install shapely==1.8.2 pip install pyinstaller==6.3.0paddlepaddle 顺便说一句，默认 pip 拿到的就是 CPU 版，体积相对可控；如果你机器上曾经装过 CUDA 版并把它带进了打包环境，最终生成物会大得很离谱，后面第 4 章专门有解。
3. 完整打包流程：从环境准备到 exe 出包
3.1 准备一个干净环境
打包最忌讳在开发环境里直接操作，因为开发环境里装过一万个包，PyInstaller 的依赖分析会被干扰，什么莫名其妙的问题都可能出现。我一般用虚拟环境专用目录：
python -m venv ocr_build_env ocr_build_env\Scripts\activate pip install paddlepaddle==2.5.2 paddleocr==2.7.0 shapely==1.8.2 pyinstaller==6.3.0这里有个细节：安装完成后立刻验证一下python -c "import paddle"是否成功。如果 import 都报错，说明 Python 版本和 paddlepaddle 版本不兼容，常见组合是 Python 3.9/3.10 对 2.5.x 系列的兼容性最好，Python 3.12 在某些版本上没有预编译包。
3.2 把三个模型放到位
从模型库页面下载det、rec、cls对应的推理模型压缩包，解压后把各自目录里的inference.pdmodel、inference.pdiparams等文件保持名称不变，放入本地 models 目录。文件命名不需要改，因为 PaddleOCR 内部是按默认文件名去加载的。模型目录结构见 2.2 节，不再重复。
3.3 离线推理脚本 main.py
下面是我用过的、并且验证过能成功打包的可运行脚本，去掉了一些项目定制内容，保留核心逻辑。它可以接受单个图片路径或文件夹路径，产出文本文件结果。
import sys import argparse from pathlib import Path from paddleocr import PaddleOCR def get_resource_path(relative_path: str) -> Path: """同时兼容源码运行与 PyInstaller 冻结运行时的路径定位。""" if getattr(sys, "frozen", False): base = Path(getattr(sys, "_MEIPASS", Path(sys.executable).parent)) else: base = Path(__file__).resolve().parent return base / relative_path def parse_ocr_result(raw_result): """把 PaddleOCR 返回的嵌套结构转成简单的 (文本, 置信度) 列表。""" lines = [] if not raw_result: return lines for page in raw_result: if not page: continue for box_info in page: if len(box_info) < 2: continue text, confidence = box_info[1] lines.append((str(text), float(confidence))) return lines def main(): parser = argparse.ArgumentParser(description="离线 OCR 命令行工具") parser.add_argument("-i", "--input", required=True, help="图片文件路径或包含图片的文件夹") parser.add_argument("-o", "--output", default="result.txt", help="结果输出路径") args = parser.parse_args() ocr = PaddleOCR( use_angle_cls=True, lang="ch", det_model_dir=str(get_resource_path("models/det")), rec_model_dir=str(get_resource_path("models/rec")), cls_model_dir=str(get_resource_path("models/cls")), show_log=False, use_gpu=False, ) input_path = Path(args.input) img_paths = [] if input_path.is_dir(): img_paths = sorted(input_path.glob("*.jpg")) + sorted(input_path.glob("*.png")) else: img_paths = [input_path] if not img_paths: print("未找到任何图片") return all_result_lines = [] for img_path in img_paths: raw = ocr.ocr(str(img_path), cls=True) parsed = parse_ocr_result(raw) for text, conf in parsed: all_result_lines.append(f"{img_path}\t{text}\t{conf:.4f}") with open(args.output, "w", encoding="utf-8") as fp: fp.writelines("\n".join(all_result_lines)) print(f"done, total {len(all_result_lines)} lines -> {args.output}") if __name__ == "__main__": main()这段脚本的关键在对 PaddleOCR 返回结果的解析：新版返回格式是双层嵌套结构，外层按图片页面分组，内层按文本行分组，每一行里存的是坐标框和(文本, 置信度)元组。不解析直接打印，你会在打包后得到一个看起来像对象地址的垃圾输出，这个问题我见不少人翻过车。参数上use_gpu=False必须显式指定，否则部分环境会尝试加载 CUDA 库，离线机器上没有就崩。
3.4 PyInstaller 打包命令与 spec
基础打包命令如下，Windows 下注意--add-data用分号分隔源与目标：
pyinstaller --noconfirm --clean --onedir ` --name OcrOfflineTool ` --add-data "models;models" ` --hidden-import shapely ` --hidden-import pyclipper ` --hidden-import skimage ` main.py这条命令里--add-data "models;models"的意思是：把源码目录下的 models 文件夹，复制到打包产物中的 models 路径。Linux 下分隔符是冒号，Windows 是分号。--hidden-import把 PaddleOCR 依赖链中动态导入的几个库补进去，这些都是常见的漏网之鱼，一次性写全。
--onedir产物会出现在dist/OcrOfflineTool/目录下，exe 文件和_internal依赖目录在一起。运行前我要检查一下_internal/models是否确实存在，很多人打包完以为成功了，实际上模型根本没用--add-data带进去。
3.5 出包后的目录检查
打开dist/OcrOfflineTool，重要检查点有四个：
| 检查项 | 期望结果 | 失败余地 |
|---|---|---|
| exe 能双击启动 | 命令行窗口正常驻留 | 秒退说明 Python 运行时或 dll 缺失 |
_internal/models三个模型目录齐全 | det/rec/cls 每个目录都有模型文件 | 识别报错缺模型或尝试联网 |
| paddle 相关 dll 存在 | _internal下有paddle相关动态库 | 提示缺paddle_fluid或paddle模块 |
| 用真实图片跑一次 | 输出文本合理 | 乱码、漏识别、框坐标异常 |
这个环节不要跳过，直接拿一张包含中文标点的样图丢给 exe，能看到完整输出再继续。
4. 避坑检查单：五类高频打包问题与处理方式
4.1 模块缺失：No module named 'paddle'
现象：打包后的 exe 运行时弹窗报ModuleNotFoundError: No module named 'paddle'，或者跑着跑着停在某个导入阶段。原因：PyInstaller 的静态分析没有把 paddle 框架内大量的 Python 包收集全，paddle 内部很多模块是通过动态导入方式加载的。解决方式：除了在命令行加--hidden-import paddle，我更推荐直接在 spec 文件里使用collect_all把这个框架及其子模块全都收进来：
from PyInstaller.utils.hooks import collect_all datas, binaries, hiddenimports = collect_all("paddle") # 运行 collect_all 后把三个列表填入 Analysis这里需要留意的是，collect_all("paddle")会把所有子模块、数据文件、二进制文件全部打进包，体积明显增加，但确实能解决绝大多数“打包后找不到模块”问题。我通常同时再对paddleocr也执行一次collect_all，双保险。
4.2 闪退且看不到错误信息
现象：双击 exe，命令行窗口一闪就消失，什么信息都不留。原因：PyInstaller 默认把控制台给应用绑定，但报错信息在窗口关闭前没来得及阅读，又或者是在非交互式会话下启动导致输出被吞。解决方式：先用 cmd 运行 exe，所有 traceback 都会停留在当前窗口：
cd dist\OcrOfflineTool OcrOfflineTool.exe -i test.jpg -o out.txt如果 exe 在 cmd 里也秒退，再用管理员身份开一个 PowerShell 看系统事件日志，定位具体缺哪一个动态库。--onedir模式下 exe 旁边还有一堆 log 文件，有时也会把异常输出写进去，同样值得先翻一遍。
4.3 shapely 2.0 导致识别过程崩溃
现象：exe 已经成功启动，模型也加载了，但一到真正执行文本检测时就崩，报错常含GEOSException或TopologyException。原因：PaddleOCR 内部对多边形交并计算依赖 shapely 1.x 的 API 行为，shapely 升到 2.0 后底层 GEOS 库的异常处理发生变化，环境安装的 shapely 版本过新。解决方式：把依赖指定回 1.8.x 系列再打包。这是我在 PaddleOCR 环境里碰到过的最典型的隐性版本陷阱，比显式ModuleNotFoundError更让人头疼。
4.4 中文路径导致的模型加载失败
现象：打包后 exe 放在带中文的目录下，运行报“模型文件不存在”或路径解析异常，但同样的模型文件在英文路径下就能加载。原因：PyInstaller 解压路径或模型路径拼接时，遇到中文字符串的编码处理与 Windows 下默认代码页不一致，导致路径无法正确识别。解决方式：交付时强制约定存放路径为纯英文无空格目录，同时代码里路径统一用Path对象处理而非字符串拼接，能规避大部分编码问题。如果需求方必须放中文路径，那就要改成从环境变量读取路径，而不是从 exe 自身位置推断。
4.5 杀毒软件误报 exe 为木马
现象：打包出的 exe 在部分机器上被拦截或直接被删除，尤其常见于--onefile形态。原因：PyInstaller 生成的 exe 带有自解压特征，加上 PaddlePaddle 内部大量二进制库的行为模式不符合常见静态特征库，确实容易被启发式查杀。解决方式：优先交付--onedir；如果必须 onefile，建议用 UPX 压缩关掉，因为 UPX 压缩壳本身就是误报重灾区。再不行就给目标机器加白名单，或者做签名。这不是 PaddleOCR 本身的问题，是 PyInstaller 打包程序的通病，提前跟需求方说清楚比较好。
5. 离线运行的关键：模型目录内嵌与运行时路径处理
5.1 两种离线策略的取舍
离线运行的关键只有一个：让 exe 在没有任何网络的情况下，也能在文件系统里找到推理模型。做法有两条路：一是把模型打进 exe 内部，靠sys._MEIPASS运行时解压；二是把模型放在 exe 同级目录，运行时直接读外部路径。第一种交付文件集中，但 onefile 形态首次启动要解压几十上百 MB，体验很差；第二种加载快、也好更新模型，但容易被人误删。我目前的倾向是 onedir + 内部模型，既有目录结构又集中；如果模型偶尔要更新，就把 models 放到 exe 同级做覆盖式替换，两种策略用同一个get_resource_path函数兼容。
5.2 _MEIPASS 到底在什么时候生效
PyInstaller 在 onefile 模式下会把--add-data指定的内容释放到系统临时目录，路径通过sys._MEIPASS暴露；onedir 模式下则放在解包后的_internal目录。运行环境中两个路径的解析规则不同，所以代码里必须做分支。前面 main.py 里那个get_resource_path函数就是干这个的：
if getattr(sys, "frozen", False): base = Path(getattr(sys, "_MEIPASS", Path(sys.executable).parent)) else: base = Path(__file__).resolve().parent这个分支每次打包前都要自己验证一遍，不能想当然。我见过不少人只写了sys._MEIPASS这一种情况，结果 onedir 模式下拿到的路径完全错误，模型怎么都找不到。代码里的getattr(..., Path(sys.executable).parent)就是给 onedir 做的兜底。
5.3 模型目录变更时的运行时检测
交付之后模型目录可能会被覆盖更新，比如换一个更大更准的中文模型。我习惯在主程序启动时加一个轻量自检，检查关键模型文件是否真实存在：
required_files = [ get_resource_path("models/det/inference.pdmodel"), get_resource_path("models/rec/inference.pdmodel"), get_resource_path("models/cls/inference.pdmodel"), ] missing = [str(p) for p in required_files if not p.exists()] if missing: print("模型文件缺失，请检查 models 目录：") print("\n".join(missing)) sys.exit(1)这样拿到 exe 的人即使误删了模型，也会得到明确的提示，而不是面对一段内部异常不知所措。参数上可以顺带检查模型目录里的.pdiparams文件是否同时存在，pdmodel 是结构文件、pdiparams 是权重文件，缺一不可。
5.4 从 300MB 到 200MB：体积控制的方向
PaddleOCR 打包体积主要花在 paddlepaddle 框架的动态库上，这部分基本动不了。能优化的是这几处：模型先确认选的是推理模型的小版本，比如 mobile 系列就比 server 系列小不少；打包时把没必要的paddle/fluid下的训练组件排除掉，但这个操作风险高，不建议新手碰；onefile 模式下开启 UPX 压缩能瘦身，但牺牲启动速度和误报率。我自己的实践是不追求极限体积，控制在 200~250MB 之间就足够交付了，省下来的时间多测几条真实样本更值。
6. 交付前最后一步：参数化 CLI 与冒烟测试
把 exe 交付给别人之前，我会给它补充两个实用的命令行参数：一个是输出格式切换，一个是置信度过滤。下面的代码片段是基于前面 main.py 的增量，不打乱原有逻辑：
parser.add_argument("--format", choices=["txt", "json"], default="txt", help="输出格式") parser.add_argument("--min-conf", type=float, default=0.0, help="置信度阈值，过滤低质量识别结果") # 写入结果时按格式分支处理 if args.format == "json": import json records = [ {"file": img_path, "text": text, "confidence": conf} for _, img_path, text, conf in ... # 循环时保存 ] with open(args.output, "w", encoding="utf-8") as fp: json.dump(records, fp, ensure_ascii=False, indent=2)加了--min-conf之后，需求方可以自己调阈值来滤掉水印、装饰字这类干扰识别结果。这个参数的实际效果很明显，我交付过的场景里，把阈值设到 0.5 基本能去掉大多数无效识别。
交付前最后一道工序是固定格式的冒烟测试，我一般做三件事：一张纯中文文本图、一张带数字和英文的混排图、一张倾斜 30 度以上的图片。三张全部通过，再提交。那些“代码在自己机器上没问题就等于没问题”的想法，我在这个项目里吃过亏，从那以后每次交付 exe 都强制走一遍冒烟测试，哪怕只是换了个模型目录，也要重新跑一轮再发出去。
希望这份拆解能帮你少走点弯路，让 PaddleOCR 的离线交付顺利落地。
本文还有配套的精品资源，点击获取
