主题
微信登录配置
扩展包
本页功能由微信扩展包提供（服务端 WECHAT_PACK_ENABLED，用户端与管理端 VITE_WECHAT_ENABLED）。关闭或删除该包后，本页菜单与接口一并消失，登录方式里不再出现微信。开关说明见 扩展包开关与裁剪。
要让用户在 PC Web 使用微信开放平台网站登录、使用公众号扫码登录、在微信内静默登录，或接收公众号自动回复，需要按实际场景配置微信开放平台、微信公众平台和管理后台。
- 后台入口：登录接入 / 微信配置 / 微信登录配置
准备材料
配置前先准备：
| 材料 | 从哪里获取 | 用途 |
|---|---|---|
| 公众号 AppId | 微信公众平台的开发信息 | 识别当前公众号 |
| 公众号 AppSecret | 微信公众平台的开发信息 | 获取微信接口调用凭证 |
| Token | 自行设置，后台和微信公众平台保持一致 | 微信服务器校验回调来源 |
| 网站应用 AppID | 微信开放平台网站应用 | PC Web 微信登录 |
| 网站应用 AppSecret | 微信开放平台网站应用 | PC Web 微信登录授权换取用户身份 |
| 网站登录回调地址 | 管理后台或网站地址拼接 | 微信开放平台网站应用授权回调 |
| 站点正式域名 | 基础信息 中的网站地址 | 生成回调地址和网页登录授权 |
| HTTPS 证书 | 域名服务商或服务器面板 | 微信回调和网页授权建议使用 HTTPS |
如果只是本地调试，微信服务器无法访问 localhost。需要使用公网测试域名或内网穿透，并确保 /api/official/notify 能被微信服务器访问。
PC Web 的开放平台网站登录依赖微信开放平台“网站应用”。如果还希望和公众号扫码登录、微信内授权登录打通同一用户身份，网站应用和公众号必须绑定到同一个微信开放平台账号下，否则 UnionID 可能缺失或不一致。
后台配置项怎么填
| 配置项 | 用途 | 从哪里找 | 填写建议 |
|---|---|---|---|
| 是否开启微信登录注册 | 控制用户端是否展示微信扫码登录入口 | 后台选择 | 微信公众平台服务器配置验证通过后再开启 |
| 是否开启微信静默 | 微信内访问时尝试自动登录 | 后台选择 | 网页授权域名配置通过后再开启 |
| 公众号名称 | 后台识别用名称 | 微信公众平台 → 账号详情，或公众号主页 | 填公众号实际名称，方便管理员辨认 |
| AppId | 标识当前公众号 | 微信公众平台 → 设置与开发 → 基本配置 → 公众号开发信息 | 复制 AppID，不是原始 ID，也不是微信号 |
| Token | 校验微信服务器回调来源 | 你自行设置，同时填到微信公众平台服务器配置中 | 自定义一串不易猜的字符串，后台和微信公众平台必须完全一致 |
| AppSecret | 获取公众号接口调用凭证 | 微信公众平台 → 设置与开发 → 基本配置 → 公众号开发信息 → AppSecret | 创建或重置后立即保存；不要公开截图 |
| 开启网站登录 | 控制 PC Web 登录弹窗是否优先展示微信开放平台网站登录 | 后台选择 | 网站应用 AppID、AppSecret 和回调域确认后再开启 |
| 网站应用 AppID | 标识微信开放平台网站应用 | 微信开放平台 → 管理中心 → 网站应用 → 应用详情 | 不要填写公众号 AppID |
| 网站应用 AppSecret | 微信开放平台网站应用密钥 | 微信开放平台 → 管理中心 → 网站应用 → 应用详情 | 不要填写公众号 AppSecret；不要公开截图 |
| 网站登录回调地址 | 授权完成后微信回跳的地址 | 留空时系统使用网站地址 + /auth/callback/wechat_open_web | 回调域必须与微信开放平台后台配置一致 |
| 开启快捷确认 | 允许微信官方组件优先展示当前电脑微信快捷确认 | 后台选择 | 建议开启；用户仍可切换为扫码 |
| 开启备用跳转 | 官方组件加载失败时允许使用后端生成的登录跳转地址 | 后台选择 | 建议开启，便于网络受限环境降级 |
| 微信开放平台 URL | 微信授权跳转地址 | 代理或私有网关提供 | 没有代理需求时留空，系统使用微信官方地址 |
| 微信 API 基础 URL | 微信接口请求地址 | 代理或私有网关提供 | 没有代理需求时留空 |
| 微信公众平台 URL | 微信公众平台地址 | 代理或私有网关提供 | 没有代理需求时留空 |
网站应用 AppID / AppSecret 和公众号 AppID / AppSecret 是两组不同凭证。即使两者绑定到同一个开放平台账号，也不要混填。
第三方代理地址位于微信登录配置页底部，只有在服务器无法直连微信官方接口，或需要使用内部网关、第三方代理服务时才需要填写。留空则使用微信官方地址，大多数站点保持为空即可。
公众平台配置步骤
第一步：复制 AppId 和 AppSecret
- 登录 微信公众平台。
- 进入“设置与开发 → 基本配置”或“设置与开发 → 开发接口管理 → 基本配置”。
- 找到公众号开发信息，复制 AppId。
- 查看或重置 AppSecret，并保存到安全位置。
- 回到管理后台，填写公众号名称、AppId、AppSecret。
AppSecret 相当于公众号接口密钥，不要发给无关人员，也不要写在公开文档或截图里。
微信开放平台网站登录
PC Web 登录使用微信开放平台的网站应用能力。用户端登录弹窗会加载微信官方登录组件，支持当前电脑微信快捷确认；如果当前环境不支持快捷确认，用户仍可以扫码登录。
配置步骤：
- 登录 微信开放平台。
- 创建或进入“网站应用”，确认应用已经具备微信登录能力。
- 复制网站应用 AppID 和 AppSecret，填写到管理后台“微信开放平台网站登录”区块。
- 在管理后台确认网站登录回调地址。留空时系统使用“网站地址 +
/auth/callback/wechat_open_web”。 - 在微信开放平台后台配置授权回调域，域名必须与管理后台中的回调地址域名一致。
- 如果需要和公众号身份打通，在微信开放平台中确认网站应用和公众号绑定到同一个开放平台账号。
微信开放平台后台通常配置的是回调域名，不是完整 URL；管理后台保存的是完整回调地址，两边的域名必须一致。
正确示例：
text
管理后台回调地址：https://agent.example.com/auth/callback/wechat_open_web
微信开放平台授权回调域：agent.example.com不要把公众号网页授权域名、公众号 AppSecret 或微信支付密钥填到网站登录配置里。
第二步：填写服务器配置
在微信公众平台进入“设置与开发 → 基本配置 → 服务器配置”，填写：
text
URL：https://你的域名/api/official/notify
Token：与管理后台 Token 保持一致
消息加解密方式：明文模式当前版本按明文消息处理公众号事件。若在微信公众平台选择“兼容模式”或“安全模式”，需要额外确认服务端已支持消息加解密，否则关注、扫码、自动回复等事件可能无法正常处理。
填写完成后，先保存管理后台，再到微信公众平台提交验证。微信会向 URL 发起一次 GET 校验，请确保：
- 域名可以公网访问。
- HTTPS 证书有效。
- 反向代理已把
/api转发到后端服务。 - 管理后台 Token 和微信公众平台 Token 完全一致。
第三步：配置网页授权域名
静默登录和微信内授权登录都依赖网页授权域名。微信后台入口可能随版本略有变化，一般在“公众号设置 / 功能设置 / 网页授权域名”，或“接口权限 / 网页服务 / 网页帐号”附近。
网页授权域名只填写域名，不要填写协议和路径。
正确示例：
text
agent.example.com不要填写：
text
https://agent.example.com/#/login如果微信要求下载校验文件，请按页面提示把校验文件放到站点根目录，并确认浏览器能直接访问该文件。完成校验后，再开启管理后台的“微信静默”。
官方说明中，snsapi_base 适合静默获取 OpenID，snsapi_userinfo 会弹出授权页并获取更完整的用户信息。当前系统会根据登录、绑定等场景自动处理授权流程，管理员只需要保证授权域名配置正确。
用户端效果
PC Web 用户打开登录弹窗后，会优先看到微信开放平台网站登录组件。已登录桌面微信且环境支持时，微信可能展示当前电脑微信快捷确认；否则用户可以扫码确认。未启用网站登录或组件加载失败时，系统可以回退到公众号二维码登录。
微信内访问时，如果已开启静默登录并配置了网页授权域名，系统会尝试自动识别当前微信用户，减少重复登录操作。
自动回复消息
| 配置项 | 触发时机 | 文案建议 |
|---|---|---|
| 订阅公众号欢迎消息 | 用户关注公众号 | 简短说明可以扫码登录或绑定账号 |
| 绑定账号成功回复消息 | 用户绑定微信成功 | 告诉用户返回页面继续使用 |
| 绑定账号失败回复消息 | 用户绑定失败 | 提醒重新扫码或联系管理员 |
| 扫码登录回复消息 | 用户扫码登录成功 | 提醒回到浏览器页面 |
| 自定义回复的默认信息 | 用户发送普通文本但未命中规则 | 告知当前公众号主要用于登录和通知 |
示例：
text
绑定成功。你现在可以回到页面继续使用。回复文案不建议写太长。公众号会话里，用户更需要知道下一步要做什么。
登录身份说明
PC Web 网站登录会记录为微信开放平台网站应用身份；公众号扫码登录、微信内授权登录和微信绑定账号会记录为微信公众号身份。两类身份的 OpenID 不同，系统不会混用。
如果网站应用和公众号绑定到同一个微信开放平台账号，微信会提供同一用户的 UnionID，系统可据此把 PC Web 网站登录和公众号身份打通到同一个账号。若没有绑定到同一个开放平台账号，UnionID 可能缺失或不一致，系统无法自动合并身份。
验证方法
- 保存管理后台配置。
- 如使用 PC Web 网站登录，先在微信开放平台确认网站应用 AppID、AppSecret 和授权回调域。
- 如使用公众号能力，在微信公众平台提交服务器配置验证。
- 打开用户端登录弹窗，确认 PC Web 优先展示微信开放平台网站登录组件。
- 使用桌面微信快捷确认或扫码，确认页面是否完成登录。
- 关闭网站登录或模拟组件不可用时，确认公众号二维码 fallback 是否符合预期。
- 在微信内打开用户端，验证公众号静默登录是否生效。
常见问题
微信平台验证失败？
检查服务器地址是否公网可访问、Token 是否一致、站点是否使用 HTTPS、反向代理是否正确转发 /api/official/notify。
扫码后没有登录成功？
先确认微信登录开关已开启，再检查公众号事件回调是否正常、AppSecret 是否正确、用户是否已经关注公众号，以及服务器日志里是否有微信接口错误。
PC Web 微信登录组件没有出现？
检查“微信开放平台网站登录”是否开启，网站应用 AppID / AppSecret 是否填写，用户端是否在 PC Web 环境访问。微信内浏览器和移动端默认不展示网站登录组件。
开放平台回调提示异常？
检查管理后台的“网站登录回调地址”域名是否和微信开放平台后台的授权回调域一致。正式环境建议使用 HTTPS；不要填写公众号网页授权域名路径或登录页地址。
PC Web 登录和公众号登录为什么没有合并成同一个账号？
确认网站应用和公众号是否绑定在同一个微信开放平台账号下。只有同一开放平台账号下微信才会提供可打通的 UnionID。
静默登录没有生效？
检查网页授权域名是否只填写了域名，未带 http://、https:// 或路径，并确认用户确实在微信内打开站点。
AppSecret 重置后要做什么？
需要同步更新管理后台中的 AppSecret。旧 AppSecret 失效后，微信接口调用会失败，扫码登录、绑定和菜单同步都可能受影响。