生命週期

開啟小程序

點開 ─▶ 容器骨架 ─┬─ 有保活實例 ──────────────────────────▶ 直接接回（熱啟動）
                  └─ 沒有 ─▶ 本機有包？─┬─ 有：直接啟動，背景檢查新版
                                        └─ 沒有：下載、驗簽（顯示進度）
                     ─▶ 載入 index.html ─▶ 你的程式 ─▶ sdk.ready() ─▶ 骨架淡出

骨架與 sdk.ready()

• 開啟時容器先蓋一層骨架。你的首屏渲染完成後呼叫 sdk.ready()，骨架才淡出。
• 先有內容（或錯誤畫面）再呼叫，不要一進來就呼叫：否則使用者會看到空白或你自己的載入畫面閃一下。
• 頁面載入完 8 秒內沒有呼叫 sdk.ready()，容器會自動拿掉骨架，並記錄一筆逾時。
• 重複呼叫只會送出一次。

版本更新

• 本機已經有包時，容器直接用本機版本開啟，同時在背景確認有沒有新版。有新版就下載，下次開啟才生效，不會打斷使用中的畫面。
• 新版需要的容器版本比 App 高時，不會下載，繼續使用目前的版本。
• 小程序被暫停或下架時，開著的畫面會立刻換成「该小程序已暂停服务」，無法再操作。

關閉與保活

使用者按膠囊的「✕」或返回關閉小程序後，正常運作中的實例會被保活：不銷毀，暫時留著。10 分鐘內再打開，直接接回原本的畫面與狀態（熱啟動）。

• 最多同時保活 2 個小程序，超過時釋放最久沒用的。
• 以下情況不會接回，改成重新啟動：
  • 超過 10 分鐘。
  • 從帶有起始頁的分享卡片打開（要從指定頁開始）。
  • 背景已經下載好新版本。
  • 換過 App 語言。
  • 保活期間崩潰（WebView 內容程序被系統回收、邏輯層崩潰）。handler 裡的一般錯誤只會上報，不影響接回。
• 以下情況會釋放所有保活實例：系統記憶體不足、登出、換帳號、重新登入、切換伺服器。
• 打開時發生錯誤的實例，以及還沒 sdk.ready()（骨架還在）就被關閉的實例，不會保活。

前景、背景事件

時機	畫面層	邏輯層
App 退到背景、小程序被關閉（進入保活）	app.pause	onHide
App 回到前景、保活的小程序被打開	app.resume	onShow

import { sdk } from '@im/miniapp-sdk';

const offPause = sdk.on('app.pause', () => {
  stopPolling();
  void saveDraft(); // 存檔：保活期間 sdk.storage、sdk.auth、sdk.http 都能用
});
const offResume = sdk.on('app.resume', () => {
  startPolling();
  void refreshIfStale();
});

• 保活期間 WebView 裡的程式還在執行：輪詢、動畫、計時器請在 app.pause 停掉，在 app.resume 恢復。
• 保活期間 ui.toast、ui.dialog、ui.actionSheet、share.toChat 會以 INTERNAL 失敗；ui.setTitle、ui.loading、navigate.close 不報錯但沒有效果；auth、http、storage 等其他能力照常可用。
• App 退到背景時，容器會先把已寫入 sdk.storage 的資料存檔，再在約 100 ms 內把 app.pause 送到；在 app.pause 裡寫入的資料約 0.5 秒內存檔。要存的資料平常就隨時寫入，不要全部留到 app.pause。
• 第一次啟動時不會收到 app.resume／onShow，請在初始化流程（或邏輯層的 onLoad）載入資料。

重新進入

膠囊「⋯」→「重新进入小程序」會銷毀目前的實例，從頭冷啟動（不重新下載）。標題、載入狀態都會重設。

錯誤畫面

情況	使用者看到（App 文案）	能否重試
網路錯誤、儲存空間不足、頁面載入失敗、邏輯層啟動失敗	「小程序打开失败」	可以
離線包驗證失敗	「小程序校验未通过，请稍后再试」	可以
小程序已暫停或下架	「该小程序已暂停服务」	不行
App 的容器版本低於 minContainer	「请更新 App 后使用该小程序」	不行

出現錯誤畫面時，實例會被拆掉，返回鍵與返回手勢直接關閉小程序。

小程序裡的導覽被新的導覽打斷（例如快速連點兩個連結）不算錯誤。

主題、字級、安全區變更

使用者切換深淺色或主題色、開關增強對比、調整系統字級，或安全區改變（例如鍵盤開關）時，容器會更新 CSS 變數並送出 theme.change。SDK 已自動套用新變數與 data-im-theme，只用 CSS 變數的畫面不需要做任何事。需要在 JS 裡反應時用 sdk.theme.onChange。