看到这类问题,我先不会急着找编码函数,第一件事是确认机器人类型,而不是改 base64 参数。钉钉机器人体系分两类:自定义 webhook 机器人和企业内部应用机器人,这两类支持的图片消息方式完全不同。
先确认机器人类型。钉钉常见的自定义机器人(webhook 方式)在消息类型中只开放 text、link、markdown、actionCard、feedCard,没有独立的 image 类型。如果你看到某些代码往 webhook 里传 imageContent 或 base64 字段,那通常不是钉钉原生的协议,很可能是封装库自造的结构。企业内部机器人(Stream 方式或旧版 API)才有 image 消息,而且真正传给服务端的是 media_id,不是 base64。
所以,如果项目文档里没有明确写出“支持 image 字段”,那这段 base64 大概率不是钉钉原生协议的一部分。封装库之所以这么设计,通常是为了让调用方少写一步上传,内部再做转换。但这种便利要经过确认,不能直接当作官方能力使用。
容易误判的地方:图片地址与图片内容
继续排查时,需要把“图片内容”和“图片访问地址”分清楚。很多失败请求来自 base64 编码了 URL,而不是图片字节。
如果目标是想把本地图片塞进消息体,首先要区分'图片内容'和'图片访问地址'。base64 处理的是图片文件的二进制内容:读取原图文件后对字节数组做 base64,得到字符串。不要对图片 URL 做 base64,也不要对文件路径做 base64,否则解码后不是图片。对自定义机器人来说,更稳妥的做法是把图片传到任意可公网访问的对象存储,再把 URL 放进 markdown 或 feedCard 的 picUrl 字段。
这里有一个容易忽略的点:自定义机器人的 markdown 和 feedCard 最终接收的是 URL,而不是图片内容。所以最省事的路径是先把图片放到对象存储,拿到公网地址,再把地址填进 picUrl。除非接口确实需要二进制内容,否则没有必要走 base64。
为什么会有这种封装?常见原因是同一套消息服务需要接多个渠道,其他渠道允许传 base64,封装层就在钉钉这边也暴露了 base64 参数。这种兼容设计容易造成“钉钉支持 base64”的错觉。实际上钉钉 webhook 不解析图片字节,它解析的是 markdown 或 actionCard 里的 URL。
base64 的格式边界与发送体积
如果还是要在某个字段里传 base64,就需要先接受两个边界:格式必须干净,体积不能太大。
base64 会让数据体积增加约三分之一,一张 5 MB 的图片编码后约 6.7 MB 字符串。钉钉对消息体长度有限制,超出会直接拒绝发送,所以不要试图把大图塞进 base64 字段。另外,base64 编码的是图片原始数据,和原图片的格式(png/jpg)无关;解码后需要按原格式保存或传输。不要在 JSON 里使用 data:image/png;base64 这种前缀,除非接口文档明确要求,否则它只是网页 src 的写法。
举个例子,Python 代码通常是下面这样处理本地图片:
import base64
with open('small.png', 'rb') as f:
raw = f.read()
b64_str = base64.b64encode(raw).decode('ascii')
b64_str = b64_str.replace('\n', '').replace('\r', '')
# 不要加 data:image/png;base64 前缀
这段代码只负责生成干净字符串,能不能发送成功,还要看接口字段名。有的封装库把 base64 放在 content 字段,有的要求同时提供 md5 或文件大小。发送之前把即将提交的 JSON 打印出来,检查字段名和值是否与接口约定一致,比反复重试更有效。
发送前的自查顺序
整理一份可执行的自查顺序,按顺序走能省去大部分调试时间。
- 确认机器人类型。在钉钉管理后台查看是自定义机器人还是企业内部应用机器人。
- 查接口定义或封装库源码,确认消息类型中是否包含 image,以及接收字段是 media_id、picUrl 还是 content。
- 对自定义 webhook,优先使用公网可访问的图片 URL,把它放进 markdown 或 feedCard 的 picUrl 字段。
- 如果确实要传 base64,先对一张几十 KB 的 PNG 做编码和解码往返测试,确认还原文件一致。
- 提交前检查 base64 字符串是否包含换行、空格或 data:image 前缀,必要时删除。
- 发送失败时,查看钉钉返回的错误码,区分“消息类型不支持”与“图片数据非法”。
这组顺序能避开大部分坑。如果错误码描述仍然模糊,抓包对比一个能成功发送的请求,字段名和值结构的差异一眼就能看出来。
稳妥的处理顺序与后续维护
如果团队里已经有一个中转服务,把收到的 base64 解码后重新上传到对象存储,再转成 URL 发给机器人,这套流程在技术上是可行的。但要注意,中转服务不能绕过钉钉对消息体大小和超时的限制。中转服务只是把“直接传 URL”变成“先存数据、再传 URL”,复杂度更高,并不会提高发送成功率。
后续维护时,建议保留一份本地测试图片和对应的 base64 样例,放在代码仓库的测试目录里。每次升级机器人 SDK 或改造封装库后,跑一次解码往返和一次测试发送,能尽早发现字段名或格式变化。