JSON · fetch · cURL · Python · PHP

Base64 API 上传

生成通过 API 上传文件所需的 Base64 JSON 载荷。上传文件、设置字段名，即可获得可直接复制的 JavaScript、cURL、Python 和 PHP 代码。

Base64 API 载荷生成器

拖拽文件到此处或点击选择

支持任意文件类型 — 最大 25 MB

💡

Base64 适用场景：当 API 仅接受 JSON 且文件体积较小（500 KB 以内）时，Base64 是合适的选择。对于大文件，multipart/form-data 通常更高效——无体积开销、支持流式传输，服务器内存占用也更低。

适合在 API 中使用 Base64 的场景

✓
仅支持 JSON 的 API
API 只接受 application/json，没有 multipart/form-data 端点。此时嵌入 Base64 是唯一的选择。
✓
小文件（< 500 KB）
图标、缩略图、短音频片段、小文档等。约 33% 的体积开销可以接受，载荷大小也在可控范围内。
✓
原子请求
需要在单个 JSON 请求体中同时发送文件和元数据——例如带有收件人信息的邮件附件。
✓
Webhook 回调
第三方 Webhook 在 JSON 通知载荷中内联传递文件内容，而非提供下载 URL。

不适合在 API 中使用 Base64 的场景

✗
大文件（> 1 MB）
一个 5 MB 的 PDF 会变成约 6.7 MB 的 Base64 文本。这会增加内存占用、拖慢 JSON 解析速度并浪费带宽。
✗
流式上传
JSON 中的 Base64 无法流式传输。服务器必须接收并解析完整的 JSON 请求体后才能处理文件。
✗
多文件上传
在一个 JSON 载荷中以 Base64 发送 10 张图片会产生极大的请求体。请改用 multipart/form-data。
✗
性能敏感场景
Base64 编解码和 JSON 解析会带来额外的 CPU 开销。对于文件上传 API，二进制传输的吞吐量更高。

Base64 JSON vs multipart/form-data

根据使用场景选择合适的上传方式。

对比项	Base64 JSON	multipart/form-data
体积开销	比二进制大 +33%	极小（约字节边界）
Content-Type 请求头	application/json	multipart/form-data
小文件（< 500 KB）	✓ 适合	✓ 适合
大文件（> 1 MB）	✗ 不推荐	✓ 推荐
文件 + JSON 元数据一次请求	✓ 简便	需处理 boundary 解析
上传进度追踪	✗ 不支持	✓ 支持
服务端流式处理	✗ 需接收完整请求体	✓ 可流式处理各部分
CDN / 代理缓存	✗ POST 请求体不缓存	✗ POST 请求体不缓存

使用 Base64 的常见 API 错误

这些错误会在生产环境中引发难以排查的 bug。

✗

将超过 1 MB 的文件以 Base64 发送

一张 2 MB 的图片会变成约 2.7 MB 的 Base64 文本。JSON 解析器必须将整个字符串加载到内存中，高并发时会导致响应变慢和内存占用飙升。

✗

对二进制文件直接使用 btoa()

btoa() 只能处理 Latin-1 字符。对于二进制文件（PDF、图片、ZIP），必须先将文件读取为 ArrayBuffer 而非文本，再转换为 Base64。本工具通过 FileReader 正确处理了这一点。

✗

忘记设置 Content-Type: application/json

没有此请求头，许多服务器（Express、FastAPI、Rails）将不会把请求体解析为 JSON。请求虽然到达了处理函数，但请求体字段会是 undefined 或空值。

✗

未在服务端验证 MIME 类型

客户端可以发送任意 MIME 类型字段值。务必在服务端重新验证实际文件内容——不要信任客户端传来的 mimeType 字段。

✗

对 Base64 字符串二次编码

如果将已经 Base64 编码的字符串再次编码，结果看起来有效，但服务端无法正确解码。请确保始终从原始二进制数据开始编码，而非从已有的 Base64 字符串编码。

常见问题

Base64 是通过 API 发送文件的好方式吗？

取决于文件大小和 API 设计。对于仅支持 JSON 的 API 中的小文件（500 KB 以内），Base64 效果不错。对于较大文件或高并发上传端点，multipart/form-data 更高效，因为它避免了 33% 的体积开销，并支持流式传输。