專案結構與設定

目錄

my-app/
├── miniapp.config.ts   # 小程序設定（id、版本、網域、權限…）
├── index.html          # 入口頁
├── vite.config.ts      # Vite 設定（只放 plugins 等，不用設 base、outDir）
├── tsconfig.json
├── package.json
├── public/             # 原樣複製進包的靜態檔（圖示等）
└── src/
    ├── main.ts         # 畫面層入口
    ├── App.vue
    └── logic.ts        # 雙執行緒才需要：邏輯層入口

建置時 CLI 會：

• 強制 base: './'：包內的檔案一律用相對路徑引用，不要寫死以 / 開頭的網址。
• 依 App 的最低系統版本設定語法目標（畫面層 safari15、chrome111；邏輯層 es2020）。
• 產生 sourcemap，但不放進包，另存在 dist/sourcemaps/。

miniapp.config.ts

import { defineConfig } from 'im-miniapp';

export default defineConfig({
  id: 'points',                 // 唯一識別碼，[a-z0-9_-]，1–64 字，發佈後不能改
  name: '会员点数',             // 顯示名稱（導覽列預設標題、分享卡片頁首）
  version: '1.1.2',             // 語意化版本；內容有任何改動都要升版
  permissions: [],              // 需要授權的能力，例如 ['share.toChat']
  domains: ['https://points.example.com'], // sdk.http.fetch 可以連的網域
  ageRating: 0,                 // 年齡分級；0 為不限
  minContainer: '1.2.0',        // 需要的最低容器版本
  pages: ['/'],                 // 小程序內的頁面路徑
  runtime: 'dual',              // 省略即單執行緒
  logic: 'src/logic.ts',        // runtime: 'dual' 時必填
});

每個欄位的完整規則見 miniapp.config.ts 參考。重點：

• version：容器用版本號判斷要不要下載新包。內容改了沒升版，使用者手機上的舊包不會更新。
• minContainer：設成你用到的所有能力中最新的那個容器版本（對照容器版本）。App 的容器版本比它低時，使用者會看到「请更新 App 后使用该小程序」，不會載入。
• domains：只能是 https:// 加主機名稱（可帶埠），不能有路徑；不接受 IP、localhost、底線、萬用字元。
• permissions：目前只有 share.toChat 需要宣告。

index.html

• 必須有 <head>：容器會在 <head> 最前面插入 __im/launch.js 與 __im/theme.css，讓第一個畫面就有主題與安全區。
• viewport 要包含 viewport-fit=cover，安全區變數才有意義：

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

• 不要放內嵌 <script>（CSP 只允許包內的腳本檔）。Vite 產生的 <script type="module" src="..."> 沒問題。

保留的路徑與檔名

包內不能有以下檔案，CLI 會擋：

路徑	原因
__im/ 底下任何檔案	容器保留（launch.js、theme.css 由容器提供）
manifest.json、signature.sig、platform.sig	CLI 產生的檔案
logic.js（雙執行緒時）	CLI 打包邏輯層的輸出檔名

路由

• 本機服務只提供包裡列出的檔案，沒有 SPA fallback：用 history 模式時，網址變成 /<密鑰>/orders 之後若整頁重新載入會 404。建議用 hash 路由（Vue Router 的 createWebHashHistory()）。
• 小程序內換頁（pushState、hash 變化）會進入 WebView 的返回歷史：Android 返回鍵、iOS 邊緣右滑會先在網頁內返回，回到第一頁才關閉小程序。程式裡要返回時呼叫 sdk.navigate.back()。
• 分享卡片可以帶起始頁（例如 /orders/1），容器一律載入 index.html，起始頁放在 getLaunch().path，由你的路由處理：

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

const start = getLaunch()?.path;
if (start && start !== '/') router.replace(start);

• 目前 CLI 只支援單一入口（index.html）的單頁應用；在 Vite 設定多個 HTML 入口會建置失敗。

圖示

icons 是「名稱 → 包內路徑」，路徑必須指向包內存在的檔案（通常放在 public/）：

icons: { '1x': 'icon@1x.png', '2x': 'icon@2x.png', '3x': 'icon@3x.png' },

public/icon@2x.png 建置後在包內的路徑是 icon@2x.png。