> ## 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-Hans/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/)