> ## 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.

# 微信掃碼登入排障

> 微信掃碼登入常見問題排查：二維碼不顯示、redirect_uri 參數錯誤、掃碼後登入失敗、發布後無法登入，按現象定位授權回調域與憑證配置問題.

本文是 [微信掃碼登入](/zh-Hant/superun/skills/wechat-open-web-login) 的補充。掃碼登入出現異常時，絕大多數問題出在微信開放平台側的配置（授權回調域、應用審核狀態）或憑證填寫，按下面的現象逐條對照，多數問題可以在幾分鐘內自行解決。

<Note>
  當前應填寫的授權回調域，可在 superun 專案的「微信掃碼登入 → 配置」頁查看並複製；專案未發布時顯示預覽網域，發布後顯示正式網域。
</Note>

## 二維碼區域顯示「redirect\_uri 參數錯誤」

微信在生成二維碼前會先校驗兩件事，任何一項不通過都會顯示這個錯誤，而不是二維碼：

1. **授權回調域未配置或與實際網域不一致。** 到微信開放平台「管理中心 → 網站應用 → 開發配置 → 開發資訊 → 網域資訊」，把「微信掃碼登入 → 配置」頁展示的授權回調域原樣填入。只填網域，不含 `https://`、端口和路徑。
2. **網站應用尚未通過審核。** 應用在審核通過前無法使用掃碼登入，請在微信開放平台查看審核狀態。

## 二維碼區域一直空白

二維碼腳本由微信官方網域（`res.wx.qq.com`）提供，區域一直空白通常是腳本加載失敗：

* 檢查設備網絡後刷新頁面重試；
* 如果頁面提供了「重新加載」按鈕，點擊重試。

## 提示憑證缺失或二維碼無法初始化

AppID / AppSecret 尚未保存到 superun。到「微信掃碼登入 → 配置」頁點「修改憑證」，填入微信開放平台**網站應用**的 AppID 和 AppSecret 並保存。

<Warning>
  AppSecret 是 32 位字符的密鑰，不以 `wx` 開頭。誤填 AppID 或小程序密鑰是最常見的錯誤，會導致掃碼後登入失敗。
</Warning>

## 掃碼成功但登入失敗

* **提示安全校驗失敗**：二維碼停留時間過長或頁面被重複使用，回到登入頁重新掃碼即可。
* **提示授權碼無效或已使用**：微信授權碼約 10 分鐘有效且只能使用一次，重新掃碼獲取新的授權碼。
* **反覆失敗**：多為 AppSecret 填錯（見上一節），重新保存憑證後再試。

## 專案發布後微信登入突然失效

專案發布後，訪問網域會從預覽網域切換為正式網域，而微信開放平台仍登記著舊網域。到「微信掃碼登入 → 配置」頁複製當前展示的授權回調域，到微信開放平台更新後即可恢復。

## 仍未解決

在專案對話中直接描述現象（例如「二維碼不顯示」「掃碼後提示登入失敗」），superun 會結合專案日誌進一步排查。