C++ Tesseract OCR 子线程调用GetUTF8Text()崩溃问题求助

核心触发原因 #

该场景下的访问违规崩溃、单线程运行完全正常的表现，是Windows x64平台下Tesseract 4.1.1 + leptonica 1.78.0 + Qt组合的典型问题，不存在“代码逻辑完全一致就该跨线程正常运行”的通用规则，崩溃来自三类高频场景：

• Tesseract 4.x的线程模型限制
  Tesseract 4.x内部状态机没有实现跨线程的内存访问同步机制，单个TessBaseAPI实例的全流程操作（创建、初始化、参数设置、传图、识别、资源释放）必须100%绑定在同一个固定线程内完成，只要任意一个API调用跨了线程，内部缓存的线程本地内存指针就会失效，直接触发访问违规。
  常见踩坑场景：提前在主线程new出tessAPI实例传到子线程使用、在子线程完成初始化后切回主线程调用识别接口、跨线程执行资源释放操作。
• 跨模块CRT运行时不匹配
  Windows平台跨DLL的内存操作，要求所有模块必须链接相同版本的动态C运行库（CRT）。如果Tesseract、leptonica的预编译包是用静态CRT（/MT）编译，而Qt程序默认采用动态CRT（/MD）编译（反之亦然），GetUTF8Text()返回的由Tesseract内部堆分配的字符指针，在Qt的qDebug模块读取、释放时，会因为堆边界不匹配触发崩溃。这类问题在单线程下因为内存调用栈连续，堆管理器的兼容机制往往能正常运行，但在子线程下，堆的线程局部缓存机制会直接拦截跨堆访问，直接触发崩溃。
• 图像数据生命周期错位
  调用tessAPI->SetImage()传入OpenCV Mat的裸指针时，Tesseract不会复制图像数据，仅持有指针引用。如果Mat对象在SetImage完成后、GetUTF8Text()执行前被提前析构，或是OpenCV在子线程下的内存分配块边界和Tesseract预期不一致，就会出现悬空指针访问触发崩溃。

修复步骤（按优先级排序） #

• 严格绑定TessBaseAPI的操作线程
  彻底杜绝跨线程操作：把tessAPI的创建、Init、参数设置、SetImage、识别、End、实例销毁的全流程，全部写在子线程的执行函数内部，不要把tessAPI指针作为类成员在其他线程初始化，不要在其他线程调用该实例的任何API。如果用QThread实现，直接把整套识别逻辑封装在run()方法内运行，全程不跨线程传递tessAPI指针。
• 解决跨CRT的内存不匹配问题
  确认所用Tesseract、leptonica的x64预编译包，和Qt应用的编译配置完全一致：Qt默认MSVC版本采用/MD动态CRT编译，对应的Tesseract包必须是同版本MSVC + /MD配置编译，不能混用MinGW编译、/MT静态CRT编译的版本。
  如果无法更换预编译包，拿到GetUTF8Text()的返回值后第一时间做字符串拷贝，不要直接把Tesseract返回的指针传给Qt模块处理，流程示例：

  char* tessResult = tessAPI->GetUTF8Text();
  // 拷贝字符串到Qt自有内存空间
  QString resultStr = QString::fromUtf8(tessResult);
  // 同线程内完成所有资源释放
  tessAPI->End();
  delete tessAPI;
  pixDestroy(&pix);
  qDebug() << resultStr;
  

• 规避leptonica的子线程已知bug
  Tesseract 4.1.1搭配leptonica 1.78.0在Windows x64非主线程下，存在已知的LSTM模型加载的内存偏移问题，可以在Init完成后添加配置关闭LSTM的独立线程加载：

  tessAPI->SetVariable("lstm_choice_mode", "0");
  

  传图时不要直接传OpenCV Mat的裸指针，改用leptonica的Pix对象作为中间层传入，避免内存适配问题：

  Pix* pix = pixCreate(imgBlackWhite.cols, imgBlackWhite.rows, 8);
  for (int y = 0; y < imgBlackWhite.rows; y++) {
      memcpy(pixGetData(pix) + y * pixGetWpl(pix)*4, 
             imgBlackWhite.ptr(y), 
             imgBlackWhite.cols);
  }
  tessAPI->SetImage(pix);
  

• 快速定位问题节点
  在调用GetUTF8Text()前插入调试输出，判断崩溃位置：

  qDebug() << "tess instance valid: " << (tessAPI != nullptr);
  qDebug() << "img data ptr valid: " << (void*)imgBlackWhite.data;
  

  如果执行到这里就崩溃，说明是线程绑定或CRT不匹配问题；如果调试输出正常，仅调用GetUTF8Text()时崩溃，说明是leptonica的内存bug。

内容的提问来源于stack exchange，提问作者Dvy Hrnsch