微信小程式 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 管理前後臺並及時釋放；回到前臺後等待重新連線
只能查詢頻道，不能加入	小程式目前不支援頻道媒體，在應用策略中開啟音影片也不會改變