EasyWeChat 官方账号临时素材（media）上传与下载实战指南

后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载临时素材是微信公众号开发中最常用的基础能力之一无论是群发消息、客服消息还是自定义菜单、自动回复中的图片、语音、视频都需要先将文件上传到微信服务器换取media_id。本篇指南以 EasyWeChat 4.x 文档《临时素材》为核心骨架结合当前仓库w7corp/easywechat的源码实现src/OfficialAccount/Application.php、src/Kernel/HttpClient/AccessTokenAwareClient.php逐层拆解从素材格式与大小限制、四类基础上传方法到群发视频的上传与素材创建、二进制流的保存下载再到请求底层如何自动携带access_token、如何判断失败并触发重试帮助读者一次性掌握临时素材的完整链路。临时素材是什么类型、格式与大小限制临时素材Temporary Media指通过微信接口上传后由微信服务器临时保存的多媒体文件。EasyWeChat 中通过$app-media入口调用上传成功的素材会返回media_id供后续创建消息、群发等场景使用。上传的临时多媒体文件有严格的格式和大小限制EasyWeChat 4.x 文档给出的官方约束如下素材类型大小限制格式要求图片image2MJPG语音voice2M播放长度不超过 60sAMR/MP3视频video10MBMP4缩略图thumb64KBJPG上述限制来自 docs/src/4.x/basic-services/media.md 原文。实际开发中请以微信开放平台最新公告为准并尽量在上传前于应用层做好文件类型与大小的前置校验避免无谓的接口调用。与永久素材$app-material见 docs/src/4.x/official-account/material.md不同临时素材适合一次性使用的场景例如客服消息中的图片、群发前的视频中转等。上传前请注意微信图片上传服务带有敏感内容检测系统图片若含色情、商品推广、虚假信息等内容上传可能失败。前置准备初始化 Application 与 media 入口$app-media并不需要单独实例化它由 src/OfficialAccount/Application.php 统一装配。从源码可见官方账号应用的核心配置项包括app_id、secret应用凭据用于构建Account与AccessToken见 getAccount() 与 getAccessToken()token、aes_key消息加解密所需require_encryption控制是否强制加密见 getServer()http.retry/http.max_retries/http.throwHTTP 重试与异常抛出策略。所有对微信 API 的请求都经由 createClient() 创建AccessTokenAwareClient发起其base_uri固定为https://api.weixin.qq.com/见 getHttpClientDefaultOptions()因此文档中的uploadImage、get等方法内部会自动拼接出完整的微信接口 URL。使用前仅需use EasyWeChat\OfficialAccount\Application; $config [ app_id your-app-id, secret your-secret, token your-token, aes_key your-aes-key, // http [ // retry true, // 是否开启自动重试 // max_retries 2, // 最大重试次数默认 2 // throw true, // 请求失败是否抛出异常默认 true // ], ]; $app new Application($config);上传图片、语音、视频与缩略图上传图片$app-media-uploadImage($path);$path为本地文件路径。由于 PHP 的相对路径受当前工作目录影响强烈建议传入绝对路径这一经验同样适用于永久素材参见 docs/src/3.x/material.md 中的提示例如使用__DIR__ . /stubs/image.jpg的方式构造路径避免因脚本执行目录不同导致文件找不到。上传语音$app-media-uploadVoice($path);语音素材受 2M 大小与 60 秒播放时长限制仅支持AMR与MP3格式请在调用前自行校验。上传视频视频上传需要同时提供标题与描述$app-media-uploadVideo($path, $title, $description);注意视频接口的限制是 10MB 且为MP4格式超过该大小会上传失败。上传缩略图缩略图通常用于视频封面或音乐封面$app-media-uploadThumb($path);缩略图限制为 64KB仅支持JPG格式。上传群发视频群发场景下的视频处理与普通视频上传不同需要先通过uploadVideoForBroadcasting获取专门的media_id$app-media-uploadVideoForBroadcasting($path, $title, $description); //{ // media_id: rF4UdIMfYK3efUfyoddYRMU50zMiRmmt_l0kszupYh_SzrcW5Gaheq05p_lHuOTQ, // title: TITLE, // description: Description //}返回结果中的media_id即用于创建群发消息的素材凭证。创建群发消息素材与上传群发视频的区别这一小节最容易被混淆请务必区分两个概念上传群发视频uploadVideoForBroadcasting把本地视频文件上传到微信服务器拿到media_id创建群发消息素材createVideoForBroadcasting用上一步拿到的media_id加上标题、描述创建一条视频消息素材用于真正发送给用户。$app-media-createVideoForBroadcasting($mediaId, $title, $description); //{ // type:video, // media_id:IhdaAQXuvJtGzwwc0abfXnzeezfO0NgPK6AQYShD8RQYMTtfzbLdBIQkQziv2XJc, // created_at:1398848981 //}完整的群发链路可以参考 docs/src/4.x/official-account/broadcasting.md 中的视频消息示例// 1. 先上传视频素材用于群发 $video /path/to/video.mp4; $videoMedia $app-media-uploadVideoForBroadcasting($video, 视频标题, 视频描述); // 2. 使用上面得到的 media_id 群发视频消息 $app-broadcasting-sendVideo($videoMedia[media_id]);获取临时素材内容并保存为本地文件对于图片、语音等二进制流内容get()返回的是EasyWeChat\Kernel\Http\StreamResponse实例可直接保存到本地$stream $app-media-get($mediaId); if ($stream instanceof \EasyWeChat\Kernel\Http\StreamResponse) { // 以内容 md5 为文件名存到本地 $stream-save(保存目录); // 自定义文件名不需要带后缀 $stream-saveAs(保存目录, 文件名); }两点使用要点save($directory)会自动以响应内容的 md5 值作为文件名适合批量落盘、按内容去重的场景saveAs($directory, $filename)允许自定义文件名且无需携带文件后缀系统会自动补全。同样的StreamResponse保存模式也出现在永久素材与小程序码等场景中见 docs/src/4.x/official-account/material.md 与 docs/src/4.x/mini-program/app_code.md掌握这一模式即可举一反三。获取 JSSDK 上传的高清语音微信 JS-SDK 通过wx.uploadVoice上传的高清语音属于另一套素材接口需使用getJssdkMedia获取$stream $app-media-getJssdkMedia($mediaId); $stream-saveAs(保存目录, custom-name.speex);这类语音为speex格式保存时建议显式指定.speex后缀注意此方法不会自动补全后缀。源码视角media 请求是如何走到微信 API 的虽然当前仓库未单独提供Media类文件但结合 src/OfficialAccount/Application.php 与 src/Kernel/HttpClient/AccessTokenAwareClient.php 可以还原完整调用链$app-media经由应用容器的魔术方法分发到createClient()创建的AccessTokenAwareClient实例所有未明确定义的方法如uploadImage通过 __call() 委托给底层 Symfony HttpClient在 request() 中客户端会自动将当前 access token 以 query 参数形式附加到请求$options[query] array_merge(..., $this-accessToken-toQuery())因此业务代码无需手动携带 token请求体经RequestUtil::formatBody()规范化JSON / multipart 等后发出返回结果被包装为 src/Kernel/HttpClient/Response.php并通过failureJudgeerrcode非 0 即判定失败见 createClient()与http.throw配置决定是否抛出异常若配置了http.retry当响应内容同时出现42001与access_token expired时会触发 AccessTokenExpiredRetryStrategy 的自动重试换取新 token 后重新发起请求——这为临时素材上传等高频操作提供了额外的健壮性。常见问题与注意事项素材类型与大小不符图片仅JPG、语音仅AMR/MP3≤60s、视频仅MP4≤10MB、缩略图仅JPG≤64KB上传前先做本地校验敏感内容拦截图片含色情、商品推广、虚假信息等内容时上传可能失败需引导运营规避路径问题$path尽量使用绝对路径防止脚本工作目录变化导致文件定位失败群发视频两步骤不要混用先uploadVideoForBroadcasting拿media_id再createVideoForBroadcasting建消息素材最后$app-broadcasting-sendVideo($mediaId)发送完整示例见 docs/src/4.x/official-account/broadcasting.md二进制响应get()/getJssdkMedia()返回StreamResponse务必用instanceof判断后再调用save()/saveAs()保存saveAs自定义文件名时无需带后缀。至此从素材限制、上传方法、群发衔接到下载保存与底层请求机制EasyWeChat 的临时素材能力已全部覆盖可直接用于生产开发。赞分享后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载相关推荐EasyWeChat 5.x 临时素材Media完整指南上传、群发视频与下载全流程EasyWeChat 5.x 临时素材Media完整指南上传、群发视频与下载全流程 本篇指南基于 EasyWeChat 5.x 官方文档「临时素材」章节展后端即时通讯企业微信临时素材上传与下载实战EasyWeChat 4.x 企业微信 media 接口全解企业微信临时素材上传与下载实战EasyWeChat 4.x 企业微信 media 接口全解 本篇技术指南聚焦 EasyWeChat 4.x 中企业微信WeC后端即时通讯EasyWeChat 3.x 素材管理完全指南永久素材与临时素材的上传、获取与管理实战EasyWeChat 3.x 素材管理完全指南永久素材与临时素材的上传、获取与管理实战 在微信公众号开发中图片、语音、视频等多媒体文件必须先上传到微信服务器后端即时通讯上一篇Data-Science-For-Beginners Docker容器VSCode远程开发环境配置下一篇EmulatorJS浏览器游戏模拟器终极指南5分钟搭建个人复古游戏平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考