> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 微信掃碼登入

> 為網站接入微信開放平台掃碼登入，了解能力作用、使用前準備、配置步驟和最終效果.

微信掃碼登入讓網站使用者透過手機微信掃碼完成登入，無需額外記憶一套帳號和密碼。啟用這項能力後，superun 會根據專案現有頁面和登入方式完成接入。

<Card title="前往微信開放平台" icon="arrow-up-right" href="https://open.weixin.qq.com/" horizontal>
  建立網站應用並取得接入所需的 AppID 和 AppSecret。
</Card>

## 這項能力的作用

* 為 PC 網站增加「微信掃碼登入」入口。
* 網站已有其它登入方式時，保留原有入口並追加微信登入。
* 網站沒有登入頁面時，補充與專案風格一致的登入頁面。
* 專案尚未建立登入能力時，補充微信登入正常運作所需的基礎能力。
* 登入成功後，使用者繼續存取原本要進入的頁面或專案已有的登入成功頁。

<Note>
  本能力適用於微信開放平台「網站應用」的 PC 網站登入。它不等同於微信公眾號網頁授權，也不適用於微信小程式登入。
</Note>

## 接入後的最終效果

使用者開啟網站登入頁後，可以看到微信登入入口。進入掃碼介面後，使用手機微信掃一掃並確認授權，即可完成登入並返回網站。

```mermaid theme={null}
flowchart LR
    A["開啟網站登入頁"] --> B["選擇微信登入"]
    B --> C["手機微信掃碼確認"]
    C --> D["登入成功"]
    D --> E["進入目標頁面"]
```

登入入口的按鈕、二維碼區域、顏色和版面會沿用專案已有設計，不會強制替換為統一範本。專案原有的郵箱、手機號或其它登入方式也會繼續保留。

## 使用前需要準備

| 準備項           | 是否必須   | 說明                         |
| ------------- | ------ | -------------------------- |
| 已認證的微信開放平台帳號  | 必須     | 用於建立網站應用和使用網站登入能力          |
| 已建立並通過審核的網站應用 | 必須     | 微信掃碼登入使用的是「網站應用」，不是公眾號或小程式 |
| AppID         | 必須     | 網站應用的公開標識，填寫到 superun 配置卡  |
| AppSecret     | 必須     | 網站應用密鑰，僅填寫到 superun 的密鑰輸入框 |
| 授權回調域         | 必須     | 在微信開放平台填寫，用於允許登入結果返回專案網域   |
| 業務網域          | 本能力不需要 | 基礎掃碼登入不依賴該配置               |

## 配置微信開放平台

### 建立網站應用

1. 登入[微信開放平台](https://open.weixin.qq.com/)。
2. 建立「網站應用」，填寫應用資料並提交審核。
3. 審核通過後，在應用開發資訊中取得 AppID 和 AppSecret。

### 配置授權回調域

進入「管理中心 → 網站應用 → 開發配置 → 開發資訊 → 網域資訊」，填寫 superun 配置卡展示的**授權回調域**。

<img src="https://b.ux-cdn.com/uxarts/files/t20260824214343/7tbzqnw5.png" alt="微信開放平台：管理中心 → 網站應用 → 開發配置 → 開發資訊 → 網域資訊，編輯授權回調域" width={900} />

授權回調域只填寫網域，不包含協議和頁面路徑。例如，專案地址為 `https://example.com/login` 時，填寫：

```text theme={null}
example.com
```

<Warning>
  授權回調域必須與專案實際使用的網域一致。未配置、填寫錯誤或專案更換網域後未同步更新，都會導致微信掃碼登入無法完成。
</Warning>

### 業務網域說明

基礎微信掃碼登入不需要配置業務網域。微信開放平台的網站應用業務網域主要用於「拉起 PC 小程式」和「分享 PC 小程式」等能力，不影響本頁介紹的掃碼登入。

只有在使用這些額外能力時，才需要按微信要求配置 HTTPS 業務網域，並部署對應的 `MP_verify_xxx.txt` 網域校驗檔案。

## 在 superun 中啟用

1. 在專案對話中選擇「微信掃碼登入」。
2. 查看配置卡展示的授權回調域，並將它填寫到微信開放平台。
3. 在配置卡中填寫同一個網站應用的 AppID 和 AppSecret。
4. 確認啟用後，說明希望在專案中的哪個位置增加微信登入入口。
5. 完成專案更新與發布後，使用真實微信帳號進行一次掃碼驗證。

<Warning>
  AppSecret 屬於敏感資訊。不要把它傳送到普通聊天訊息、寫入前端程式或提交到 Git 倉庫；只在配置卡的密鑰輸入框中填寫。
</Warning>

## 專案適配方式

| 專案現況        | 接入後的表現                  |
| ----------- | ----------------------- |
| 已有登入頁面      | 在現有頁面中追加微信登入，保留原有登入方式   |
| 沒有登入頁面      | 建立與專案風格一致的登入頁面和微信登入入口   |
| 尚未建立登入能力    | 補充微信登入正常運作所需的基礎能力       |
| 已有特殊或多套登入方式 | 優先保留現有體系；如需替換或遷移，會先說明影響 |

這項能力不會自動增加郵箱註冊、手機號註冊、密碼找回、帳號綁定或帳號合併等其它功能。如有這些需求，需要在專案中單獨提出。

## 安全注意事項

* AppSecret 只用於伺服端與微信通訊，不會寫入瀏覽器頁面。
* 微信登入不會根據暱稱、頭像或手機號自動合併已有帳號。
* 停用插件不會自動刪除專案中已經上線的微信登入；移除線上入口需要單獨修改並重新發布專案。
* 專案切換到新網域後，需要同步更新微信開放平台的授權回調域。

## 驗收結果

完成接入後，應能夠確認以下結果：

1. 登入頁正常展示微信登入入口；
2. 手機微信可以掃碼並確認授權；
3. 授權完成後可以正常進入網站；
4. 專案原有登入方式仍然可用；
5. 登入頁面的樣式與專案整體設計一致；
6. AppSecret 未出現在前端頁面或程式倉庫中。

真實掃碼驗證依賴已審核的網站應用和可用的微信帳號。專案發布後應至少完成一次真實掃碼，才能確認整個登入流程可用。

如果二維碼不顯示、提示 `redirect_uri 參數錯誤` 或掃碼後登入失敗，請查看[微信掃碼登入排障](/zh-Hant/superun/skills/wechat-open-web-login/troubleshooting)。

## 微信官方資料

* [微信開放平台：網站應用微信登入](https://developers.weixin.qq.com/doc/oplatform/Website_App/WeChat_Login/Wechat_Login.html)
* [微信開放平台：網站應用業務網域](https://developers.weixin.qq.com/doc/oplatform/Website_App/guide/domain.html)
* [微信開放平台首頁](https://open.weixin.qq.com/)