微信H5图片与语音开发全攻略：weixin-js-sdk的chooseImage、uploadVoice等媒体接口避坑指南-平芜编程栈

微信H5图片与语音开发全攻略：weixin-js-sdk的chooseImage、uploadVoice等媒体接口避坑指南

【免费下载链接】weixin-js-sdk微信官方 JS-SDK 的 CommonJS 版本，支持 TypeScript项目地址: https://gitcode.com/gh_mirrors/wei/weixin-js-sdk

weixin-js-sdk是微信官方 JS-SDK 的 npm 版本（当前 1.6.5），支持 CommonJS 与 TypeScript 类型，让开发者在 webpack、browserify 中一行require即可调用 chooseImage、uploadVoice 等媒体接口，是微信 H5 图片与语音开发的利器。

一、为什么选 weixin-js-sdk：30秒理解它的价值 🎯

官方 JS-SDK 只能以<script>标签方式引入，无法被模块化工具打包。而 weixin-js-sdk 将官方源码原样封装为 npm 包：

CommonJS / ES Module 双支持：require或import均可直接引用
TypeScript 类型完整：index.d.ts 中定义了全部接口的参数与回调签名，IDE 智能提示开箱即用
源码零魔改：index.original.js 即官方 1.6.0 源码，行为与官网文档完全一致

安装只需一条命令：

npm install weixin-js-sdk

二、如何正确初始化 config：签名是第一步也是最大坑 🔑

所有接口调用前必须完成wx.config注入，参数在 index.d.ts 第 89-97 行有完整类型定义：

参数	说明
`appId`	公众号唯一标识（必填）
`timestamp`	生成签名的时间戳（必填）
`nonceStr`	生成签名的随机串（必填）
`signature`	服务端按附录1规则计算的签名（必填）
`jsApiList`	要使用的接口列表，漏写会导致对应接口静默失败

⚠️避坑提示：jsApiList必须显式列出chooseImage、uploadVoice等你要用的接口；签名在服务端生成，切勿在前端暴露appId对应的密钥。

三、chooseImage 选图接口：参数详解与实战 📷

chooseImage用于从相册选图或拍照，类型定义见 index.d.ts 第 233-251 行：

wx.chooseImage({ count: 9, // 最多可选张数，默认9 sizeType: ['original', 'compressed'], // 原图/压缩图 sourceType: ['album', 'camera'], // 相册/相机 success: function (res) { // res.localIds：本地图片ID列表 } });

常见坑点：

localId 有生命周期：localIds只是本地临时标识，页面长时间停留或跳转后可能失效，务必及时上传
9 张是上限：count最大为 9，超出会被截断
压缩图体积更小：非高清场景建议只传compressed，上传更快

四、图片上传闭环：chooseImage → uploadImage → downloadImage 🔄

完整的图片链路在 index.d.ts 的"图像接口"区段（第 232-294 行）中依次定义：

chooseImage拿到localId
uploadImage将localId上传，成功后返回微信服务器的serverId
downloadImage用serverId反向下载回本地
getLocalImgData把localId转成 base64（localData），可直接用<img>标签展示

💡注意：uploadImage返回的serverId并非公网可访问的 URL，需要后端通过微信多媒体文件接口换取，且该文件有效期仅 3 天，务必尽快转存到自己的服务器。

isShowProgressTips参数默认为 1（显示进度提示），追求体验一致性时可显式传 0 关闭。

五、语音四步曲：startRecord → stopRecord → playVoice → uploadVoice 🎙️

语音接口同样集中在 index.d.ts 的"音频接口"区段（第 295-357 行），标准流程为四步：

startRecord：开始录音，无需参数
stopRecord：停止录音，回调中返回localId
playVoice / pauseVoice / stopVoice：播放、暂停、停止，都接收localId
uploadVoice：上传语音，返回serverId（即media_id）

wx.startRecord(); // 用户点击停止 wx.stopRecord({ success: function (res) { res.localId; // 录音本地ID } });

高频避坑清单：

录音最长 60 秒：超时会自动停止，并触发onVoiceRecordEnd的complete回调（第 309-316 行），务必监听它做 UI 复位
播放结束回调：用onVoicePlayEnd监听播放完毕，别靠setTimeout猜时长
serverId 有效期 3 天：与图片相同，后端应尽早通过多媒体接口下载转存
网络敏感：可在调用前先用getNetworkType（第 374-380 行）判断是否 2g/3g，弱网下提示用户避免上传超时

六、进阶技巧：先用 checkJsApi 探路 ✅

在调用任何媒体接口前，推荐先用checkJsApi检测当前客户端是否支持（index.d.ts 第 114-127 行）：

wx.checkJsApi({ jsApiList: ['chooseImage', 'uploadVoice'], success: function (res) { // res.checkResult 中 true 表示可用 } });

这样可在旧版本微信中优雅降级，避免接口调用直接报错。

七、项目文件速览 📁

文件	作用
index.js	CommonJS 入口，`require('weixin-js-sdk')`加载的就是它
index.original.js	微信官方 1.6.0 源码原文
index.d.ts	TypeScript 类型定义，媒体接口声明集中在第 232-381 行
package.json	包信息，入口指向`index.js`，MIT 协议
README.md	安装与使用说明