常见问题

构建时找不到 lz4 或 OpenSSL

安装开发文件：libssl-dev、liblz4-dev，以及 pkg-config（lz4 通过它查找）。Ubuntu：

sudo apt-get install -y libssl-dev liblz4-dev pkg-config

首次构建很慢

首次配置会从源码构建锁定版本的 protobuf（3.21.12）。在验证机器上 20 路并行约 47 秒。之后的增量构建不再重复这一步。

系统 protobuf 版本不对

生成代码与运行库必须是同一个 protobuf 版本。默认选项 LIXEL_OPENAPI_PROTOBUF_PROVIDER=AUTO：系统 protobuf 为 3.21.0 及以上时用系统版本，否则自动构建锁定版本。想强制用系统版本可设为 SYSTEM，强制构建锁定版本设为 FETCH。

连接 MQTTS 失败 / 证书错误

C++ 客户端默认校验服务端证书，而设备用的是自签名证书。两种处理：

• 传入设备证书：示例里用 --ca-file <证书路径>。
• 关闭校验：示例里用 --insecure（与 Python 客户端行为一致，但不校验身份，仅用于调试）。

注：这一点与 Python 不同——Python 客户端从不校验证书。

请求超时 / 无响应

Request 返回 RequestTimeout 表示超时内没有收到同 seq 的响应。确认 openapi_key 正确、请求与响应主题匹配、设备处于可响应状态。注意设备可能已执行了该请求，判断前先向设备确认。默认超时 10 秒，可用 ClientOptions::request_timeout 调整。

在订阅回调里调用 Request 没反应

这是有意的限制：订阅回调运行在 MQTT 层线程上，在回调里调用 Request 会返回 Errc::CalledFromCallback 而不是阻塞，Connect / Disconnect 也不允许在回调里调用。把需要请求的逻辑放到回调之外的线程。

点云解码失败

实时点云是 LZ4 block 格式（不是 frame）。用库提供的 DecodePointCloud 即可正确处理。Zstd 压缩的点云和负的 header.scaler 返回 Errc::Unsupported。

能在 Windows / macOS 上用吗

当前仅在 Linux 上支持与验证。其他平台、真机上的 MQTTS、ThreadSanitizer 等未验证。