语聊房小程序怎么开发：微信环境 SDK 接入指南

微信小程序的语聊房接入，和 Android/iOS 原生端有几处明显差异：SDK 使用的是基于 Stream 的旧式 API（不是原生端的 Track API），AppID 在初始化时传入而不是 join 时传入，join 的参数顺序也不同。加上微信平台本身的前置要求（类目资质、域名白名单、运行时权限），新人容易在没进到代码之前就卡住。

这篇文章按接入顺序说明：先处理微信平台的前置配置，再讲 SDK 的核心用法，最后覆盖调试和常见报错。

一. 微信平台前置要求

微信小程序的实时音视频通信需要申请特定权限，不满足条件直接写代码是跑不通的。

类目要求

微信对使用实时音视频能力的小程序有类目限制。社交、游戏、教育、医疗等类目通常可以申请。在微信开放平台 → 小程序管理后台 → 开发管理 → 接口设置，申请”实时播放音视频流”和”实时录制音视频流”两项能力。审核通过后才能在真机上正常使用。

服务域名白名单

微信小程序的所有网络请求都必须在”request 合法域名”和”socket 合法域名”里。声网 SDK 使用 WebSocket 连接，需要将声网的服务域名添加到小程序的合法 socket 域名列表。具体域名列表以声网官方文档为准，通常包含 *.agora.io、*.agoraio.cn 等域名。在微信公众平台 → 开发 → 开发设置 → 服务器域名 里配置。

开发阶段可以在微信开发者工具的”详情”里勾选”不校验合法域名”，方便本地调试。上线前必须配置好白名单。

二. 安装 SDK

声网小程序 SDK 的 npm 包名为 agora-miniapp-sdk。

在小程序项目根目录执行：

npm init -y
npm install agora-miniapp-sdk --save

安装后，在微信开发者工具里点击”工具 → 构建 npm”，生成 miniprogram_npm 目录。然后在代码里引入：

const AgoraMiniappSDK = require('agora-miniapp-sdk');

如果不用 npm 方式，也可以从声网官网下载 SDK 文件，手动放到项目目录里用相对路径引入。两种方式功能一样，npm 方式更便于版本管理。

三. 声明权限

在 app.json 里声明麦克风权限用途：

{
  "permission": {
    "scope.record": {
      "desc": "加入语聊房需要使用麦克风"
    }
  }
}

这个声明是系统弹权限请求时显示给用户的说明文字，要写清楚用途，微信审核时也会检查。

在进入频道前，先用 wx.authorize 主动申请录音权限：

function requestRecordPermission() {
    return new Promise((resolve, reject) => {
        wx.authorize({
            scope: 'scope.record',
            success: () => resolve(true),
            fail: () => {
                // 用户拒绝或未授权，引导去设置页
                wx.showModal({
                    title: '需要麦克风权限',
                    content: '请在设置中开启麦克风权限后重试',
                    confirmText: '去设置',
                    success: ({ confirm }) => {
                        if (confirm) wx.openSetting();
                    }
                });
                reject(new Error('record permission denied'));
            }
        });
    });
}

四. 初始化 SDK 和加入频道

小程序 SDK 的 API 风格和原生端不同：AppID 在 init 时传入，join 时只传 token、频道名和 uid，参数顺序也和 Web SDK 不同。

const APP_ID = "你的 AppID";
const client = new AgoraMiniappSDK.Client();

async function joinChannel(token, channelName, uid) {
    // Step 1：用 AppID 初始化
    await client.init(APP_ID);

    // Step 2：设置角色（语聊房默认进入为观众）
    // 小程序 SDK 用 setRole，角色值为 'broadcaster' 或 'audience'
    await client.setRole('audience');

    // Step 3：加入频道
    // 注意参数顺序：(token, channelName, uid)，和 Web SDK 不同
    await client.join(token, channelName, uid);

    console.log("加入频道成功");
}

Token 的获取方式和原生端一样，从自己的业务服务端获取，不要在小程序代码里存放 App Certificate。

五. 发布音频（上麦）

小程序 SDK 使用 Stream（流）模型，和原生端的 Track（轨道）模型不同。上麦需要先创建本地 Stream，再发布：

let localStream = null;

async function goOnMic() {
    // 创建纯音频本地流（语聊房不需要视频）
    localStream = AgoraMiniappSDK.createStream({
        audio: true,
        video: false
    });

    // 初始化流（此时会触发麦克风权限）
    await localStream.init();

    // 切换角色为主播
    await client.setRole('broadcaster');

    // 发布音频流
    await client.publish(localStream);
    console.log("上麦成功");
}

六. 订阅远端音频

进入频道后监听 stream-added 事件，有新的音频流加入时自动订阅：

// 建议在 join 之前注册
client.on('stream-added', ({ stream }) => {
    client.subscribe(stream);
});

client.on('stream-subscribed', ({ stream }) => {
    // 播放远端音频
    stream.play();
});

client.on('peer-leave', ({ uid }) => {
    console.log("用户离开:", uid);
    // 清除对应麦位 UI
});

七. 下麦和离开频道

// 下麦：停止发布，切回观众
async function goOffMic() {
    if (localStream) {
        await client.unpublish(localStream);
        localStream.close();
        localStream = null;
    }
    await client.setRole('audience');
}

// 离开频道
async function leaveChannel() {
    if (localStream) {
        localStream.close();
        localStream = null;
    }
    await client.leave();
    await client.destroy();
}

八. 调试注意事项

必须用真机测试

微信开发者工具的模拟器不支持麦克风访问，所有音频相关的功能都需要扫码预览或真机调试。在工具里看到的只是页面布局，音频功能必须真机验证。

开启调试模式

真机调试时，在微信开发者工具里打开”开发版”调试，可以看到 console 输出和网络请求。SDK 初始化失败的错误信息会在 console 里显示。

域名白名单校验

开发阶段可以关闭域名校验（工具 → 详情 → 不校验合法域名），方便快速验证功能。上线前必须配置好白名单并开启校验，否则审核不通过。

九. 常见问题

初始化失败，错误码 901

可能原因：1）微信开放平台没有开通”实时播放/录制音视频流”能力；2）socket 合法域名未配置声网服务域名；3）uid 参数不是整型（小程序 SDK 要求 uid 为整型，不接受字符串）。

初始化失败，错误码 903

通常是网络问题或鉴权失败。检查 Token 是否正确（有效期、频道名是否匹配），以及设备是否能访问声网服务器。开发环境可以临时用控制台生成的临时 Token 排查。

上麦后其他人听不到

确认 setRole('broadcaster') 是否在 publish 之前调用。如果以 audience 角色调用 publish，SDK 会报错或静默失败。

用户拒绝麦克风权限后无法再弹权限请求

微信里用户一旦拒绝某个权限，后续再调用 wx.authorize 不会再弹系统弹窗。只能调用 wx.openSetting 让用户手动去开启，或者引导用户下拉刷新当前小程序重置权限状态。