package_body_offset是Swoole TCP服务器启用长度检测协议时指定包体起始位置的配置项，决定onReceive回调中$data是否已剔除包头；需与package_length_offset协同使用，否则会导致截断、错位或空数据。

package_body_offset 是什么

package_body_offset 是 Swoole TCP 服务器在启用长度检测协议（open_length_check => true）时，用来告诉底层「包体从第几个字节开始」的配置项。它不参与数据解析逻辑本身，只影响底层如何截取有效载荷——换句话说，它决定 onReceive 回调里收到的 $data 是不是已经去掉了包头。

为什么 package_body_offset 要和 package_length_offset 配合使用

这两个偏移量必须协同工作，否则会直接收不到完整包体，甚至触发 package_max_length 截断或静默丢包。

• package_length_offset 指明「长度字段从哪开始」，比如设为 0 表示前 4 字节是包长（package_length_type => 'N'）
• package_body_offset 指明「真正业务数据从哪开始」，比如设为 4 表示跳过前 4 字节长度字段，后面才是正文
• 如果 package_body_offset 小于 package_length_offset + 长度字段字节数（如 0 + 4），会导致包体被截断或错位
• 如果设得过大（比如长度字段只有 4 字节，却设 package_body_offset => 8），那么前 4 字节长度字段之后的 4 字节会被当成“冗余头”，实际业务数据就少了

常见错误：body offset 设错导致 onReceive 收到空字符串或乱码

典型现象是：onReceive 里 $data 长度恒为 0，或者内容始终少开头若干字节。这往往是因为：

Swoole 6.1.1

Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。

下载

• 客户端发的是「4 字节长度 + 2 字节魔数 + JSON body」，但服务端只设了 package_length_offset => 0、package_body_offset => 4，漏掉了中间 2 字节魔数，导致 body 偏移错 2 位
• 误把 package_body_offset 当成「整个包头长度」来填，而没考虑魔数、版本号等额外字段
• 用了 package_start_symbol（如魔数 0x12345678），但该字段只支持单字节符号，多字节魔数必须靠 package_body_offset 手动跳过——此时 offset 必须包含魔数字节数

怎么验证 offset 是否正确

最直接的办法是在 onReceive 中打印原始二进制数据的十六进制表示：

echo bin2hex($data) . "\n";

对照你协议定义的结构逐字节比对：长度字段是否在预期位置？魔数是否紧随其后？业务数据是否从 package_body_offset 开始？只要 hex 输出中能清晰看到「长度值 → 魔数 → 实际 JSON/XML/protobuf」的顺序，且起始位置与配置一致，就基本没问题。

复杂点在于，一旦协议里混入可选字段、压缩标记或校验位，package_body_offset 就不再是固定常量，而得结合长度字段动态计算——这时候 Swoole 的静态配置就不够用了，得退回到手动缓存 + 自定义解析。