手动编译安装CBOR扩展需五步：一、克隆janez83/cbor-php源码；二、执行phpize生成configure脚本；三、运行./configure并指定php-config路径；四、make编译后sudo make install安装so文件；五、在php.ini中添加extension=cbor.so并验证加载。
PHP怎么安装CBOR扩展才能用
PHP原生不支持CBOR，必须装第三方扩展。最成熟的是 cbor 扩展（由 @janez83 维护），不是 PECL 官方收录的，得手动编译。如果你用的是 PHP 8.0+，别选老版本的 php-cbor（已停更、不兼容 JIT），直接上 cbor 扩展。
常见错误现象：Call to undefined function cbor_encode() —— 这说明扩展根本没装成功，不是代码写错了。
- Linux 下：克隆
https://github.com/janez83/cbor-php，进目录执行phpize && ./configure && make && sudo make install，然后在php.ini加extension=cbor - macOS（Homebrew + php@8.2）：先确认
php-config路径对不对，which php-config输出要和phpize匹配，否则make会链接错 Zend 头文件 - Docker 环境：别用
apt install php-cbor（Ubuntu 源里那个是过时的旧包），坚持源码编译
cbor_encode() 和 cbor_decode() 的参数陷阱
cbor_encode() 默认把 PHP 数组转成 CBOR map（键必须是字符串），但如果你传的是纯数字索引数组，它会自动转成 CBOR array —— 这点和 JSON 一致，但容易被忽略。真正踩坑的是 cbor_decode() 的第二个参数：$assoc。
它不像 json_decode($str, true) 那样只控制“是否返回关联数组”，而是控制“是否把 CBOR map 解为 PHP array”。如果 CBOR 数据里有标签（tag），比如时间戳 6 或 bignum 2，$assoc = true 会丢掉 tag 信息，直接当普通值处理。
立即学习“PHP免费学习笔记（深入）”；
- 想保留 tag？必须设
$assoc = false，这时返回的是Cbor\Map、Cbor\Tag等对象，需调用->getValue()或->getTag() - 解一个不含 tag 的配置数据？
cbor_decode($data, true)最省事 - 注意：
cbor_decode()遇到损坏数据默认静默返回null，加第三个参数true可抛异常：cbor_decode($data, true, true)
PHP里怎么处理 CBOR tag（比如时间戳、二进制）
CBOR tag 是语义增强的关键，比如 0 表示 UTF-8 字符串（通常不用显式标），1 表示 UNIX 时间戳（64位浮点或整数），2/3 表示 bignum。PHP 的 cbor 扩展不会自动转换 tag 1 为 DateTime 对象，得自己判断。
典型场景：你收到一个带 tag 1 的 CBOR blob，想转成可读时间。
- 先用
cbor_decode($data, false)得到原始结构 - 检查是否是
Cbor\Tag实例：if ($val instanceof Cbor\Tag && $val->getTag() === 1) - 再取值：
$ts = $val->getValue()，它可能是 int 或 float，用new DateTime("@$ts")构造 - 二进制（tag 2/3）同理，
$val->getValue()返回的是string，但内容是原始字节，不是 base64
性能和兼容性要注意什么
CBOR 比 JSON 小、解析快，但 PHP 扩展层有开销。实测 10KB 数据，cbor_decode() 比 json_decode() 慢约 15–20%，主要耗在对象封装（尤其是带 tag 时）。如果你只传简单结构体，又追求极致性能，可以关掉 tag 支持：编译扩展时加 --disable-cbor-tags，这样 cbor_decode() 总是返回原生 PHP 类型，不生成 Cbor\* 对象。
跨语言兼容性方面，PHP 的 cbor 扩展默认用 deterministic 编码（map key 排序、无浮点 NaN），这点和 Go 的 go-cbor、Rust 的 minicbor 一致，但和 Python 的 cddl 默认行为不同——如果对方用非 determinstic 模式编码 map，PHP 解出来 key 顺序可能不一致（虽然语义不变）。
最常被忽略的一点：CBOR 的 “undefined” 值（type 7, value 23）在 PHP 扩展中被映射为 null，但某些设备固件会用它表示“字段未设置”，而 PHP 的 null 和 “显式设为 null” 无法区分。需要业务层额外加标记字段，或者改用 optional tag（如 tag 24）来规避。
