小程序直播 SDK 集成教程：从 SDK 引入到推拉流组件配置

笔者简介

长期关注 RTC 实时音视频领域的技术演进，参与过音视频算法工程化、接入实现与效果评估等相关工作。在实际项目中，持续关注包括腾讯 TRTC、即构 ZEGO、声网 Agora 在内的多家 RTC 厂商在实时通信能力与工程落地层面的实践，重点关注 SDK 接入、通话链路实现与场景化应用。本系列文章将围绕 RTC SDK 接入与实时互动能力实现，持续输出工程实践与场景分析。

在微信小程序直播场景中，开发者通常需要在有限的运行环境内完成 SDK 集成、推流组件接入、拉流组件接入以及小程序后台插件配置。相比普通 Web 页面，小程序还会受到基础库版本、插件审核、组件声明和开发者工具配置等因素影响。如果接入流程处理不完整，常见问题会集中在 SDK 文件引用失败、npm 构建未生效、直播插件未申请或未声明、推拉流组件无法加载等环节。

对第一次接入小程序直播能力的团队来说，先把环境、SDK 和插件链路跑通，比直接进入业务功能开发更关键。

本文将以 ZEGO小程序直播SDK 官方文档为基础，围绕「小程序直播SDK集成」梳理完整接入流程，重点覆盖开发环境准备、SDK 集成方式、直播插件申请、app.json 插件声明以及 zego-pusher / zego-player 组件使用。

1 准备环境

请确保开发环境满足以下技术要求：

已安装微信开发者工具
使用微信小程序基础库 2.3.0 及以上版本（否则不支持音视频播放、录制组件）

2 集成 SDK

请选择以下任一方法集成即构小程序 SDK：

方法一：从官网下载 SDK

请从 ZegoExpress-MiniProgram 下载 SDK。历史版本更新，请查看：小程序 JS SDK 历史更新日志。
将下载下来的文件包解压缩后拷贝到小程序项目所在文件夹下。
使用 require 将 SDK 集成到项目中即可：

 <script src="ZegoExpressWebRTC-x.x.x.js"></script>

require 需填写项目中 SDK 的实际文件路径。

方法二：使用npm获取 SDK

在终端运行安装命令。

npm i miniprogram-zego

在开发者工具菜单栏中选择 工具 > 构建 npm，并勾选“使用 npm 模块”选项。
在项目中添加如下代码：

let { ZegoExpressEngine } = require("zego-express-engine-miniprogram"); // 以npm的方式引用

小程序使用 npm 详见官方文档。

3 集成小程序直播插件

3.1 申请插件

登录微信小程序后台，在 设置>基本设置 中，确定已具备符合接入的类目。

[图片待处理：飞书私有图片 Ms3xbz...Nntc]

在小程序管理后台的“设置-第三方设置”中选择“添加插件”，在弹出的面板中搜索“即构直播助手”，选中插件并添加，等待后台审核。

[图片待处理：飞书私有图片 B16Pbb...lnAf]

插件名称：即构直播助手。
插件 AppID：wx2b8909dae7727f25。
插件最低版本限制：1.0.4。

3.2 在小程序中引入插件代码

插件申请审核通过后，使用插件前要在小程序工程的 app.json 中声明需要使用的插件，例如：

{
  "plugins": {
    "zego-e-commerce": {
      "version": "1.0.4",
      "provider": "wx2b8909dae7727f25"
    }
  }
}

3.3 小程序使用插件中的推拉流组件

在 page 或 component 的 .json 文件中定义需要引入的 zego-pusher 组件，使用 plugin:// 协议。

{
    "usingComponents": {
      "zego-pusher": "plugin://zego-e-commerce/zego-pusher",    //推流组件
    }
}

在 wxml 文件加载上一步引入的 zego-pusher 组件。

    <zego-pusher wx:if="{{loginType==='anchor'}}" id="zg-pusher" url="{{pushUrl}}" class="push-content" bindstatechange="onPushStateChange" bindnetstatus="onPushNetStateChange"></zego-pusher>

