FIT文件是Garmin定义的紧凑二进制协议，含动态字段编码、压缩字典和CRC校验，必须用官方fit-sdk（C++版）解析，不可直接用fread或std::ifstream::read硬读；其Decode类支持流式解析、自动校验、多态消息分发，并需通过IsFieldDefined检查字段是否存在，GPS坐标需转十进制度，海拔单位为cm。
FIT 文件不是普通二进制，得用官方 SDK 解析
直接用 fread 或 std::ifstream::read 读 FIT 文件只会看到乱码或校验失败——FIT 是 Garmin 定义的紧凑二进制协议，含动态字段编码、压缩字典和 CRC 校验。硬解析极易出错，也不值得重复造轮子。
官方 fit-sdk（C++ 版）是唯一稳定选择，它已处理了：字段类型映射（如 uint16 vs si_float）、时间戳解码（timestamp_ms 转 Unix 时间）、消息类型多态分发（record / lap / session 等）。GitHub 上搜 garmin/fit-sdk 下载最新 release，解压后 include/ 和 src/ 目录即用。
- 别用第三方非官方解析器（如某些 Python 的
fitparse移植版），C++ 生态里它们普遍不维护、不支持新字段（如跑步动态stance_time_balance） -
fit-sdk不依赖 Boost 或 C++17，C++11 即可编译；但注意默认不开启异常，若需错误抛出，编译时加-DFIT_USE_EXCEPTIONS=ON - 头文件路径要包含
include/，链接时需编译src/下的fit.cpp、fit_buffered_record_mesg.cpp等（见 SDK 中的CMakeLists.txt）
用 Decode 类读取文件，别自己写循环解析
SDK 提供 fit::Decode 类封装全部底层逻辑，传入 std::istream* 即可触发完整解析流程。手动逐字节解析 header + data + footer 不仅冗长，还会漏掉字节对齐、局部消息定义（LDM）等细节。
典型用法：
立即学习“C++免费学习笔记（深入）”；
fit::Decode decoder;
decoder.AddEventListener(&my_listener); // 自定义监听器
std::ifstream file("activity.fit", std::ios::binary);
if (!decoder.CheckFileIntegrity(file)) {
// 报错：CRC 失败或文件截断
}
file.clear();
file.seekg(0);
decoder.Decode(file); // 触发所有回调
-
CheckFileIntegrity必须在Decode前调用，否则可能跳过 CRC 校验导致静默解析错误 - 监听器类必须继承
fit::Listener并重载OnRecord、OnLap等虚函数；不要试图在OnMesg里做耗时操作（如写磁盘），FIT 文件中record消息可能每秒上百条 - 若文件来自旧设备（如 Forerunner 220），注意其时间戳为本地时区偏移，SDK 默认按 UTC 解码；需手动用
local_timestamp字段或设备配置补正
record 消息字段缺失很常见，必须检查 IsFieldDefined
FIT 协议允许设备按需省略字段（例如心率带未连接时，heart_rate 字段完全不出现），所以不能假设 mesg.GetFieldValue("heart_rate") 一定返回有效值。直接访问未定义字段会触发 std::out_of_range 异常（若启用了异常）或返回 0（默认行为）。
正确做法是先判断再取值：
if (mesg.IsFieldDefined(fit::RECORD_MESG_HEART_RATE)) {
uint8_t hr = mesg.GetHeartRate();
// ...
}
if (mesg.IsFieldDefined(fit::RECORD_MESG_SPEED)) {
float speed = mesg.GetSpeed(); // 单位 m/s
}
-
fit::RECORD_MESG_XXX是宏定义的字段 ID，比字符串查找快且类型安全；不要用mesg.GetFieldByName("speed") - 速度、功率等数值字段单位固定（
speed是 m/s，power是 watt），无需额外换算；但海拔altitude是 cm，需除以 100.0 - GPS 坐标字段（
position_lat/position_long）是半度（semicircle）单位，必须转为十进制度：lat_deg = lat_semi * 180.0 / 0x7FFFFFFF
内存和性能：大文件别全加载，用流式解析
一个 2 小时骑行 FIT 文件可达 5–10 MB，全部读入内存再解析既浪费又无必要。fit::Decode 原生支持流式处理，只要 std::istream 支持 seekg 和 read（std::ifstream 满足），就能边读边解，峰值内存仅几百 KB。
- 避免用
std::stringstream或std::vector<char></char>全局加载——这会让解析变慢 3–5 倍，且失去对超大文件（>100 MB）的兼容性 - 若需随机访问（如跳到第 N 个
record），FIT 不支持索引，只能顺序解析并计数；建议解析时缓存关键 offset（如每个lap开始位置）到外部结构 - Android NDK 或嵌入式环境注意：SDK 默认使用
std::vector存储临时消息，可重载fit::MemoryPool替换为静态缓冲区，避免 heap 分配
真正麻烦的是多设备数据融合——比如手表记录的 record 和骑行台导出的 record 时间戳精度不同（毫秒级 vs 10 毫秒级），对齐时不能只比 timestamp 字段，得结合 timestamp_ms 和设备固件版本查文档确认采样策略。
