Bun HTTP客户端在空请求体时意外添加Transfer-Encoding头的问题分析

在Bun 1.2.6版本之后，HTTP客户端在处理POST请求时出现了一个兼容性问题。当开发者发送一个没有请求体的POST请求时，Bun会自动添加"Transfer-Encoding: chunked"头，而不是像Node.js那样添加"Content-Length: 0"头。这个行为变化导致了一些依赖特定HTTP头行为的应用程序出现问题。

问题现象

通过一个简单的HTTP服务器和客户端测试代码可以重现这个问题。当使用Bun 1.2.7发送一个空体的POST请求时，服务器端会收到带有"Transfer-Encoding: chunked"头的请求，而不是预期的"Content-Length: 0"头。

这个问题特别影响了与Docker Engine API交互的应用程序，因为Docker Engine的ContainerStart API明确拒绝接收带有分块传输编码的空请求体，导致容器启动失败并显示错误信息："starting container with non-empty request body was deprecated since API v1.22 and removed in v1.24"。

技术背景

在HTTP协议中，对于没有主体的请求，通常有两种表示方式：

1. 使用Content-Length头设置为0
2. 使用Transfer-Encoding头设置为chunked

虽然从技术上讲这两种方式都是合法的，但许多API实现（特别是Docker Engine API）对请求头的处理有严格要求，期望看到Content-Length:0而不是分块传输编码。

Node.js的http模块一直采用第一种方式处理空请求体，而Bun在1.2.6版本后改为第二种方式，这导致了兼容性问题。

影响范围

这个问题主要影响以下场景：

1. 与Docker Engine API交互的应用程序（如testcontainers和dockerode）
2. 其他严格要求Content-Length头的API服务
3. 任何依赖Node.js默认HTTP客户端行为的代码

解决方案

对于遇到此问题的开发者，目前有以下几种临时解决方案：

1. 降级到Bun 1.2.5版本
2. 在发送请求前显式添加一个空字符串作为请求体（调用req.write('')）
3. 等待Bun团队修复此兼容性问题

从长远来看，Bun团队需要评估是否应该保持与Node.js的完全兼容，特别是在这种基础网络行为上。对于HTTP客户端来说，保持与广泛使用的实现（如Node.js）的一致性通常比技术上的灵活性更重要。

总结

这个案例提醒我们，在开发网络相关的库和工具时，即使是看似微小的行为变化也可能对上层应用产生重大影响。对于像Bun这样定位为Node.js替代品的项目，保持高度兼容性尤为重要。开发者在使用新版本的运行时或工具链时，也应该注意测试核心功能，特别是在涉及网络通信的关键路径上。