MVT是自定义编码的Protocol Buffers二进制格式，非标准protobuf IDL生成，直接用protoc解析会失败；推荐使用mapbox/vector-tile库（header-only，基于protozero，支持visitor模式和完整坐标/属性解码）。
什么是 MVT，为什么 C++ 解析它不推荐直接手撸
MapBox 矢量切片（MVT）本质是 Protocol Buffers 编码的二进制格式，但**不是标准 protobuf IDL 生成的常规 message**——它使用自定义的、紧凑的、无 schema 的编码规则（比如 zigzag varint、packed deltas、字段 ID 隐式约定）。直接用 protoc 生成 C++ 类解析会失败，因为官方 .proto 文件（mvt.proto）仅作参考，实际切片中字段 ID 和重复策略与标准解析器预期不符。
真正可行的路径只有两条：用成熟封装库（如 mapbox/vector-tile），或基于 protobuf-cpp 手动解包 + 按 spec 逐字段 decode。后者调试成本极高，且易因版本差异（如 Mapbox GL JS v2 vs v3 切片格式微调）出错。
- 不要尝试用
protoc --cpp_out=.编译官方mvt.proto后直接ParseFromArray()—— 大概率触发parse error: truncated message或字段全为 0 - 切片中的
features是 repeated，但编码时往往用 packed varint 序列，而非标准 repeated 字段头；geometry是纯整数指令流（MoveTo/LineTo/ClosePath），需状态机解码 - 坐标是 delta 编码 + zigzag + 量化到 16-bit 整数（默认 extent=4096），还原需按顺序累加并除以
extent
用 mapbox/vector-tile C++ 库解析最省心
mapbox/vector-tile 是 Mapbox 官方维护的轻量 C++ 解析器（header-only，依赖 protozero），专为 MVT 设计，绕过 protobuf runtime，直接解析二进制流。它不生成对象树，而是通过 visitor 模式回调每层数据，内存友好且兼容主流 MVT 版本。
使用前需确认：你的构建环境支持 C++14（最低要求），且已引入 protozero（它作为子模块被包含）。
立即学习“C++免费学习笔记（深入）”；
- 克隆方式：
git clone --recursive https://github.com/mapbox/vector-tile.git，注意--recursive拉取protozero - 关键头文件是
vector_tile.hpp，解析入口为vector_tile::tile类，构造时传入原始char*和长度 - 遍历图层用
for (const auto& layer : tile.layers())；每个layer提供name()、version()、extent() - 读 feature 需绑定 visitor：调用
layer.features().for_each([&](const vector_tile::feature& f) { ... })，其中f.geometry()返回指令迭代器，f.attributes()是 key-value 对（key 是整数索引，需查layer.keys()和layer.values()）
#include "vector_tile.hpp"
// ...
std::string data = /* raw MVT bytes */;
vector_tile::tile tile(data.data(), data.size());
for (const auto& layer : tile.layers()) {
std::cout << "Layer: " << layer.name() << "\n";
layer.features().for_each([&](const vector_tile::feature& f) {
// geometry 解码需手动处理指令流
auto geom = f.geometry();
while (geom.is_valid()) {
auto cmd = geom.command();
auto count = geom.argument();
// cmd == 1 → MoveTo, 2 → LineTo, 7 → ClosePath...
geom.next();
}
});
}
geometry 指令流解码最容易出错的三个点
MVT 的 geometry 不是坐标数组，而是一串“绘图指令+参数”，必须按顺序执行并维护当前坐标（x, y）状态。新手常卡在坐标还原和指令边界上。
- 指令格式：低 3 位是 command（
cmd & 0x7），高 29 位是 count（cmd >> 3）；count 表示后续多少个参数对（每个参数是单个 varint） - 参数是 delta 编码：第一个
x是绝对值，之后所有x、y都是相对于上一个坐标的差值；且全部经 zigzag 解码（(val >> 1) ^ (-(val & 1))） - 最终坐标 =
(accumulated_delta * 1.0 / layer.extent())，不是直接除 4096——因为layer.extent()可能被设为其他值（如 256 或 8192）
漏掉 zigzag 或误把 count 当坐标数，会导致整个多边形扭曲或崩溃。建议直接复用 mapbox/vector-tile 内置的 vector_tile::geometry::points 辅助类，它已封装完整解码逻辑。
属性（attributes）查表机制必须手动配对
MVT 为节省体积，不存字符串 key 和 value，而是存整数索引：feature 中的每个 attribute 是 key_id 和 value_id，真实字符串需查图层的 keys()（std::vector<std::string>）和 values()（std::vector<variant>，含 string/float/int/bool/null）。
- 若
key_id >= layer.keys().size()，说明数据损坏或版本不匹配，应跳过该 attribute -
values()中的string_value是直接存储的 UTF-8 字符串；double_value是 IEEE754 双精度（注意平台字节序，但通常无需干预） - 没有
feature.id()字段？那是正常的——MVT 规范里id是可选字段，很多服务（如 Mapbox Tilesets）根本不开，不能假设存在
真正麻烦的是嵌套结构：MVT 不支持 object/array 类型，JSON-like 属性（如 {"type": "Point", "coordinates": [102, 0.5]}）必须由上层业务自行序列化为字符串再存入 value_id，解析时得额外 JSON parse。
