通过cx-freeze编译Python程序为exe后 其他设备Pytesseract无法正常运行的问题

核心实现思路 #

无需引导终端用户单独下载安装Tesseract OCR引擎，直接将便携版Tesseract的可执行文件、语言包资源与Python代码一同打包，运行时动态匹配路径，实现开箱即用。

分步操作流程 #

• 准备便携版Tesseract资源
  1. 下载解压即可运行的绿色版Tesseract OCR程序，无需走安装流程
  2. 在项目根目录新建tesseract_runtime文件夹，将解压后的tesseract.exe、包含所有需要语言包（比如简体中文、英文识别包）的tessdata文件夹全部放入该目录，最终目录结构如下：

  项目根目录/
  ├─ MatrixARKBot.py  # 你的主程序
  ├─ setup.py          # 打包配置文件
  └─ tesseract_runtime/
      ├─ tesseract.exe
      └─ tessdata/
          ├─ chi_sim.traineddata
          └─ eng.traineddata
  

• 改造主程序中的路径配置逻辑，替换原来写死的绝对路径

  原代码中硬编码的C:\Program Files\Tesseract-OCR\tesseract路径仅在你自己的本机有效，发到用户机器上100%会找不到文件，需要替换为适配本地开发、打包后运行两种场景的动态路径逻辑：

  import os
  import sys
  import pytesseract
  
  def get_resource_path(relative_path):
      # cx-freeze打包后，程序运行时的工作目录为exe所在文件夹
      if getattr(sys, "frozen", False):
          base_dir = os.path.dirname(sys.executable)
      # 本地开发调试时，从项目根目录读取资源
      else:
          base_dir = os.path.abspath(".")
      return os.path.join(base_dir, relative_path)
  
  # 动态绑定Tesseract可执行文件路径
  pytesseract.pytesseract.tesseract_cmd = get_resource_path(r"tesseract_runtime\tesseract.exe")
  # 显式指定语言包目录路径，避免Tesseract默认去系统安装路径找识别资源
  os.environ["TESSDATA_PREFIX"] = get_resource_path(r"tesseract_runtime\tessdata")
  

• 修改cx-freeze打包配置，将外部Tesseract资源一同打入输出目录
  在原setup.py的配置中增加include_files参数，把整个tesseract_runtime目录映射到打包输出的目录层级，完整配置示例如下：

  from cx_Freeze import setup, Executable
  import os
  
  build_exe_options = {
      "packages": ["tkinter","sys","pynput","time","pyautogui","PIL","os","win32api","win32con","cv2","pyperclip","pytesseract","numpy","threading","mysql.connector"],
      # 关键配置：将非Python依赖的外部文件同步拷贝到打包输出目录
      "include_files": [
          (os.path.abspath("./tesseract_runtime"), "tesseract_runtime")
      ]
  }
  
  # GUI模式无后台控制台窗口
  base = "Win32GUI"
  
  target = Executable(
      script="MatrixARKBot.py",
      base=base,
      targetName="MatrixARKBot.exe"
  )
  
  setup(
      name = "MatrixARKBot",
      version = "0.1",
      description = "Matrix ARK Bot",
      options = {"build_exe": build_exe_options},
      executables = [target]
  )
  

常见踩坑提醒 #

• 不要省略TESSDATA_PREFIX环境变量配置：就算成功定位到了tesseract.exe，没有指定语言包路径时，Tesseract仍会默认读取系统级安装目录下的识别数据，依然会触发报错
• 打包完成后需要核查输出目录结构，确保tesseract_runtime文件夹与最终生成的exe文件处于同一层级，否则动态路径逻辑会失效
• 交付时可以将整个build输出的文件夹压缩后发给终端用户，无需用户进行任何额外安装操作，解压即可运行所有功能

内容的提问来源于stack exchange，提问作者Steel Hard