在 page 或 component 的 .json 文件中定义需要引入的 zego-player 组件，使用 plugin:// 协议。

{
   "usingComponents": {
       "zego-player": "plugin://zego-e-commerce/zego-player",    //拉流组件
   }
}

在 wxml 文件加载上一步引入的 zego-player 组件。

    <zego-player wx:if="{{loginType==='audience'}}" id="zg-player" sid="{{sid}}" url="{{playUrl}}" objectFit="fillCrop" class="play-content" bindstatechange="onPlayStateChange" bindnetstatus="onPlayNetStateChange"></zego-player>

结语

本文主要介绍了「小程序直播SDK集成」的基础接入流程，并结合官方文档梳理了环境准备、核心 API 调用、媒体处理和结果验证等关键环节。通过这类能力，开发者可以更快搭建实时音视频、在线互动、远程协作、直播连麦、视频通话等典型场景，并在后续根据业务需要扩展更多互动能力。围绕实时音视频能力，后续还可以继续关注：

RTC SDK 完整接入流程与关键参数配置
推流、拉流、房间与回调机制解析
权限、Token、设备兼容和网络异常排查
多人通话、语聊房、互动直播等进阶场景
跨端场景下的实时互动能力对比本系列将围绕「RTC SDK 接入与实时互动能力实现」持续更新，适合需要构建实时音视频、在线互动、AI 实时通信等能力的开发者参考。

如果近期有接入需求，可以注册即构ZEGO开发者帐号，快速开始。接入过程中遇到问题，可以参考下方常见问题或官方文档进一步排查。

常见问题

1. 接入小程序直播 SDK 前需要准备哪些环境？

需要先安装微信开发者工具，并确认小程序基础库版本为 2.3.0 及以上。低版本基础库不支持音视频播放和录制组件，可能导致推流、拉流相关组件无法正常工作。

2. 小程序直播 SDK 可以通过哪些方式集成？

通常有两种方式：一种是从官网下载 ZegoExpress-MiniProgram SDK 包并放入小程序项目目录；另一种是通过 npm 安装 miniprogram-zego，再在微信开发者工具中执行“构建 npm”并启用 npm 模块。

3. 使用 npm 集成后为什么代码里仍然找不到 SDK？

常见原因是安装后没有在微信开发者工具中执行“构建 npm”，或者没有勾选“使用 npm 模块”。完成 npm 安装后，需要在开发者工具菜单中执行构建，让小程序能够识别依赖包。

4. 为什么还需要申请小程序直播插件？

小程序直播场景需要使用插件中的推流和拉流组件。开发者需要先在微信小程序后台确认类目符合要求，再到“设置 - 第三方设置”中添加“即构直播助手”插件，并等待审核通过。

5. 插件接入时 app.json 需要配置什么？

插件审核通过后，需要在小程序工程的 app.json 中声明插件信息，包括插件名称、版本号和 provider。当前文档中的示例使用 zego-e-commerce，版本为 1.0.4，provider 为 wx2b8909dae7727f25。

6. zego-pusher 和 zego-player 分别负责什么？

zego-pusher 负责推流，通常用于主播端或需要发送音视频的一端；zego-player 负责拉流，通常用于观众端或需要播放远端音视频的一端。二者都需要先在页面或组件的 JSON 文件中通过 plugin 协议声明。

7. 小程序直播接入最容易出错的地方有哪些？

常见问题包括基础库版本过低、SDK 文件路径填写错误、npm 构建遗漏、插件未审核通过、app.json 插件声明错误、组件路径写错，以及推流地址或拉流地址参数未正确传入。

posted @ 2026-06-04 11:17 RTC实战笔记阅读(41) 评论(0) 收藏举报

刷新页面返回顶部