图片、语音、视频与文件
图片
js
await ctx.replyImage('https://example.com/a.png');视频、音频、文件
js
await ctx.replyVideo('https://example.com/a.mp4');
await ctx.replyAudio('https://example.com/a.mp3');
await ctx.replyFile('https://example.com/a.pdf');或统一使用:
js
await ctx.replyMedia(url, 'image' | 'video' | 'audio' | 'file');媒体要求
- 必须是 QQ 服务端可访问的公网 HTTPS 地址
- 不能传本地路径
- 不能传 base64(
replyMedia) - 大文件受 QQ 文件大小限制
音频说明
QQ 语音有时长限制。平台的策略:
- 55 秒以内:继续按语音发送
- 超过 55 秒:优先发送完整音频文件
- 文件失败:回退为语音(短音频场景)
长音频完整播放需要走文件或外部链接,不能强行用语音。
外链转存
js
const stableUrl = await ctx.rehost('https://example.com/a.png');
await ctx.replyImage(stableUrl);用于把临时外链转存到平台媒体目录,减少过期/防盗链问题。
主动媒体
js
await ctx.sendGroupMedia(groupId, url, 'image');
await ctx.sendPrivateMedia(userId, url, 'image');上传方法
js
ctx.uploadImage(url)
ctx.uploadVideo(url)
ctx.uploadAudio(url)
ctx.uploadFile(url)当前做公网 URL/SSRF 校验并返回可发送地址,不是把本地文件读入沙箱。
常见失败
| 现象 | 原因 |
|---|---|
| 图片不显示 | URL 不可公网访问 / 防盗链 |
| 语音失败 | 时长超限 / 格式不支持 |
| 文件失败 | 超过 QQ 文件限制 / URL 失效 |
| 无回复 | 本插件 2 条回复额度或 QQ 5 条总额度已用尽 |
