cv2.CascadeClassifier() 加载失败常静默返回空对象，需用 detector.empty() 检查；路径须正确（推荐 cv2.data.haarcascades 拼接），并确保图像转灰度、参数合理、分类器复用。
cv2.CascadeClassifier() 加载失败但没报错
OpenCV 的 cv2.CascadeClassifier() 在 XML 文件路径错误、文件损坏或格式不兼容时，常常静默返回一个空的分类器对象（detector.empty() 为 True），而不是抛异常。很多人卡在这一步，以为代码跑通了，实际后续 detectMultiScale() 总是返回空列表。
- 务必在加载后立刻检查：
if detector.empty(): raise ValueError("Failed to load cascade XML") - 路径必须是绝对路径或相对于当前工作目录的**正确相对路径**——注意 Python 脚本执行时的
cwd不一定是脚本所在目录 - OpenCV 4.5.5+ 对旧版 Haar XML 兼容性变差，若用的是 OpenCV 官网下载的
haarcascade_frontalface_default.xml，优先确认版本匹配；推荐直接用cv2.data.haarcascades提供的内置路径
用 cv2.data.haarcascades 找不到 XML 文件
cv2.data.haarcascades 是个字符串常量，指向 OpenCV 安装时自带的级联文件目录，但它**不是自动搜索路径**，只是告诉你“文件应该在哪”。如果手动拼接路径出错（比如漏了斜杠、大小写不对），照样打不开。
- 正确用法：
cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml") - Windows 下路径分隔符用
/或os.sep都行，但不要混用反斜杠\（容易被当成转义） - Linux/macOS 注意大小写：文件名是
haarcascade_frontalface_default.xml，不是HaarCascade...xml或frontalFace.xml - 不确定路径是否有效？先 print 出完整路径，再用
os.path.isfile()检查
detectMultiScale() 返回空列表但图像明显有人脸
不是模型不行，大概率是预处理或参数没调对。Haar 分类器对对比度、光照、人脸角度和尺寸非常敏感，原始图像几乎总是需要调整。
- 必须把彩色图转成灰度：
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)—— OpenCV 默认读取 BGR，别用RGB2GRAY -
scaleFactor太大（如 1.5）会跳过小尺度人脸，建议从1.1开始试；太小（如 1.01）则耗时爆炸且误检多 -
minNeighbors控制置信度，默认3偏保守，光照好时可降到2；但设成0或1会导致大量噪点框 - 确保输入图像分辨率不过低：Haar 对小于 60×60 像素的人脸基本无响应，必要时先 resize
Python 中反复加载同一个 XML 影响性能
cv2.CascadeClassifier() 初始化开销不小，尤其在循环或 Web 请求中每次 new 一个新实例，会拖慢整体速度。
- 把分类器对象作为模块级变量或类属性初始化一次，复用它 —— 它是线程安全的（OpenCV 4.x）
- 别在函数里写
detector = cv2.CascadeClassifier(...)，除非你明确要隔离状态 - 如果需支持热更新（比如换不同分类器），用 LRU cache 或显式管理生命周期，而不是靠反复 new
