小程序開發文件

除錯與常見問題 ​

錯誤碼 ​

所有 sdk.* 呼叫失敗時都會以 MiniAppError reject，code 是下列其中之一：

code意思常見原因與處理
NOT_IN_CONTAINER不在容器內在瀏覽器裡預覽時一定會出現。顯示「請在 App 中開啟」之類的畫面即可
NOT_ALLOWED不允許呼叫方法不存在（容器版本太舊）、需要的權限沒在 permissions 宣告、在邏輯層呼叫只限畫面層的方法
PERMISSION_DENIED使用者拒絕授權目前沒有需要使用者授權的能力，保留給之後的相機、定位等
DOMAIN_BLOCKED網址不在白名單把網域加進 domains；相對網址、http://、IP 都會被擋
INVALID_PARAMS參數不合法超過長度上限、型別不對、標頭含中文或換行、GET 帶 body。見各 API 的參數表
RATE_LIMITED太頻繁每秒超過 50 次呼叫（瞬間最多 100 次）；已經有對話框、選單或分享頁開著；一批超過 64 個呼叫
QUOTA_EXCEEDED儲存空間已滿sdk.storage 超過 10 MB
NETWORK網路錯誤連不上、DNS 失敗、回應超過 5 MB
TIMEOUT逾時一般呼叫 30 秒沒有回應；http.fetch 超過 timeoutMs
INTERNAL容器內部錯誤保活期間呼叫 ui.toast／dialog／actionSheet、share.toChat；雙執行緒的邏輯層沒有在執行；其他情況請回報平台團隊
ts
import { MiniAppError, sdk } from '@im/miniapp-sdk';

try {
  await sdk.storage.set('k', value);
} catch (e) {
  if (e instanceof MiniAppError && e.code === 'QUOTA_EXCEEDED') {
    await sdk.ui.toast({ text: '空間不足，請清理後再試', icon: 'error' });
  }
}

常見問題 ​

骨架一直不消失，8 秒後才出現畫面 ​

沒有呼叫 sdk.ready()，或呼叫失敗。首屏畫完後呼叫一次；雙執行緒時在第一次拿到非載入中的資料後呼叫。

改了程式，App 裡還是舊的 ​

  • 沒有升 version：容器以版本號判斷更新。
  • 新版要下次開啟才生效；保活中的實例會先被接回，等 10 分鐘或用「⋯ → 重新进入小程序」。

使用者看到「请更新 App 后使用该小程序」 ​

minContainer 比使用者 App 的容器版本高。確認真的需要那麼新的容器能力；不需要就調低。

打不開，顯示「小程序校验未通过」 ​

包被改過，或簽章不對：

  • 建置後修改了包內的檔案（包含重新壓縮 zip）。
  • 用了錯的平台金鑰，或沒有 platform.sig。
  • 用開發用平台金鑰簽的包放到正式版 App。

localStorage 的資料不見了 ​

localStorage 只在這次開啟有效。持久資料改用 sdk.storage。

換頁後重新整理變成空白或 404 ​

用了 history 模式的路由。本機服務沒有 SPA fallback，改用 hash 路由，見路由。

某些套件報錯：拒絕執行 eval 或內嵌腳本 ​

CSP 不允許 eval、new Function 與內嵌 <script>。換用不依賴它們的套件；Vue 請用單檔元件（建置時預先編譯模板），不要在執行期編譯模板。

iOS 上樣式壞掉，Android 正常 ​

用到了 iOS 15 不支援的 CSS，見相容性。

邏輯層在 Android 上出錯，iOS 正常 ​

Android 的 QuickJS 沒有 Intl：toLocaleString、Intl.NumberFormat、Intl.DateTimeFormat 都不能用，請自己格式化。

http.fetch 回 INVALID_PARAMS ​

最常見的是標頭值有中文（例如把暱稱放進標頭）或換行。改放在 body，或先用 encodeURIComponent 編碼。

深色模式顏色不對 ​

用了 prefers-color-scheme 或寫死顏色。改用 CSS 變數或 [data-im-theme='dark']，見深色模式。

除錯方式 ​

  • 瀏覽器：npm run dev 適合排版與不依賴 SDK 的邏輯。把呼叫 SDK 的部分包成函式，在瀏覽器裡用假資料取代。
  • 埋點：用 sdk.telemetry.report 記錄關鍵數值，由平台收集（查詢方式請向平台團隊確認）。
  • App 內遠端除錯：測試版 App 目前還沒有開放 Safari Web Inspector／chrome://inspect，見尚未提供的功能。