微信小程序 Demo 运行指南

完整源码见 GitLab sdk/miniprogram，仓库访问需要相应权限。四套示例当前随源码提供，没有独立下载包；接入自己的项目可直接安装已发布 SDK。

四套示例分别面向原生微信、分包、TypeScript 契约和 Taro React；与 sdk/uniapp/demo-miniprogram 的 uni-app 工程不同。

选择入口

工程	用途	配置	开发者工具导入目录
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	类型契约	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、IM HTTPS/WSS 地址和 AppKey。 基础库最低 2.21.3，Skyline、加密存储和隐私接口还需按目标基础库与设备验收。touristappid 是占位值。 request 合法域名包括 IM HTTPS 和签名 PUT 对象存储，另配 Socket WSS、downloadFile 及实际用到的 uploadFile 域名。 相册、麦克风隐私声明与授权由应用完成；工具中跳过域名校验不能替代真机合法域名配置。 业务后端签发短期登录凭证，Client Secret / App Token 不进入小程序。密码登录与注册仅在应用策略允许时使用。

已发布包接入

@deeprespond/im-miniprogram@1.0.0-alpha 已公开发布。在自己的原生小程序工程中执行：

npm install @deeprespond/im-miniprogram@1.0.0-alpha

在开发者工具执行“工具 → 构建 npm”，核对 package.json、miniprogramRoot 和打包输出关系。 发行包的 miniprogram 字段指向 CommonJS；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 / bind 到分包目录，不会上传小程序。 example 的 file:../ 指仓库 SDK，不能只复制 example 再安装。

1. 修改对应 project.config.json 的 appid。
2. 修改该工程 miniprogram/config.js 的 appKey 和 apiUrl，使用微信可访问的 HTTPS。
3. 开发者工具导入表中目录，核对 miniprogramRoot 后编译；手动重建 npm 时保持输出关系一致。
4. 原生先验证普通聊天、好友、群和聊天室，再检查 Page 生命周期与 Skyline。
5. 分包在开发者工具设置自定义编译启动页 im/pages/index，再以 standalone/pages/index 验证独立分包冷启动；确认 sdk 目录已生成。

开发者工具、页面回放与真机是不同验证环境，需分别记录结果。

Taro React

仓库根目录执行：

make sdk-miniprogram-taro

它构建 Web/React 共享包、安装 Taro 依赖，执行类型、weapp 构建与无浏览器适配/LiveKit 混入检查。 修改 example-taro/src/im.ts 与 AppID，重新构建后导入 example-taro。它是框架接入示例，页面功能不等同于原生完整 Demo。 自己的 Taro 工程安装同版本 Web/React 包，先导入 polyfills，使用 /miniprogram 子路径；不使用浏览器入口或原生预打包包替代。

类型与自动检查

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

第一项含单元、组件、官方 wx 类型及 example-ts 契约；第二项需完整仓库已启动的独立 harness，见 sdk/conformance/README.md。 开发者工具与真机须使用 HTTPS/WSS，不能照搬本机 HTTP。不要让多个测试并行改变同一应用策略。 现有报告 Agent测试/微信小程序SDK与Demo完善/测试报告.md：逻辑 E2E 49/49，页面回放 33 步、双视口 66 张截图；不代表官方工具/真机、二进制 PUT、后台回收、加密存储、隐私、分包或 Skyline 已验收。

双账号与边界

两台真机或独立调试实例以同应用不同账号登录，互加好友后验证收发、群聊、已读、撤回和重新进入页面。 同一宿主同一 AppKey 只允许一个客户端，重复创建返回 client_exists；换用户先退出，销毁旧客户端后再创建。 文件使用路径，不使用 Blob；媒体处理失败不可默默保留元数据。预览/录音的前后台按 keepForeground 生命周期管理。 calls.supported 和 channels.supported 都为 false，没有 LiveKit 媒体加入；查询频道不等于能参与实时媒体。 原生包支持微信和企业微信中的小程序，不代表支持支付宝、抖音、QQ 或 Donut。

排查

现象	检查
找不到 SDK/bind	先构建 Web，再运行 make sdk-miniprogram-example，核对 npm 输出与分包复制
登录失败	AppKey、应用策略、账号归属、短期凭证及时间
真机请求失败	HTTPS/WSS 证书、合法域名、签名 PUT 和下载域名
Taro 混入浏览器/LiveKit	polyfills 顺序、/miniprogram 子路径、共享包版本与依赖图检查
TS 示例无法运行	example-ts 只用于类型编译
文件预览后暂停	管理页面生命周期、keepForeground 释放，回前台等待重连
只能查频道	当前平台限制，开启 RTC 策略不会补齐媒体适配