OpenCV FileStorage读YAML/XML必须显式指定FileStorage::READ模式，否则静默失败；中文路径需UTF-8转码；嵌套访问须逐级检查empty()；opencv-matrix须用read()而非>>；多线程需独立实例。
OpenCV的FileStorage读取YAML/XML必须用FileStorage::READ模式
直接用FileStorage构造时传入文件路径却不指定标志，会默认以写入模式打开——此时读取失败且不报错，只会静默返回空数据。这是最常踩的坑。
正确做法是显式传入FileStorage::READ（或简写为cv::FileStorage::READ）：
cv::FileStorage fs("config.yaml", cv::FileStorage::READ);
if (!fs.isOpened()) {
// 这里会触发：路径错、权限不足、格式非法都进这里
}
- YAML和XML路径相同，仅靠后缀和内容识别格式，无需额外指定
- 若文件含中文路径，在Windows上需先用
cv::utils::fs::canonical转为UTF-8字符串（OpenCV 4.5.2+），旧版本建议用std::filesystem::u8path转码 - XML中注释（
<!-- ... -->）会被忽略，YAML中#行注释同理
读取嵌套结构时必须用operator[]逐级访问节点
OpenCV不支持类似JSON Pointer的扁平化路径（如"camera.intrinsics.fx"），所有嵌套都得手动展开。一旦某级节点不存在，operator[]返回空FileNode，后续调用operator>>会崩溃。
cv::FileStorage fs("config.yaml", cv::FileStorage::READ);
cv::FileNode root = fs.root();
cv::FileNode cam = root["camera"]; // 若无camera字段，cam为空
double fx = cam["intrinsics"]["fx"].real(); // 空节点调用real()会abort
- 务必每级都检查
!node.empty()，尤其在生产环境 -
FileNode::type()可判断类型：FileNode::NONE（空）、FileNode::REAL、FileNode::INT、FileNode::STRING、FileNode::SEQ（数组）、FileNode::MAP（对象） - 读取数组推荐用迭代器：
for (cv::FileNodeIterator it = node.begin(); it != node.end(); ++it)，避免索引越界
YAML里用!!opencv-matrix导出的矩阵需用read()而非operator>>
OpenCV用write()保存Mat时，默认加YAML tag !!opencv-matrix。这种格式不能直接用node >> mat，否则mat尺寸为0且无报错。
立即学习“C++免费学习笔记（深入）”；
必须用cv::FileNode::read(Mat&)成员函数：
cv::Mat K;
cv::FileNode K_node = root["K"];
if (!K_node.empty() && K_node.type() == cv::FileNode::MAP) {
K_node >> K; // ❌ 错误：对带tag的matrix无效
K_node.read(K); // ✅ 正确：自动识别opencv-matrix并解析
}
- XML中同理，
<K type_id="opencv-matrix">节点也必须用read() - 若想绕过tag、用纯数值方式读写，保存时加
cv::FileStorage::WRITE_MAT_AS_LIST标志，读取时就能用>> -
read()只支持Mat，不支持cv::Vec3d等轻量类型，后者仍要用>>
多线程读配置必须每个线程独立FileStorage实例
FileStorage内部有非线程安全的解析状态（比如YAML parser的当前层级栈），共享单个实例并发读会导致段错误或数据错乱，哪怕只是多个线程同时调用root()也不行。
- 不要把
FileStorage作为全局变量或静态成员 - 高频读场景下，考虑一次性读入内存（如
std::map<std::string, double>），之后只操作内存结构 - 若配置极小（cv::utils::fs::readFileToString读原始文本再解析，比反复打开文件更快
YAML/XML解析本身不慢，但OpenCV的FileStorage对异常格式容忍度低——一个缩进错、一个冒号漏，就直接abort()。真要稳定，得先用yaml-cpp或pugixml做预检，再交由OpenCV读取。
