快速開始

這一頁從零建一個單執行緒的小程序，最後建置出可以安裝到測試版 App 的離線包。全部步驟約 10 分鐘。

1. 準備環境

• Node.js 22.22 以上（建議 24 LTS）（node -v 確認）。
• 平台提供的工具 im-miniapp-tools（內含 SDK @im/miniapp-sdk 與 CLI im-miniapp）。

SDK 與 CLI 尚未發佈到 npm

目前請向平台團隊取得 im-miniapp-tools，放在小程序專案的旁邊，以本機路徑安裝。發佈到套件庫後，這一步會改成一般的 npm install。

建議的目錄配置：

workspace/
├── im-miniapp-tools/   # 平台提供的工具
└── hello/              # 你的小程序

先建置一次 SDK（之後工具更新時再跑）：

cd im-miniapp-tools
npm install
npm run build:sdk

2. 建立專案

在 workspace/hello 建立以下檔案。

package.json

{
  "name": "hello",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "typecheck": "vue-tsc --noEmit",
    "build": "im-miniapp build --dev-key keys/developer.pem --platform-key keys/dev-platform.pem"
  },
  "dependencies": {
    "@im/miniapp-sdk": "file:../im-miniapp-tools/packages/sdk",
    "vue": "^3.5.44"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^6.0.10",
    "im-miniapp": "file:../im-miniapp-tools/packages/cli",
    "typescript": "~6.0.3",
    "vite": "^8.3.5",
    "vue-tsc": "^3.3.14"
  }
}

miniapp.config.ts

import { defineConfig } from 'im-miniapp';

export default defineConfig({
  id: 'hello',
  name: '你好小程序',
  version: '1.0.0',
  permissions: [],
  domains: [],
  ageRating: 0,
  minContainer: '1.2.0',
  pages: ['/'],
});

vite.config.ts

import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

// base、outDir、sourcemap 由 im-miniapp build 設定，這裡不用寫。
export default defineConfig({
  plugins: [vue()],
});

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "types": ["vite/client"]
  },
  "include": ["src/**/*.ts", "src/**/*.vue", "miniapp.config.ts", "vite.config.ts"]
}

index.html

<!doctype html>
<html lang="zh-Hant">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
    <title>你好小程序</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

src/ 底下三個檔案：

src/main.ts

import { createApp } from 'vue';
import App from './App.vue';
import './style.css';

createApp(App).mount('#app');

src/App.vue

<script setup lang="ts">
import { MiniAppError, sdk } from '@im/miniapp-sdk';
import { nextTick, onMounted, ref } from 'vue';

const nickname = ref<string | null>(null);
const error = ref('');

onMounted(async () => {
  try {
    const session = await sdk.auth.getSession();
    nickname.value = session.nickname;
  } catch (e) {
    error.value = e instanceof MiniAppError && e.code === 'NOT_IN_CONTAINER' ? '請在 App 中開啟' : '載入失敗';
  }
  // 首屏渲染完成後通知容器移除骨架。
  await nextTick();
  sdk.ready().catch(() => {});
});

function greet(): void {
  sdk.ui.toast({ text: '你好！', icon: 'success' }).catch(() => {});
}
</script>

<template>
  <main class="page">
    <h1 class="title">{{ error || `嗨，${nickname ?? ''}` }}</h1>
    <button type="button" class="button" @click="greet">打招呼</button>
  </main>
</template>

src/style.css

/* 顏色、間距、圓角、字級一律用容器注入的 --im-* 變數。 */
body {
  margin: 0;
  background: var(--im-color-background);
  color: var(--im-color-text);
  font-family: system-ui, -apple-system, sans-serif;
  font-size: var(--im-font-body);
}

.page {
  padding: var(--im-space-md);
  padding-bottom: calc(var(--im-space-md) + var(--im-safe-bottom));
}

.title {
  margin: 0 0 var(--im-space-md);
  font-size: var(--im-font-title2);
}

.button {
  min-height: 44px;
  padding: 0 var(--im-space-lg);
  border: 0;
  border-radius: var(--im-radius-pill);
  background: var(--im-color-primary);
  color: var(--im-color-on-accent);
  font: inherit;
}

安裝依賴並做型別檢查：

cd hello
npm install
npm run typecheck

3. 在瀏覽器預覽

npm run dev

瀏覽器裡沒有容器，所以：

• 所有 sdk.* 呼叫都會以 NOT_IN_CONTAINER 失敗（上面的範例會顯示「請在 App 中開啟」）。可以用 inContainer() 判斷。
• 沒有 --im-* CSS 變數，畫面沒有顏色。只是看排版的話可以接受；需要顏色時，在開發環境另外載入一份變數預設值（數值見主題變數），不要把預設值打包進正式版。

瀏覽器預覽只適合排版與純前端邏輯；呼叫 SDK 的功能要在 App 裡測。

4. 準備金鑰

mkdir keys
npx im-miniapp keygen keys/developer

• keys/developer.pem 是你的開發者私鑰，用來產生 signature.sig。請放進 .gitignore，正式的開發者私鑰只放在 CI。
• keys/dev-platform.pem 是開發用平台金鑰，請向平台團隊索取。只有測試版 App 會信任它；正式包的平台簽章由平台在審核通過後加上。

node_modules/
dist/
keys/

5. 建置

npm run build

成功時會印出體積報告並輸出離線包：

主包     67.3 KB / 2 MB    ✓
總量     67.3 KB / 20 MB   ✓
首屏 JS  23.7 KB / 300 KB  ✓

已輸出 dist/hello-1.0.0.imapp（29.2 KB，29916 bytes）

任何一項超出效能預算都會失敗，不會產生 .imapp。

6. 在 App 裡測試

目前請把 dist/hello-1.0.0.imapp 交給平台團隊放進測試版 App。掃碼載入開發中的小程序（im-miniapp dev）還在規劃中，見尚未提供的功能。

在 App 裡打開後應該會看到：

1. 容器的骨架畫面，接著淡出（因為呼叫了 sdk.ready()）。
2. 「嗨，＋你的暱稱」。
3. 點「打招呼」跳出 App 原生的 Toast。

下一步

• 專案結構與設定：每個設定欄位的意思。
• 單執行緒與雙執行緒：業務邏輯比較重時改用雙執行緒。
• 開發規範：上架前要逐條自查。