微信小程序 Demo 运行指南

仓库中有四个微信小程序示例，分别演示原生小程序、分包加载、TypeScript 类型和 Taro React 的接入方式，完整源码见 GitLab sdk/miniprogram（访问仓库需要相应权限）。这些示例目前只随源码提供，没有单独的下载包；在自己的项目中接入，直接安装已发布的 SDK 即可。

用 uni-app 开发小程序的，请看 UniApp 微信小程序 Demo，那是另一个工程（sdk/uniapp/demo-miniprogram）。

选择入口

工程	用途	要修改的配置	在开发者工具中导入的目录
example	原生小程序的完整 IM 示例	miniprogram/config.js、project.config.json	sdk/miniprogram/example
example-subpackage	主包只放绑定（bind），SDK 放在分包中异步加载，并演示独立分包	miniprogram/config.js、project.config.json	sdk/miniprogram/example-subpackage
example-ts	TypeScript 类型示例，只用于类型检查	contract.ts、tsconfig.json	不能运行
example-taro	Taro 4 + React 的接入示例	src/im.ts、project.config.json	构建后导入 sdk/miniprogram/example-taro，miniprogramRoot 为 dist

环境与应用

• Node.js 20.19 以上、pnpm、微信开发者工具，以及你自己的小程序 AppID（project.config.json 中的 touristappid 只是占位）。
• IM 服务的 HTTPS 和 WSS 地址，以及应用的 AppKey。
• 微信基础库最低 2.21.3。使用 Skyline、加密存储、隐私接口的，请在目标基础库版本和真机上测试。
• 在小程序后台配置服务器域名：request 合法域名包括 IM 的 HTTPS 地址和文件上传用的对象存储地址（签名 PUT），socket 合法域名为 IM 的 WSS 地址，另外配置 downloadFile 域名和实际用到的 uploadFile 域名。开发者工具中“不校验合法域名”只在调试时有效，真机上必须配置。
• 相册、麦克风等隐私声明和用户授权由你的小程序完成。
• 登录凭证由业务服务端签发，Client Secret 和 App Token 不能放进小程序。密码登录和注册只在应用策略允许时可用。

已发布包接入

@deeprespond/im-miniprogram@1.1.1 已在 npm 公开发布。在你的原生小程序工程中执行：

npm install @deeprespond/im-miniprogram@1.1.1

然后在开发者工具中执行“工具 → 构建 npm”，确认 package.json、miniprogramRoot 和构建输出的目录对应。

• 发行包的 miniprogram 字段指向 CommonJS 版本；在 project.config.json 的 setting.babelSetting.ignore 中加入 miniprogram_npm/@deeprespond/**。
• 原生包没有运行时依赖，不需要另装 Web SDK。
• 仓库中的源码可能比已发布的版本新。使用新 API 之前，先确认已发布的包中有它；从源码能构建出来，不代表新版本已经发布。

完整仓库原生与分包 Demo

在仓库根目录执行：

cd sdk/web
pnpm install --frozen-lockfile
pnpm build
cd ../..
make sdk-miniprogram-example

这一步构建当前的 SDK，用官方的 miniprogram-ci 为原生示例构建 npm，并把 SDK 和绑定复制到分包目录；不会上传小程序。example 通过 file:../ 引用仓库中的 SDK，所以不能只复制 example 目录单独安装。

1. 修改对应工程 project.config.json 中的 appid。
2. 修改该工程 miniprogram/config.js 中的 appKey 和 apiUrl，apiUrl 要用微信能访问的 HTTPS 地址。
3. 在开发者工具中导入上表中的目录，确认 miniprogramRoot 后编译；手动重新构建 npm 时保持同样的输出目录。
4. 原生示例：先试单聊、好友、群和聊天室，再检查页面生命周期和 Skyline 渲染。
5. 分包示例：在开发者工具中设置自定义编译，启动页为 im/pages/index；再用 standalone/pages/index 试独立分包的冷启动，确认 sdk 目录已经生成。

开发者工具和真机上的表现可能不同，请分别测试。

Taro React

在仓库根目录执行：

make sdk-miniprogram-taro

它构建 Web SDK 和 React 绑定，安装 Taro 的依赖，做类型检查和微信小程序构建，并检查构建结果中没有混入浏览器专用代码和 LiveKit。

修改 example-taro/src/im.ts 和 AppID，重新构建后导入 example-taro。它只演示怎样在 Taro 中接入，页面功能比原生的完整示例少。

在自己的 Taro 工程中，安装同一版本的 Web SDK 和 React 绑定包，先导入 polyfills，再从 /miniprogram 子路径导入；不要用浏览器入口或原生小程序的预打包包代替。

类型与自动检查

make sdk-miniprogram-test
make sdk-miniprogram-integration

• make sdk-miniprogram-test：单元测试、组件测试、官方 wx 类型检查，以及 example-ts 的类型示例。
• make sdk-miniprogram-integration：集成测试，需要先启动仓库中的测试服务，见 sdk/conformance/README.md。

开发者工具和真机都必须用 HTTPS 和 WSS，不能用本机测试时的 HTTP 地址。不要让多个测试同时修改同一个应用的策略。

自动测试只覆盖了逻辑和页面流程。官方开发者工具和真机上的运行、文件上传、小程序被系统回收、加密存储、隐私接口、分包和 Skyline，还需要你在自己的环境中测试。

双账号与边界

• 双账号互测：两台手机（或两个独立的调试实例）用同一应用的不同账号登录，互加好友后试收发消息、群聊、已读、撤回，以及退出再进入页面。
• 一个客户端：同一个小程序中每个 AppKey 只能有一个客户端，再次创建返回 client_exists。切换用户时先退出登录、销毁旧的客户端，再创建新的。
• 文件用路径：文件都用本地路径交给 SDK，不使用 Blob。去除媒体元数据失败时，SDK 不会悄悄保留元数据。预览、录音时的前后台切换用 keepForeground 管理。
• 没有音视频：calls.supported 和 channels.supported 都为 false，不能加入通话和频道的媒体；能查询频道不代表能参与音视频。
• 支持的平台：原生包支持微信和企业微信中的小程序；支付宝、抖音、QQ 小程序和 Donut 没有适配。

排查

现象	检查
找不到 SDK 或 bind	是否先构建了 Web SDK，再运行 make sdk-miniprogram-example；npm 的输出目录和分包复制是否正确
登录失败	AppKey、应用策略、账号是否属于这个应用，凭证是否还在有效期内
真机上请求失败	HTTPS、WSS 证书；合法域名中是否有 IM 地址、文件上传（签名 PUT）和下载的域名
Taro 构建中混入了浏览器代码或 LiveKit	是否最先导入 polyfills、是否用 /miniprogram 子路径、各包版本是否一致
TS 示例无法运行	example-ts 只用于类型检查，不能运行
预览文件后连接中断	是否用 keepForeground 管理前后台并及时释放；回到前台后等待重新连接
只能查询频道，不能加入	小程序目前不支持频道媒体，在应用策略中开启音视频也不会改变