OpenCV C++ 编译链接错误和cv::imread返回空Mat是常见卡点：路径转义、相对路径基准、中文路径、编译选项缺失、Mat内存布局误用、引用计数陷阱及链接模块遗漏均导致静默失败。
OpenCV C++ 不是“装好就能用”的库，编译链接阶段出错才是你真正卡住的地方。
cv::imread 返回空 Mat 的常见原因
这根本不是图像路径写错了这么简单。Windows 下路径反斜杠没转义、Linux/macOS 下相对路径从可执行文件目录算起、中文路径未用 cv::String 构造——都导致 cv::imread 静默失败，mat.empty() 为 true。
- 用
cv::String("/home/user/img.jpg")替代裸字符串，避免 C++ 字符串转义干扰 - 检查文件是否存在：
std::filesystem::exists(path)（C++17 起），别只信cv::imread的返回值 - OpenCV 默认不支持 JPEG2000、WebP 等格式，编译时没开
WITH_JASPER或WITH_WEBP就会读失败且不报错
cv::Mat 内存布局与数据指针误用
直接拿 mat.data 当 C 数组遍历，很容易越界或踩到 padding 字节。OpenCV 的 cv::Mat 每行末尾可能有对齐填充（mat.step ≠ mat.cols * mat.elemSize()）。
- 遍历像素优先用
mat.at<uchar>(i, j)或mat.ptr<uchar>(i)，别硬算地址 - 创建自定义内存的
cv::Mat时，必须显式传入step参数，否则默认按cols * elemSize算，后续cv::resize或 ROI 操作会崩 -
cv::Mat是引用计数对象，mat.clone()才深拷贝；cv::Mat roi = mat(cv::Rect(0,0,100,100))共享数据，改 roi 就改原图
编译时 undefined reference 到 cv::xxx 的典型场景
不是 OpenCV 没装，而是链接顺序或模块没开对。比如用了 cv::dnn::readNet 却没链接 opencv_dnn，或者 CMakeLists.txt 里 find_package(OpenCV REQUIRED) 成功了，但 target_link_libraries(myapp ${OpenCV_LIBS}) 漏了 ${OpenCV_LIBS}。
立即学习“C++免费学习笔记（深入）”；
- CMake 中务必确认
message(${OpenCV_LIBS})输出包含你要用的模块，如opencv_imgproc、opencv_videoio - Linux 下静态链接需额外加
-ldl -lpthread，否则cv::VideoCapture初始化失败 - macOS M1/M2 上用 Homebrew 装的 OpenCV 默认是 arm64，但 clang 可能默认编译 x86_64，架构不匹配会导致符号找不到
OpenCV C++ 接口看着像 C++，实则大量沿用 C 风格内存管理和宏定义逻辑。最麻烦的从来不是算法调用，而是 Mat 生命周期管理、模块链接粒度、以及跨平台路径和编码处理——这些地方一错，连第一行 cv::imshow 都弹不出窗口。
