> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 微信小程序
> 一鍵將專案發布為微信小程序，在 superun 內完成預覽與上傳。
請在微信內開啟視頻號教程，按步驟完成插件配置、預覽與上傳。
## 微信小程序是什麼
微信小程序是騰訊在微信生態內提供的一種輕量應用形態。它具備這些核心特徵：
* **即用即走**：使用者無需在應用商店下載安裝，掃碼或搜尋後直接使用
* **跑在微信原生容器裡**：和普通 H5（跑在 WebView 裡）不同，小程序執行在微信原生容器中，可以呼叫 `wx.*` 系列原生 API
* **依託微信關係鏈分發**：可以透過分享、掃碼、附近的小程序等方式快速觸達使用者
在 superun 中，你只需準備好已發布的 H5 專案，superun 會將其建構為微信小程序程式碼包，並支援一鍵預覽與上傳到微信公眾平台。
## 使用須知
* 當前方案使用小程序 web-view 元件，微信限制[個人類型小程序不支援 web-view](https://developers.weixin.qq.com/miniprogram/dev/component/web-view.html)，**僅企業主體小程序可用**。
## 接入前的必要配置（總覽）
在 superun 啟用微信小程序插件之前，你需要先在 [微信公眾平台](https://mp.weixin.qq.com/) 準備好下面三件配置：
| 配置項 | 檔案 / 形態 | 用途 | 在哪裡取得 |
| ------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------- | ------------------------------- |
| AppID | 18 位字元字串 | 小程序唯一身分，綁定 superun 專案時填入 | 微信公眾平台 → 開發管理 → 開發設定 → 開發者 ID |
| [小程序程式碼上傳密鑰（.pem 私鑰）](https://developers.weixin.qq.com/miniprogram/dev/devtools/ci.html) | `private.{appid}.key`（PEM 格式 RSA 私鑰） | superun 代你把小程序程式碼包上傳到微信，進行預覽/審核 | 微信公眾平台 → 開發管理 → 開發設定 → 小程序程式碼上傳 |
| [業務網域校驗檔案](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/domain.html) | `MP_verify_xxxx.txt` | 讓微信確認你擁有該 H5 網域，配置後才能在小程序裡透過 `` 載入你的 H5 | 微信公眾平台 → 開發管理 → 開發設定 → 業務網域 |
為什麼需要這三件，可以從 superun 的小程序執行模型理解：
* AppID 解決「這是哪個小程序」——所有上傳、登入、支付等操作都基於這個 ID
* 上傳密鑰解決「程式碼怎麼上去」——superun 用它代表你的身分，把程式碼包推送到微信
* 業務網域校驗檔案解決「H5 怎麼被允許在小程序裡展示」——微信只允許已認領網域的頁面在 `` 中開啟
## 分段取得流程
### 1. 取得 AppID
**前置準備**：
* 已在微信公眾平台註冊帳號，類型為「小程序」
* 已完成主體資訊登記（個人或企業，兩種主體都能取得 AppID，但可用能力會有差異）
**操作路徑**：
1. 開啟 [微信公眾平台](https://mp.weixin.qq.com/) 並使用管理員帳號登入
2. 左側選單進入「**開發管理**」
3. 頂部切換到「**開發設定**」分頁
4. 捲動到「**開發者 ID**」分塊，複製 **AppID（小程序 ID）**
**後續動作**：在 superun 後台「微信小程序」插件的配置項裡貼上該 AppID。
### 2. 取得程式碼上傳密鑰（.pem 私鑰）
**前置準備**：
* 已確認本人是該小程序的「管理員」（一般運營者無權下載上傳密鑰）
**操作路徑**：
1. 在「**開發管理 → 開發設定**」頁面繼續往下捲動，找到「**小程序程式碼上傳**」分塊
2. 如果是首次使用，點擊「**生成**」；如果之前生成過、本機已遺失，可以「**重設**」（重設會讓舊密鑰立即失效）
3. 瀏覽器會自動下載一個檔案，檔名形如 `private.{appid}.key`，這就是你需要的程式碼上傳密鑰
4. 用記事本/文字編輯器開啟，可以看到 `-----BEGIN RSA PRIVATE KEY-----` 開頭——這是標準的 PEM 格式 RSA 私鑰
**配套：IP 白名單**：
同一分塊下還有一個「**IP 白名單**」設定。superun 會從固定的伺服器 IP 出口去呼叫上傳介面，**必須把 superun 提供的出口 IP 全部加入白名單**，否則上傳會被微信拒絕並回傳 `40164` 錯誤。
請在 superun 小程序外掛設定頁查看最新的出口 IP 列表，複製後貼到微信公眾平台。格式示例：
```
198.51.100.1
198.51.100.2
```
以上為示例格式，實際 IP 請以 superun 產品內展示的為準。
上傳密鑰涉及程式碼發布權限，請妥善保管：
* 檔案只在下載那一刻能取得，關閉頁面後微信不會再展示密鑰內容
* 如果檔案遺失，必須在公眾平台「重設」一次，然後把新密鑰重新填入 superun
* 不要把這個檔案提交到任何程式碼倉庫，特別是公開倉庫
### 3. 取得並部署業務網域校驗檔案
**操作路徑**：
1. 在「**開發管理 → 開發設定**」頁面捲動到「**業務網域**」分塊
2. 點擊「**修改**」（首次配置點「**開始配置**」）
3. 在彈出的浮層裡，按提示先點擊「**下載校驗檔案**」按鈕，瀏覽器會下載一個檔案，檔名形如 `MP_verify_AbCdEf123456.txt`
4. 把這個檔案放到你 H5 網站的**根目錄**——也就是要讓 `https://你的網域/MP_verify_AbCdEf123456.txt` 這個 URL 能被直接存取到，回傳檔案內容
5. 回到浮層裡，在網域輸入框中填入業務網域，**僅填 host，不帶協定、不帶路徑**，例如 `my-app.superun.com`
6. 點擊「**儲存**」，微信會立即去 GET 上一步那個 URL 做校驗，校驗通過後業務網域生效
校驗檔案的部署方式取決於你的網站託管方案：放到靜態資源目錄、設定 nginx 透傳、或在框架裡加一條靜態路由都可以，只要保證從公網根路徑能存取到這一個檔案即可。
這裡填寫的網域，可以在 superun 的小程序配置頁直接看到推薦的填寫值，複製貼上到微信後台即可。
## 接入前的準備清單
正式在 superun 啟用微信小程序插件前，請確認以下項已就緒：
* [x] 已註冊並完成主體認證的小程序帳號，且目前操作者是管理員
* [x] AppID 已記錄
* [x] 已在公眾平台生成程式碼上傳密鑰 `private.{appid}.key` 並妥善保存
* [x] 已在公眾平台下載業務網域校驗檔案並妥善保存
## 三項配置如何串起來
下面這張圖把三件配置之間的依賴關係拉成一條線，可以對照檢查每一步是否完成：
```mermaid theme={null}
flowchart TD
Start[微信公眾平台後台] --> A[拿到 AppID]
A --> B[生成程式碼上傳密鑰 .pem]
A --> C[下載業務網域校驗檔案]
B --> D[在 superun 填入 **AppID** 與上傳**私鑰**和**網域校驗檔案**]
C --> D
D --> E[生成小程序]
E --> F[發起小程序程式碼上傳與預覽]
```
## 在 superun 內一鍵預覽 / 上傳
完成上述設定後，你**無需開啟微信開發者工具**即可在 superun 內完成程式碼包預覽與上傳：
* **一鍵預覽**：在微信小程序插件詳情頁點選「**預覽**」，superun 會建構小程序程式碼包並直接生成預覽 QR Code，用微信掃碼即可在手機上體驗
* **一鍵上傳**：點選「**上傳**」，superun 會把程式碼包推送到微信公眾平台後台，**無需再切換到微信開發者工具**；上傳完成後可在微信公眾平台「版本管理」中提交審核或體驗
* **設定表單 UX 升級**：插件詳情頁表單互動全面優化，關鍵欄位（AppID / 上傳密鑰 / 業務網域）的填寫與校驗提示更清晰
* **行動端預覽入口**：在行動端預覽入口的位置與互動調整為更易觸達的位置，預覽體驗更順暢
預覽與上傳的具體按鈕文案、位置以你目前產品版本為準。