推荐API返回图片URL而非二进制流或Base64；URL方案支持缓存、追踪与复用，Base64仅适用于≤1KB无缓存需求的小图；需规范HTTP状态码、防缓存处理及MIME配置。
PHP API 返回图片时不能直接返回二进制流并声称是 JSON，这是常见误解——你得在 JSON 响应里提供图片的访问地址或 Base64 数据，而不是把图片塞进 Content-Type: application/json 里强行“返回图片”。
API 返回图片 URL 是最推荐的做法
前端需要刷新图片（比如验证码、用户头像、图表），后端不该每次返回 raw 图片字节，而应返回一个可复用、可缓存、可追踪的 URL。这样前端只需更新 src 属性即可触发浏览器重新加载。
- 后端生成图片后保存到 Web 可访问路径（如
/uploads/verify/abc123.png），并返回该相对或绝对 URL - JSON 响应结构保持标准：包含
code、message、data，其中data.url是图片地址 - 避免返回临时签名 URL 时漏掉过期时间字段，否则前端无法预判失效时机
- 注意 Web 服务器对图片后缀的 MIME 类型配置（如 Nginx 要确保
.png返回image/png）
{
"code": 0,
"message": "success",
"data": {
"url": "/uploads/verify/7f3a9c.png",
"expires_at": 1717023600
}
}
Base64 内联方式只适用于小图且无缓存需求
当图片极小（如 1KB 以内图标）、且必须避免额外 HTTP 请求时，才考虑将图片转为 Base64 放进 JSON 的 data.image 字段。但要注意：
- PHP 中用
base64_encode(file_get_contents($path))即可，但务必检查文件是否存在、是否为图片类型 - JSON 响应体积会显著增大，HTTP 响应体可能翻 3–4 倍，不适用于 >5KB 的图
- 前端需拼接前缀如
"data:image/png;base64," + base64str才能用于<img src="..."> - 浏览器不会缓存 Base64 图片，每次刷新都重新解析渲染，CPU 开销略高
状态码别乱用 200 搞定一切
API 返回图片相关数据时，HTTP 状态码要反映业务逻辑，不是所有成功都用 200 OK：
立即学习“PHP免费学习笔记（深入）”；
- 正常返回图片信息（URL 或 Base64）→
200 OK - 请求了已过期的验证码 ID →
410 Gone（比404更准确，表示资源曾存在但已不可用） - 参数缺失（如没传
type）→400 Bad Request，并在message里说明缺哪个字段 - 服务端生成图片失败（GD 库报错、磁盘满）→
500 Internal Server Error，但不要暴露堆栈，message写 “failed to generate image” 即可
前端刷新图片时防缓存是关键细节
即使后端返回了新 URL，浏览器也可能因强缓存（Cache-Control: public, max-age=31536000）继续用旧图。解决方法不是让后端关缓存，而是前端主动破：
- 给图片 URL 加时间戳参数：
img.src = data.url + '?t=' + Date.now() - 或者用随机数：
img.src = data.url + '?r=' + Math.random() - 如果后端控制 URL，建议在路径中嵌入唯一标识（如时间戳哈希或 UUID），而非依赖查询参数
- 别在 PHP 里用
header('Cache-Control: no-cache')拦截图片响应——那是干扰 CDN 和浏览器缓存策略，治标不治本
真正难的不是生成图片或拼 JSON，而是让前后端对“何时算新图”“缓存谁来管”“错误怎么退”有一致预期。URL 方案看似多一步，但省去大量边界问题；Base64 看似简单，容易在图片稍大时拖垮接口和页面性能。
