HTTP 415 Unsupported Media Type — Content-Type 不匹配

症状

错误“HTTP 415 Unsupported Media Type — Content-Type 不匹配”指向一个明确的失效模式。下面依次给出症状、定位该原因的检查命令、根本原因、修复方案，以及证明修复有效的验证步骤。

可观察到的症状包括：

• API 对 POST 返回 415 Unsupported Media Type
• curl 在补充客户端遗漏的头后可用
• 框架拒绝 text/plain 或缺失的 Content-Type

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

curl -i -X POST https://api.example.com/items -d '{"a":1}'

省略头通常得到 415；加上 -H “Content-Type: application/json” 应可修复。

步骤 2

curl -i -X OPTIONS https://api.example.com/items -H 'Access-Control-Request-Headers: content-type'

预检与服务端配置可揭示端点接受哪些媒体类型。

常见诱因（按出现频率排序）：

• 请求缺少 Content-Type，或发送了解析器不接受的值
• 请求体是 JSON 却以 text/plain 发送
• 路由未配置 multipart 或厂商专用媒体类型

根因

由于请求的 Content-Type 缺失或不在端点接受的媒体类型内，服务端无法解析，遂返回 415 而不尝试读取请求体。

修复

发送正确的 Content-Type（JSON 用 application/json），确保客户端库设置它，并配置框架路由接受预期媒体类型。

注意：以 application/json 发送非 JSON 体会得到另一种解析错误；须保持头与体一致。

// fetch: set the header and body together
await fetch('/items', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ a: 1 }),
});

# multipart uploads must not hand-set Content-Type (the boundary is automatic)
curl -X POST https://api.example.com/upload -F '[email protected]'

验证

用正确 Content-Type 重试并确认 2xx；验证错误类型仍返回 415。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。