安装tesseract需同时装运行时和开发库：Ubuntu/Debian执行sudo apt install tesseract-ocr libtesseract-dev libleptonica-dev；macOS用brew install tesseract leptonica；Windows推荐vcpkg。
安装 tesseract 和 C++ 开发库时，最容易漏掉 libtesseract-dev
直接 apt install tesseract-ocr 只装运行时，g++ 编译时会报 fatal error: tesseract/baseapi.h: No such file or directory。必须额外装开发头文件和静态/动态库：
-
sudo apt install tesseract-ocr libtesseract-dev libleptonica-dev（Ubuntu/Debian） - macOS 用
brew install tesseract leptonica即可，头文件默认可用 - Windows 建议用 vcpkg：
vcpkg install tesseract[core]:x64-windows leptonica:x64-windows，否则手动配 include/lib 路径极容易出错
初始化 tesseract::TessBaseAPI 前必须调用 Init()，且路径参数不能省
很多人写完 tesseract::TessBaseAPI api; 就直接 api.SetImage(...)，结果 Recognize() 返回 -1 或识别为空。根本原因是没初始化 OCR 引擎——Init() 不仅加载语言模型，还校验数据路径有效性：
- Linux/macOS 下，若未指定路径，
Init(nullptr, "chi_sim")会去/usr/share/tesseract-ocr/4.00/tessdata/找，但实际路径可能是/usr/share/tesseract-ocr/tessdata/，得显式传入：api.Init("/usr/share/tesseract-ocr/tessdata/", "chi_sim") - Windows 上路径要用正斜杠或双反斜杠：
api.Init("C:/tools/tessdata/", "eng") - 调用
Init()后务必检查返回值：if (api.Init(...) != 0) { /* 初始化失败 */ }，否则后续所有 API 调用都不可靠
SetImage() 对图像格式和内存布局极其敏感
tesseract 不接受任意 cv::Mat 或裸指针，它要求图像数据是连续、灰度、按行排列的 uint8 内存块。常见崩溃或乱码源于：
-
cv::Mat是 BGR 彩图？必须先转灰度：cv::cvtColor(img, gray, cv::COLOR_BGR2GRAY) -
cv::Mat数据不连续（如 ROI 截图）？必须复制：gray = gray.clone() - 传给
SetImage()的宽高单位是像素，不是字节；bytes_per_pixel必须为 1（灰度），bytes_per_line必须等于width（即无 padding） - 正确调用示例：
api.SetImage(gray.data, gray.cols, gray.rows, 1, gray.cols)
中文识别必须用 chi_sim.traineddata，且编码输出默认是 UTF-8
装完 tesseract 后，tesseract --list-langs 如果没看到 chi_sim，说明语言包没装全。识别中文时：
立即学习“C++免费学习笔记（深入）”；
- 确保
Init()第二个参数是"chi_sim"（简体中文），不是"chi_tra"（繁体）或"chi"（不存在） -
GetUTF8Text()返回的是char*，指向内部堆内存，**不能直接delete[]或长期持有**；应立即std::string text(api.GetUTF8Text())拷贝走 - 如果输出含乱码，大概率是终端或 IDE 不支持 UTF-8，而非识别错误；可用
printf("len=%zu, first char=0x%02x\n", text.length(), (unsigned char)text[0])验证是否真为 UTF-8 字节流
tesseract 的 C++ 接口看着简单，但 init 路径、图像内存布局、语言包路径这三处，任一出错都会静默失败——没有异常，也不报错，只是返回空字符串或垃圾结果。调试时优先打日志确认 Init() 返回值、GetAvailableLanguages() 输出、以及 IsValidImage() 结果。
