1. 项目概述为什么需要自己实现微信扫码登录在开发一个需要用户登录的Web应用或桌面应用时直接让用户注册账号、设置密码再通过邮箱或手机验证这套流程对用户来说已经越来越繁琐了。用户可能只是想来试用一下或者临时访问某个功能冗长的注册流程会直接劝退他们。这时第三方登录尤其是微信扫码登录就成了一个极佳的解决方案。它利用用户手机上已经安装且高度信任的微信应用通过扫描二维码的方式一键完成身份授权极大地简化了登录流程提升了用户体验和转化率。你可能在很多网站和应用上都见过这个功能页面上展示一个动态刷新的二维码用户用微信“扫一扫”手机上点击确认网页就自动登录成功了。这个看似简单的交互背后其实是一套标准的OAuth 2.0授权流程。作为开发者我们不需要去破解微信的协议而是遵循微信开放平台提供的标准接口来实现。今天我就以一个C#后端开发者的视角带你从零开始完整地走一遍这个流程把其中的技术细节、踩过的坑和优化心得都分享给你。无论你是想为你的ASP.NET Core Web应用、WinForm桌面程序还是Unity游戏添加这个功能这篇指南都能给你提供清晰的路径。2. 核心原理与流程拆解OAuth 2.0在微信扫码登录中的应用在动手写代码之前我们必须先理解微信扫码登录背后的工作原理。它本质上是OAuth 2.0授权码模式的一个具体应用场景。OAuth 2.0是一种开放标准允许用户授权第三方应用访问他们存储在另一服务提供商这里是微信上的信息而无需将用户名和密码提供给第三方应用。整个扫码登录流程涉及三个角色我们的应用第三方网站、微信开放平台服务提供商和用户。流程可以拆解为以下几个核心步骤2.1 流程时序与状态解析前端生成二维码我们的网站前端需要向我们的后端服务器请求一个“临时门票”。后端服务器会拿着这个请求去微信开放平台换取一个唯一的、有时效性的二维码URL。这个URL对应着一个本次登录的“场景值”scene。前端拿到这个URL后将其渲染成二维码图片展示给用户。这里的关键是这个二维码本身并不包含任何用户信息它只是一个指向微信服务器的“入口”并携带了能让我们后端识别这次登录事件的标识。用户扫码与授权用户使用手机微信扫描二维码。微信客户端会识别出这是一个登录授权请求并引导用户到一个确认页面上面会显示我们的应用名称和请求的权限如获取昵称、头像。用户点击“同意”后微信服务器就知道“哦用户XXX同意授权给应用YYY了”。微信回调与票据交换用户授权后微信服务器不会直接通知我们的前端因为前端是不可信的。它会根据我们最初生成二维码时提供的“回调地址”redirect_uri将授权结果一个一次性的code发送给我们的后端服务器。这个code是本次授权的凭证但它还不是最终的访问令牌。后端兑换用户信息我们的后端服务器在收到微信发来的code后需要立即用它再加上我们应用的AppSecret一个绝不能泄露的密码去微信服务器兑换两样东西access_token访问令牌和openid用户在当前应用下的唯一标识。拿到access_token和openid后我们才能进一步调用微信的接口获取用户的昵称、头像等基本信息。建立本地会话获取到用户信息后我们的后端业务逻辑才开始介入。我们通常会做这几件事检查这个openid是否已经在我们的用户系统中存在。如果存在就直接取出对应的本地用户ID如果不存在则用微信返回的信息创建一条新的用户记录。然后生成我们应用自身的会话标识例如一个JWT Token或Session ID返回给前端。前端拿到这个标识才算真正登录成功可以访问需要登录的页面了。注意整个安全链条的核心在于AppSecret和code。AppSecret必须永远保存在后端任何情况下都不能出现在前端代码、客户端配置或日志中。code是一次性的且必须在短时间内通常建议在5分钟内使用用后即废。正是这两个机制保证了即使二维码和code在传输中被截获攻击者也无法冒充用户。2.2 微信开放平台准备工作创建网站应用理论清楚了我们得先有“门票”才能入场。所有与微信服务器交互的权限都来自于你在微信开放平台创建的一个“网站应用”。注册与认证访问微信开放平台完成开发者注册和企业资质认证个人开发者也可以但部分高级接口和支付功能会受限。认证是必须的否则无法获得AppSecret也无法使用网页授权等核心功能。创建网站应用在管理中心找到“网站应用”栏目点击创建。你需要填写应用名称、简介、官网地址等。最关键的是授权回调域。这个域必须是你后端服务接收微信code的域名且需要精确到一级或二级域名例如www.yoursite.com或api.yoursite.com不能带http://或端口号也不能是IP地址。微信会对重定向请求的域名做严格校验不匹配则会失败。获取关键凭据应用创建并通过审核后审核通常需要几个工作日你就能在应用详情页找到你的AppID和AppSecret。把它们妥善保存特别是AppSecret要像保护数据库密码一样保护它。我建议将其存入环境变量或专业的密钥管理服务绝对不要硬编码在代码里或提交到版本库。3. 后端核心实现从生成二维码到建立会话接下来我们用C#以ASP.NET Core为例来实现后端逻辑。我会使用HttpClient进行网络请求并使用Newtonsoft.Json或System.Text.Json处理JSON数据。3.1 项目结构与依赖准备首先创建一个ASP.NET Core Web API项目。在appsettings.json中配置微信的凭据{ WeChat: { AppId: 你的AppId, AppSecret: 你的AppSecret, RedirectUri: https://你的域名.com/api/wechat/callback // 后端回调地址 } }然后创建一个对应的配置类WeChatSettings和一个服务类IWeChatAuthService及其实现。我们将核心逻辑封装在服务中。3.2 第一步生成带场景值的二维码URL前端需要展示二维码因此我们需要提供一个API返回生成二维码所需的临时数据。通常我们会生成一个随机字符串作为本次登录的“状态码”state用于防止CSRF攻击同时也可以将其作为我们后台标识这次登录请求的scene_id。// 服务接口方法 public async TaskQrCodeResponse GetLoginQrCodeAsync() { // 1. 生成一个随机的state并关联一个临时存储如分布式缓存Redis var state Guid.NewGuid().ToString(N); var cacheKey $wechat:login:state:{state}; // 存储state并设置较短过期时间例如300秒 await _cache.SetStringAsync(cacheKey, created, TimeSpan.FromSeconds(300)); // 2. 构造请求微信的URL // 微信生成二维码的地址是固定的 var baseUrl https://open.weixin.qq.com/connect/qrconnect; // 参数需要按照微信文档顺序拼接这里使用字典方便管理 var parameters new Dictionarystring, string { [appid] _settings.AppId, [redirect_uri] Uri.EscapeDataString(_settings.RedirectUri), [response_type] code, [scope] snsapi_login, // 固定值用于网站应用扫码登录 [state] state }; // 构造查询字符串 var queryString string.Join(, parameters.Select(p ${p.Key}{p.Value})); var qrCodeUrl ${baseUrl}?{queryString}#wechat_redirect; // 3. 返回给前端 return new QrCodeResponse { QrCodeUrl qrCodeUrl, State state, ExpiresIn 300 // 告诉前端二维码的有效期 }; }前端拿到qrCodeUrl后可以使用任何二维码生成库如qrcode.js将其渲染成图片。同时前端需要启动一个轮询定期询问后端“state对应的登录成功了吗”。3.3 第二步处理微信回调并兑换AccessToken当用户扫码并授权后微信会跳转到我们设置的RedirectUri并带上code和state参数。我们需要一个Controller Action来处理这个回调。[HttpGet(callback)] public async TaskIActionResult Callback([FromQuery] string code, [FromQuery] string state) { // 1. 验证state防止CSRF var cacheKey $wechat:login:state:{state}; var cachedState await _cache.GetStringAsync(cacheKey); if (string.IsNullOrEmpty(cachedState)) { return BadRequest(无效的state或二维码已过期); } // 验证通过后立即删除这个state防止被重复使用 await _cache.RemoveAsync(cacheKey); // 2. 用code和AppSecret向微信兑换access_token var tokenUrl https://api.weixin.qq.com/sns/oauth2/access_token; var tokenParams new Dictionarystring, string { [appid] _settings.AppId, [secret] _settings.AppSecret, [code] code, [grant_type] authorization_code }; using var httpClient _httpClientFactory.CreateClient(); var response await httpClient.GetStringAsync(${tokenUrl}?{ToQueryString(tokenParams)}); var tokenResult JsonConvert.DeserializeObjectAccessTokenResponse(response); // 3. 检查微信返回的错误 if (!string.IsNullOrEmpty(tokenResult.ErrorCode)) { _logger.LogError($微信获取access_token失败: {tokenResult.ErrorMessage}); return BadRequest($授权失败: {tokenResult.ErrorMessage}); } // 4. 用access_token和openid获取用户基本信息 var userInfoUrl https://api.weixin.qq.com/sns/userinfo; var userInfoParams new Dictionarystring, string { [access_token] tokenResult.AccessToken, [openid] tokenResult.OpenId, [lang] zh_CN }; var userInfoResponse await httpClient.GetStringAsync(${userInfoUrl}?{ToQueryString(userInfoParams)}); var userInfo JsonConvert.DeserializeObjectWeChatUserInfoResponse(userInfoResponse); if (!string.IsNullOrEmpty(userInfo.ErrorCode)) { // 有时access_token可能失效这里可以加入重试逻辑 _logger.LogError($获取用户信息失败: {userInfo.ErrorMessage}); return BadRequest($获取用户信息失败); } // 5. 业务处理查找或创建本地用户 var localUser await _userService.FindOrCreateUserAsync(userInfo.OpenId, userInfo.Nickname, userInfo.HeadImgUrl); // 6. 生成应用自身的登录凭证例如JWT var appToken _jwtService.GenerateToken(localUser.Id, localUser.Username); // 7. 这里不能直接返回JSON给这个回调请求因为这是微信服务器发起的重定向。 // 我们需要将登录成功的结果appToken, state通知给前端轮询接口。 // 常见做法将结果存入缓存key为最初的state var loginResultKey $wechat:login:result:{state}; var loginResult new LoginResult { Success true, Token appToken, UserId localUser.Id }; await _cache.SetStringAsync(loginResultKey, JsonConvert.SerializeObject(loginResult), TimeSpan.FromSeconds(60)); // 8. 回调页面重定向到前端一个“登录成功”的静态页面该页面会通知主窗口或轮询接口。 // 或者如果前端是桌面应用这里可以返回一个包含token的简单HTML由内嵌浏览器捕获。 return Redirect(${_frontendHost}/login-success?state{state}); }实操心得AccessTokenResponse和WeChatUserInfoResponse这两个模型类需要严格对应微信API返回的JSON字段。微信的字段命名风格是蛇形snake_case如access_token、expires_in在C#中我们可以用[JsonProperty(access_token)]特性来映射。另外所有微信接口的调用都要做好异常处理和日志记录因为网络波动或微信接口临时故障是常有的事。3.4 第三步前端轮询与登录状态确认前端在展示二维码后就需要开始轮询一个后端接口检查state对应的登录是否已完成。[HttpGet(poll/{state})] public async TaskIActionResult PollLoginResult(string state) { var resultKey $wechat:login:result:{state}; var resultJson await _cache.GetStringAsync(resultKey); if (string.IsNullOrEmpty(resultJson)) { // 结果还未产生或已过期 return Ok(new PollingResponse { Status pending }); } // 获取到结果后可以将其从缓存中移除或者让前端多轮询几次确保拿到 var result JsonConvert.DeserializeObjectLoginResult(resultJson); await _cache.RemoveAsync(resultKey); // 移除已消费的结果 return Ok(new PollingResponse { Status success, Data result }); }前端JavaScript轮询逻辑大致如下function pollLoginResult(state) { const pollInterval setInterval(async () { const resp await fetch(/api/wechat/poll/${state}); const data await resp.json(); if (data.status success) { clearInterval(pollInterval); // 将获取到的token存入localStorage或Cookie localStorage.setItem(auth_token, data.data.token); // 跳转到登录后的首页 window.location.href /dashboard; } else if (data.status pending) { // 继续等待 console.log(等待扫码授权...); } }, 1500); // 1.5秒轮询一次 }4. 安全加固与生产环境注意事项实现基本功能只是第一步要上线生产环境必须考虑以下安全与稳定性问题。4.1 State参数的安全性与防重放攻击我们使用state参数主要目的是防止CSRF攻击。但它的实现必须满足以下几点足够随机且不可预测使用密码学安全的随机数生成器如Guid.NewGuid()或RandomNumberGenerator。与用户会话关联在生成state时可以将其与当前未认证的会话ID如果有绑定验证时一并检查。一次性使用一旦用于兑换code立即在服务端使其失效无论成功与否。设置合理有效期存储在缓存中并设置一个略长于二维码有效期的过期时间如300秒过期自动清理防止缓存无限制增长。4.2 AccessToken的存储与刷新我们通过code兑换得到的是微信的access_token它有自己的有效期通常为7200秒。在我们的扫码登录场景中这个token主要用于一次性获取用户信息之后便不再需要。因此我们不应该存储这个微信的access_token。获取用户信息后我们的任务就完成了。这与我们开发微信小程序或公众号时需要长期保存并刷新access_token的场景完全不同。4.3 网络超时与重试机制调用微信API是网络IO操作必须设置合理的超时时间例如10秒并实现重试逻辑。对于获取access_token和userinfo这类关键步骤建议实现简单的指数退避重试。public async TaskT CallWeChatApiWithRetryT(FuncTaskT apiCall, int maxRetries 2) { int retryCount 0; while (true) { try { return await apiCall(); } catch (HttpRequestException ex) when (retryCount maxRetries) { retryCount; var delay TimeSpan.FromSeconds(Math.Pow(2, retryCount)); // 指数退避 _logger.LogWarning(ex, $调用微信API失败第{retryCount}次重试等待{delay.TotalSeconds}秒); await Task.Delay(delay); } } }4.4 日志与监控记录详细的日志特别是在兑换code和获取用户信息失败时需要将微信返回的错误码和错误信息记录下来方便排查。监控接口的调用成功率、耗时和频率设置告警。5. 常见问题排查与调试技巧在实际开发中你几乎一定会遇到下面这些问题。这里我整理了排查清单。5.1 二维码不显示或“该链接无法访问”原因1回调域名未设置或设置错误这是最常见的原因。登录微信开放平台检查“网站应用”的“授权回调域”。必须与代码中RedirectUri的域名部分完全一致不包含http://和端口。例如回调域设为www.example.com那么RedirectUri可以是https://www.example.com/callback但不能是https://api.example.com/callback或http://www.example.com:8080/callback。原因2生成二维码的URL参数错误或未编码确保redirect_uri参数已经进行了URL编码。使用Uri.EscapeDataString方法。检查scope参数是否为snsapi_login。原因3AppId或AppSecret错误仔细核对配置。5.2 扫码后提示“redirect_uri参数错误”原因几乎可以肯定是回调地址的问题。除了上述域名匹配问题还需注意回调地址的路径如/api/wechat/callback必须是真实存在且可被外网访问的。在开发环境使用localhost或127.0.0.1是不行的微信服务器无法回调到你的本地机器。开发时需要使用内网穿透工具如ngrok、frp将本地服务暴露到一个公网域名并将该域名配置到微信回调域中。5.3 兑换access_token时返回40029或40163错误码40029无效的code说明code已经被使用过或者已经过期超过5分钟。请检查后端逻辑是否对同一个code重复发起了兑换请求。错误码40163code已被使用同上。确保你的回调接口是幂等的或者通过state的验证来防止重复处理。5.4 获取用户信息返回48001或40001错误码48001api功能未授权检查scope参数是否正确设置为snsapi_login。也可能是你的微信开放平台应用没有通过审核部分接口权限未开通。错误码40001无效的access_token可能access_token已经过期或者你在获取用户信息时传入的access_token与openid不匹配。确保你是用兑换access_token时返回的那个token和openid配对去调用用户信息接口。5.5 前端轮询不到结果一直pending检查state的生命周期确保生成二维码时存储了state在回调处理成功后将结果存储时使用的state键名与轮询接口读取的键名完全一致。注意缓存服务如Redis的连接和读写是否正常。检查回调逻辑在回调接口中是否成功将登录结果写入了缓存可以在写入后立即读取一次验证。同时检查回调接口完成后是否正确地重定向到了前端页面前端页面是否能触发轮询状态的更新。网络问题检查你的后端API特别是回调接口和轮询接口是否可以被公网正常访问防火墙和云安全组策略是否放行了相应端口。6. 扩展思考在非Web场景下的应用我们上面讨论的是标准的Web网站扫码登录。但微信扫码登录的思想也可以扩展到其他场景。桌面应用WinForm/WPF原理类似。桌面应用内嵌一个WebBrowser控件导航到我们生成的二维码URL页面。用户扫码授权后微信会回调到我们的服务器。我们的服务器在完成用户信息处理后可以生成一个带有一次性令牌的URL重定向到一个简单的“登录成功”页面。桌面应用可以监听WebBrowser控件导航到这个特定成功页面的事件从URL中提取出令牌从而完成桌面端的登录。关键在于桌面应用需要有一个本地HTTP服务器或者长轮询机制来接收从我们后端服务器推送过来的登录结果。Unity游戏/移动端应用在移动端可以让用户点击“微信登录”按钮直接跳转到微信客户端进行授权使用微信SDK的移动应用授权方式与扫码流程不同。但如果你的游戏是PC版希望玩家用手机微信扫码登录PC客户端那么流程就和桌面应用类似了。PC客户端展示二维码由游戏后端生成手机扫码授权后游戏后端通知PC客户端登录成功。实现这些变种的核心依然是理解并妥善处理OAuth 2.0的授权码流程以及如何在不同类型的客户端浏览器、原生应用、游戏引擎与我们的后端服务器之间安全地传递登录状态。万变不离其宗掌握了Web网站的实现其他场景只需在“最后一公里”的交付方式上做些适配即可。 
长河君 · 2026/8/22 3:14:37 · 阅读 1.2k C#实现微信扫码登录：OAuth 2.0原理与ASP.NET Core实战指南
1. 项目概述为什么需要自己实现微信扫码登录在开发一个需要用户登录的Web应用或桌面应用时直接让用户注册账号、设置密码再通过邮箱或手机验证这套流程对用户来说已经越来越繁琐了。用户可能只是想来试用一下或者临时访问某个功能冗长的注册流程会直接劝退他们。这时第三方登录尤其是微信扫码登录就成了一个极佳的解决方案。它利用用户手机上已经安装且高度信任的微信应用通过扫描二维码的方式一键完成身份授权极大地简化了登录流程提升了用户体验和转化率。你可能在很多网站和应用上都见过这个功能页面上展示一个动态刷新的二维码用户用微信“扫一扫”手机上点击确认网页就自动登录成功了。这个看似简单的交互背后其实是一套标准的OAuth 2.0授权流程。作为开发者我们不需要去破解微信的协议而是遵循微信开放平台提供的标准接口来实现。今天我就以一个C#后端开发者的视角带你从零开始完整地走一遍这个流程把其中的技术细节、踩过的坑和优化心得都分享给你。无论你是想为你的ASP.NET Core Web应用、WinForm桌面程序还是Unity游戏添加这个功能这篇指南都能给你提供清晰的路径。2. 核心原理与流程拆解OAuth 2.0在微信扫码登录中的应用在动手写代码之前我们必须先理解微信扫码登录背后的工作原理。它本质上是OAuth 2.0授权码模式的一个具体应用场景。OAuth 2.0是一种开放标准允许用户授权第三方应用访问他们存储在另一服务提供商这里是微信上的信息而无需将用户名和密码提供给第三方应用。整个扫码登录流程涉及三个角色我们的应用第三方网站、微信开放平台服务提供商和用户。流程可以拆解为以下几个核心步骤2.1 流程时序与状态解析前端生成二维码我们的网站前端需要向我们的后端服务器请求一个“临时门票”。后端服务器会拿着这个请求去微信开放平台换取一个唯一的、有时效性的二维码URL。这个URL对应着一个本次登录的“场景值”scene。前端拿到这个URL后将其渲染成二维码图片展示给用户。这里的关键是这个二维码本身并不包含任何用户信息它只是一个指向微信服务器的“入口”并携带了能让我们后端识别这次登录事件的标识。用户扫码与授权用户使用手机微信扫描二维码。微信客户端会识别出这是一个登录授权请求并引导用户到一个确认页面上面会显示我们的应用名称和请求的权限如获取昵称、头像。用户点击“同意”后微信服务器就知道“哦用户XXX同意授权给应用YYY了”。微信回调与票据交换用户授权后微信服务器不会直接通知我们的前端因为前端是不可信的。它会根据我们最初生成二维码时提供的“回调地址”redirect_uri将授权结果一个一次性的code发送给我们的后端服务器。这个code是本次授权的凭证但它还不是最终的访问令牌。后端兑换用户信息我们的后端服务器在收到微信发来的code后需要立即用它再加上我们应用的AppSecret一个绝不能泄露的密码去微信服务器兑换两样东西access_token访问令牌和openid用户在当前应用下的唯一标识。拿到access_token和openid后我们才能进一步调用微信的接口获取用户的昵称、头像等基本信息。建立本地会话获取到用户信息后我们的后端业务逻辑才开始介入。我们通常会做这几件事检查这个openid是否已经在我们的用户系统中存在。如果存在就直接取出对应的本地用户ID如果不存在则用微信返回的信息创建一条新的用户记录。然后生成我们应用自身的会话标识例如一个JWT Token或Session ID返回给前端。前端拿到这个标识才算真正登录成功可以访问需要登录的页面了。注意整个安全链条的核心在于AppSecret和code。AppSecret必须永远保存在后端任何情况下都不能出现在前端代码、客户端配置或日志中。code是一次性的且必须在短时间内通常建议在5分钟内使用用后即废。正是这两个机制保证了即使二维码和code在传输中被截获攻击者也无法冒充用户。2.2 微信开放平台准备工作创建网站应用理论清楚了我们得先有“门票”才能入场。所有与微信服务器交互的权限都来自于你在微信开放平台创建的一个“网站应用”。注册与认证访问微信开放平台完成开发者注册和企业资质认证个人开发者也可以但部分高级接口和支付功能会受限。认证是必须的否则无法获得AppSecret也无法使用网页授权等核心功能。创建网站应用在管理中心找到“网站应用”栏目点击创建。你需要填写应用名称、简介、官网地址等。最关键的是授权回调域。这个域必须是你后端服务接收微信code的域名且需要精确到一级或二级域名例如www.yoursite.com或api.yoursite.com不能带http://或端口号也不能是IP地址。微信会对重定向请求的域名做严格校验不匹配则会失败。获取关键凭据应用创建并通过审核后审核通常需要几个工作日你就能在应用详情页找到你的AppID和AppSecret。把它们妥善保存特别是AppSecret要像保护数据库密码一样保护它。我建议将其存入环境变量或专业的密钥管理服务绝对不要硬编码在代码里或提交到版本库。3. 后端核心实现从生成二维码到建立会话接下来我们用C#以ASP.NET Core为例来实现后端逻辑。我会使用HttpClient进行网络请求并使用Newtonsoft.Json或System.Text.Json处理JSON数据。3.1 项目结构与依赖准备首先创建一个ASP.NET Core Web API项目。在appsettings.json中配置微信的凭据{ WeChat: { AppId: 你的AppId, AppSecret: 你的AppSecret, RedirectUri: https://你的域名.com/api/wechat/callback // 后端回调地址 } }然后创建一个对应的配置类WeChatSettings和一个服务类IWeChatAuthService及其实现。我们将核心逻辑封装在服务中。3.2 第一步生成带场景值的二维码URL前端需要展示二维码因此我们需要提供一个API返回生成二维码所需的临时数据。通常我们会生成一个随机字符串作为本次登录的“状态码”state用于防止CSRF攻击同时也可以将其作为我们后台标识这次登录请求的scene_id。// 服务接口方法 public async TaskQrCodeResponse GetLoginQrCodeAsync() { // 1. 生成一个随机的state并关联一个临时存储如分布式缓存Redis var state Guid.NewGuid().ToString(N); var cacheKey $wechat:login:state:{state}; // 存储state并设置较短过期时间例如300秒 await _cache.SetStringAsync(cacheKey, created, TimeSpan.FromSeconds(300)); // 2. 构造请求微信的URL // 微信生成二维码的地址是固定的 var baseUrl https://open.weixin.qq.com/connect/qrconnect; // 参数需要按照微信文档顺序拼接这里使用字典方便管理 var parameters new Dictionarystring, string { [appid] _settings.AppId, [redirect_uri] Uri.EscapeDataString(_settings.RedirectUri), [response_type] code, [scope] snsapi_login, // 固定值用于网站应用扫码登录 [state] state }; // 构造查询字符串 var queryString string.Join(, parameters.Select(p ${p.Key}{p.Value})); var qrCodeUrl ${baseUrl}?{queryString}#wechat_redirect; // 3. 返回给前端 return new QrCodeResponse { QrCodeUrl qrCodeUrl, State state, ExpiresIn 300 // 告诉前端二维码的有效期 }; }前端拿到qrCodeUrl后可以使用任何二维码生成库如qrcode.js将其渲染成图片。同时前端需要启动一个轮询定期询问后端“state对应的登录成功了吗”。3.3 第二步处理微信回调并兑换AccessToken当用户扫码并授权后微信会跳转到我们设置的RedirectUri并带上code和state参数。我们需要一个Controller Action来处理这个回调。[HttpGet(callback)] public async TaskIActionResult Callback([FromQuery] string code, [FromQuery] string state) { // 1. 验证state防止CSRF var cacheKey $wechat:login:state:{state}; var cachedState await _cache.GetStringAsync(cacheKey); if (string.IsNullOrEmpty(cachedState)) { return BadRequest(无效的state或二维码已过期); } // 验证通过后立即删除这个state防止被重复使用 await _cache.RemoveAsync(cacheKey); // 2. 用code和AppSecret向微信兑换access_token var tokenUrl https://api.weixin.qq.com/sns/oauth2/access_token; var tokenParams new Dictionarystring, string { [appid] _settings.AppId, [secret] _settings.AppSecret, [code] code, [grant_type] authorization_code }; using var httpClient _httpClientFactory.CreateClient(); var response await httpClient.GetStringAsync(${tokenUrl}?{ToQueryString(tokenParams)}); var tokenResult JsonConvert.DeserializeObjectAccessTokenResponse(response); // 3. 检查微信返回的错误 if (!string.IsNullOrEmpty(tokenResult.ErrorCode)) { _logger.LogError($微信获取access_token失败: {tokenResult.ErrorMessage}); return BadRequest($授权失败: {tokenResult.ErrorMessage}); } // 4. 用access_token和openid获取用户基本信息 var userInfoUrl https://api.weixin.qq.com/sns/userinfo; var userInfoParams new Dictionarystring, string { [access_token] tokenResult.AccessToken, [openid] tokenResult.OpenId, [lang] zh_CN }; var userInfoResponse await httpClient.GetStringAsync(${userInfoUrl}?{ToQueryString(userInfoParams)}); var userInfo JsonConvert.DeserializeObjectWeChatUserInfoResponse(userInfoResponse); if (!string.IsNullOrEmpty(userInfo.ErrorCode)) { // 有时access_token可能失效这里可以加入重试逻辑 _logger.LogError($获取用户信息失败: {userInfo.ErrorMessage}); return BadRequest($获取用户信息失败); } // 5. 业务处理查找或创建本地用户 var localUser await _userService.FindOrCreateUserAsync(userInfo.OpenId, userInfo.Nickname, userInfo.HeadImgUrl); // 6. 生成应用自身的登录凭证例如JWT var appToken _jwtService.GenerateToken(localUser.Id, localUser.Username); // 7. 这里不能直接返回JSON给这个回调请求因为这是微信服务器发起的重定向。 // 我们需要将登录成功的结果appToken, state通知给前端轮询接口。 // 常见做法将结果存入缓存key为最初的state var loginResultKey $wechat:login:result:{state}; var loginResult new LoginResult { Success true, Token appToken, UserId localUser.Id }; await _cache.SetStringAsync(loginResultKey, JsonConvert.SerializeObject(loginResult), TimeSpan.FromSeconds(60)); // 8. 回调页面重定向到前端一个“登录成功”的静态页面该页面会通知主窗口或轮询接口。 // 或者如果前端是桌面应用这里可以返回一个包含token的简单HTML由内嵌浏览器捕获。 return Redirect(${_frontendHost}/login-success?state{state}); }实操心得AccessTokenResponse和WeChatUserInfoResponse这两个模型类需要严格对应微信API返回的JSON字段。微信的字段命名风格是蛇形snake_case如access_token、expires_in在C#中我们可以用[JsonProperty(access_token)]特性来映射。另外所有微信接口的调用都要做好异常处理和日志记录因为网络波动或微信接口临时故障是常有的事。3.4 第三步前端轮询与登录状态确认前端在展示二维码后就需要开始轮询一个后端接口检查state对应的登录是否已完成。[HttpGet(poll/{state})] public async TaskIActionResult PollLoginResult(string state) { var resultKey $wechat:login:result:{state}; var resultJson await _cache.GetStringAsync(resultKey); if (string.IsNullOrEmpty(resultJson)) { // 结果还未产生或已过期 return Ok(new PollingResponse { Status pending }); } // 获取到结果后可以将其从缓存中移除或者让前端多轮询几次确保拿到 var result JsonConvert.DeserializeObjectLoginResult(resultJson); await _cache.RemoveAsync(resultKey); // 移除已消费的结果 return Ok(new PollingResponse { Status success, Data result }); }前端JavaScript轮询逻辑大致如下function pollLoginResult(state) { const pollInterval setInterval(async () { const resp await fetch(/api/wechat/poll/${state}); const data await resp.json(); if (data.status success) { clearInterval(pollInterval); // 将获取到的token存入localStorage或Cookie localStorage.setItem(auth_token, data.data.token); // 跳转到登录后的首页 window.location.href /dashboard; } else if (data.status pending) { // 继续等待 console.log(等待扫码授权...); } }, 1500); // 1.5秒轮询一次 }4. 安全加固与生产环境注意事项实现基本功能只是第一步要上线生产环境必须考虑以下安全与稳定性问题。4.1 State参数的安全性与防重放攻击我们使用state参数主要目的是防止CSRF攻击。但它的实现必须满足以下几点足够随机且不可预测使用密码学安全的随机数生成器如Guid.NewGuid()或RandomNumberGenerator。与用户会话关联在生成state时可以将其与当前未认证的会话ID如果有绑定验证时一并检查。一次性使用一旦用于兑换code立即在服务端使其失效无论成功与否。设置合理有效期存储在缓存中并设置一个略长于二维码有效期的过期时间如300秒过期自动清理防止缓存无限制增长。4.2 AccessToken的存储与刷新我们通过code兑换得到的是微信的access_token它有自己的有效期通常为7200秒。在我们的扫码登录场景中这个token主要用于一次性获取用户信息之后便不再需要。因此我们不应该存储这个微信的access_token。获取用户信息后我们的任务就完成了。这与我们开发微信小程序或公众号时需要长期保存并刷新access_token的场景完全不同。4.3 网络超时与重试机制调用微信API是网络IO操作必须设置合理的超时时间例如10秒并实现重试逻辑。对于获取access_token和userinfo这类关键步骤建议实现简单的指数退避重试。public async TaskT CallWeChatApiWithRetryT(FuncTaskT apiCall, int maxRetries 2) { int retryCount 0; while (true) { try { return await apiCall(); } catch (HttpRequestException ex) when (retryCount maxRetries) { retryCount; var delay TimeSpan.FromSeconds(Math.Pow(2, retryCount)); // 指数退避 _logger.LogWarning(ex, $调用微信API失败第{retryCount}次重试等待{delay.TotalSeconds}秒); await Task.Delay(delay); } } }4.4 日志与监控记录详细的日志特别是在兑换code和获取用户信息失败时需要将微信返回的错误码和错误信息记录下来方便排查。监控接口的调用成功率、耗时和频率设置告警。5. 常见问题排查与调试技巧在实际开发中你几乎一定会遇到下面这些问题。这里我整理了排查清单。5.1 二维码不显示或“该链接无法访问”原因1回调域名未设置或设置错误这是最常见的原因。登录微信开放平台检查“网站应用”的“授权回调域”。必须与代码中RedirectUri的域名部分完全一致不包含http://和端口。例如回调域设为www.example.com那么RedirectUri可以是https://www.example.com/callback但不能是https://api.example.com/callback或http://www.example.com:8080/callback。原因2生成二维码的URL参数错误或未编码确保redirect_uri参数已经进行了URL编码。使用Uri.EscapeDataString方法。检查scope参数是否为snsapi_login。原因3AppId或AppSecret错误仔细核对配置。5.2 扫码后提示“redirect_uri参数错误”原因几乎可以肯定是回调地址的问题。除了上述域名匹配问题还需注意回调地址的路径如/api/wechat/callback必须是真实存在且可被外网访问的。在开发环境使用localhost或127.0.0.1是不行的微信服务器无法回调到你的本地机器。开发时需要使用内网穿透工具如ngrok、frp将本地服务暴露到一个公网域名并将该域名配置到微信回调域中。5.3 兑换access_token时返回40029或40163错误码40029无效的code说明code已经被使用过或者已经过期超过5分钟。请检查后端逻辑是否对同一个code重复发起了兑换请求。错误码40163code已被使用同上。确保你的回调接口是幂等的或者通过state的验证来防止重复处理。5.4 获取用户信息返回48001或40001错误码48001api功能未授权检查scope参数是否正确设置为snsapi_login。也可能是你的微信开放平台应用没有通过审核部分接口权限未开通。错误码40001无效的access_token可能access_token已经过期或者你在获取用户信息时传入的access_token与openid不匹配。确保你是用兑换access_token时返回的那个token和openid配对去调用用户信息接口。5.5 前端轮询不到结果一直pending检查state的生命周期确保生成二维码时存储了state在回调处理成功后将结果存储时使用的state键名与轮询接口读取的键名完全一致。注意缓存服务如Redis的连接和读写是否正常。检查回调逻辑在回调接口中是否成功将登录结果写入了缓存可以在写入后立即读取一次验证。同时检查回调接口完成后是否正确地重定向到了前端页面前端页面是否能触发轮询状态的更新。网络问题检查你的后端API特别是回调接口和轮询接口是否可以被公网正常访问防火墙和云安全组策略是否放行了相应端口。6. 扩展思考在非Web场景下的应用我们上面讨论的是标准的Web网站扫码登录。但微信扫码登录的思想也可以扩展到其他场景。桌面应用WinForm/WPF原理类似。桌面应用内嵌一个WebBrowser控件导航到我们生成的二维码URL页面。用户扫码授权后微信会回调到我们的服务器。我们的服务器在完成用户信息处理后可以生成一个带有一次性令牌的URL重定向到一个简单的“登录成功”页面。桌面应用可以监听WebBrowser控件导航到这个特定成功页面的事件从URL中提取出令牌从而完成桌面端的登录。关键在于桌面应用需要有一个本地HTTP服务器或者长轮询机制来接收从我们后端服务器推送过来的登录结果。Unity游戏/移动端应用在移动端可以让用户点击“微信登录”按钮直接跳转到微信客户端进行授权使用微信SDK的移动应用授权方式与扫码流程不同。但如果你的游戏是PC版希望玩家用手机微信扫码登录PC客户端那么流程就和桌面应用类似了。PC客户端展示二维码由游戏后端生成手机扫码授权后游戏后端通知PC客户端登录成功。实现这些变种的核心依然是理解并妥善处理OAuth 2.0的授权码流程以及如何在不同类型的客户端浏览器、原生应用、游戏引擎与我们的后端服务器之间安全地传递登录状态。万变不离其宗掌握了Web网站的实现其他场景只需在“最后一公里”的交付方式上做些适配即可。