微信小程序直播实战：从项目搭建到真机调试的完整流程

一、项目搭建：3 步完成初始化

1. 安装微信开发者工具

2. 注册小程序账号

注册小程序 → 选择类目（如：社交-直播、教育-在线教育，类目必须与后续开通直播组件一致）→ 完成认证。

3. 创建项目

• 打开「微信开发者工具」→ 选「小程序」→ 填入

  • 项目目录：任意空文件夹

  • AppID：注册后在「开发-开发设置」里复制

  • 后端服务：选「不使用云服务」→ 勾选「建立普通快速启动模板」→ 完成。

目录结构（模板自动生成）：

└─weapp-live/
   ├─app.js
   ├─app.json
   ├─app.wxss
   ├─pages/
   │  └─index/
   │     ├─index.wxml
   │     ├─index.wxss
   │     └─index.js
   └─project.config.json

二、开通直播组件权限

4. 类目审核

• 在「小程序后台-设置-基本设置」确认一级类目 + 二级类目已包含「直播」相关关键词。

5. 接口开关

• 路径：小程序后台 → 开发 → 开发设置 → 接口设置

• 打开「实时播放音视频流」和「实时录制音视频流」（默认关闭，需管理员扫码确认）。

三、使用 live-player 组件

6. 组件属性速查

7. 状态码对照（bindstatechange 回调）

2001 已连接服务器  
2002 开始拉流  
2004 播放开始  
2007 播放中网络恢复  
-2301 网络断连  

四、代码示例：首页播放直播

8. 修改 pages/index/index.wxml

<live-player
  id="player"
  src="{{liveUrl}}"
  mode="live"
  autoplay
  muted="{{false}}"
  orientation="vertical"
  object-fit="contain"
  bindstatechange="onPlayerStateChange"
  binderror="onPlayerError"
  style="width:100%;height:300px;"
/>

muted="{{false}}"表示不静音；如果想默认静音就写 true。

orientation="vertical"是竖屏直播。横屏写 horizontal。

object-fit="contain"表示保持比例完整显示；可选 fill（拉伸）或 cover（裁剪填满）。

9. 修改 pages/index/index.js

Page({
  data: {
    liveUrl: ''   // 先留空
  },
  onLoad() {
    // 本地调试把 127.0.0.1 换成电脑局域网 IP
    this.setData({
      liveUrl: 'rtmp://192.168.1.100/live/stream'
    });
  },
  onPlayerStateChange(e) {
    console.log('live-player code:', e.detail.code);
  },
  onPlayerError(e) {
    console.error('live-player error:', e.detail.errMsg);
  }
});

一句话来说 WXML 负责「放组件、绑事件」。JS 负责「给地址、收状态」。
把两段代码原样放进 pages/index，手机扫码即可看到直播画面。

五、本地推流与真机调试

1. 启动本地 RTMP → HTTP-FLV 服务（同 H5 章节）

docker run -d --name live \
  -p 1935:1935 -p 8080:8080 \
  alfg/nginx-rtmp

2. 推流

ffmpeg -re -i big_buck_bunny.mp4 \
  -c:v libx264 -preset veryfast -g 30 \
  -c:a aac -f flv rtmp://192.168.1.100/live/stream

3. 真机调试步骤

• 手机和电脑连接 同一 Wi-Fi。

• 开发者工具 → 预览 → 生成二维码 → 微信扫码。

• 若出现 net::ERR_CONNECTION_REFUSED，把 liveUrl 里的 127.0.0.1 改为电脑局域网 IP。

4. 调试面板
   扫码后，手机右上角菜单 → 打开调试 → 可在 VConsole 查看 live-player 状态码、码率、缓存等日志。

六、注意事项

• 层级最高：live-player 为原生组件，无法通过 z-index 控制，遮挡问题可用 cover-view 解决。

• 禁止嵌套：不可放在 scroll-view、swiper、movable-view 内。

• CSS 动画无效：对该组件设置 transform / animation 不会生效。

• 推流中断：视频播完或 FFmpeg 退出后，页面会黑屏；重新推流即可恢复。

七、上线 checklist

5. 类目、接口权限已开通。

6. HTTPS-FLV 或 RTMP 地址可用，且域名已配置到小程序「downloadFile 合法域名」。

7. 真机测试通过，状态码正常，无报错。

8. 按需开启「后台静音」和「低缓存」参数，避免耗电、耗流量。