做 Flutter 开发这两年要说哪个功能最容易被低估开发量我第一个想到的就是微信登录。表面上看它只是一句调起微信、用户点一下确认、回调里拿到 code真正动手做的时候开放平台审核、包名签名绑定、iOS 的 URL Scheme、Android 的回调 Activity、再加上 Flutter 与原生之间的通信时序每一层都能让你半夜对着日志发呆。这篇就完整记录一次 Flutter 在 Android/iOS 双端集成微信登录的全过程包含我踩过的坑和排查思路给正要接这个功能的人一份可以直接照做的实操记录。1. 微信登录的完整链路前端只是其中一环1.1 微信 OAuth 授权码模式的移动端版本微信登录本质上走的是 OAuth 2.0 的 Authorization Code授权码模式但移动端和网页端在执行路径上有很大区别。先把这条链路画清楚后面排查问题才有地图。完整流程是这样的用户点击登录按钮Flutter 通过插件调起微信 SDK微信 App 被唤起展示授权确认页面用户在微信里点允许微信通过回调把 auth_code 交还给你的 App你的 App 把 code 发给自己的后端后端拿 appid、secret、code 去微信服务器换取 access_token、openid、unionid后端按 user 维度建立账号或登录态返回自定义 token前端保存 token完成登录这里最核心的认知点是access_token 不应该出现在前端。很多团队第一次做的时候习惯把 token 全放前端然后发现微信的 access_token 有刷新机制、有有效期限制前端根本处理不干净。微信移动应用登录里前端只跟 auth_code 打交道拿到 code 就完成任务剩下的脏活累活都应该放在后端。授权码本身也有讲究code 有效期只有五分钟而且只能使用一次。这意味着用户如果点了一次登录拿到 code请求后端失败了第二次不能拿同一个 code 重试只能重新拉起微信再授权一次。这个细节在联调的时候特别容易让人困惑你会觉得我刚明明拿到 code 了为什么后端说无效大概率就是之前已经消费过一次了。1.2 前端、SDK、后端的分工边界从分层视角来看微信登录的职责分配是这样的原生 SDK 层负责和微信 App 通信。Android 上通过 Intent 跳到微信的授权 ActivityiOS 上通过 URL Scheme 唤起微信然后把用户的选择结果code 或 errCode通过插件通道传回 Flutter。Flutter 插件层把原生回调封装成 Dart 的 Future 或 Stream屏蔽平台差异。Dart 业务层负责发起登录、处理回调、调用后端接口、保存登录态。这里面容易被忽略的是第二层和第三层之间的回调时序问题。微信登录插件正是依赖原生到 Flutter 的通信通道来完成回调的——具体来说是 MethodChannel 负责 Dart 调用原生EventChannel 负责把原生的回调结果推回 Dart。如果你把登录结果的监听放在一个会被销毁的 Widget 里页面一重建回调就可能看起来丢了实际是监听者已经不存在了。所以我的建议是登录相关的逻辑不要放在页面级 Widget 的 State 里而是放到一个全局的 AuthController 或者 ChangeNotifier 里面这样能保证回调产生时监听者一定还存在。1.3 移动端登录和扫码登录的关键差异如果团队同时要做 PC 端微信扫码登录千万别拿 App 登录的流程硬套。扫码登录是开放平台的网站应用交互方式是网页先展示二维码再轮询扫码结果移动端登录是 SDK 直呼微信不存在轮询。两者在开放平台创建的应用类型就不同一个是移动应用一个是网站应用需要分别申请。这个区分看起来基础但我真见过有人申请了网站应用想在 App 里调微信登录调了半天也没调起来——因为在微信那边你的 App 身份根本没被登记。还有一个容易混淆的点是个人微信和企业微信个人微信登录走的是微信开放平台这套流程企业微信登录完全是另一套体系参数、回调、SDK 都不一样别指望换一个 AppID 就能通用。2. 开放平台注册与参数绑定包名、签名、应用名一个都不能错2.1 开通开发者账号与创建移动应用要调用微信登录第一步是去微信开放平台注册开发者账号。注意这里有几个微信平台的区分微信公众平台mp.weixin.qq.com管公众号、小程序微信开放平台open.weixin.qq.com管 App 接入、网站应用、第三方平台微信商户平台pay.weixin.qq.com管支付微信登录属于开放平台不在公众平台。很多第一次做的人会跑到公众平台里找 App 登录入口找不到就开始怀疑人生。注册时需要准备邮箱以及主体信息个人或企业。个人主体的开发者账号也能接入 App 登录但某些需要高级权限的能力会受限所以企业项目建议直接用企业主体注册。在开放平台里创建移动应用后需要填写应用名称、简介、图标、下载链接。这里有一个不少团队踩过的坑同一个 App 的 Android 和 iOS 版要在开放平台建两个移动应用分别拿到各自的 AppID 和 AppSecret。代码里 Android 用 Android 的 AppIDiOS 用 iOS 的 AppID。如果图省事只建了一个另一个平台调微信登录时就会出问题。2.2 包名、签名的绑定逻辑微信开放平台创建 Android 应用时会要求填两个关键信息包名PackageName和签名MD5。包名对应 Android 工程里的 applicationId签名对应 APK 签名证书的 MD5 值去掉冒号、大写微信为什么要绑这两个信息因为 Android 的 App 身份就是由包名和签名共同确定的。拿包名相同但签名不同的 APK 安装到同一台手机上系统都会当成另一个应用。微信在收到调用请求时会校验调用方的包名和签名是否和开放平台登记的一致不一致就直接拒绝。签名这块最经典的坑是开发时用 debug 签名调试成功了发版时切到 release 签名微信登录瞬间失效。debug keystore 和 release keystore 是两套完全不同的证书MD5 值不一样。正确的做法是正式项目从一开始就用 release 签名跑联调可以在 build.gradle 里把 debug 的 signingConfig 指向 release或者按环境申请两个 AppIDdebug 环境一套release 环境一套代码里根据 BuildConfig.DEBUG 切换实在只有一套 AppID那就以线上正式包签名为准开发期安装的调试包必须使用相同签名的 keystore2.3 获取签名 MD5 的正确姿势获取签名 MD5 有几种方式我按可靠程度排序。方式一微信官方签名获取工具App。直接在应用市场搜输入包名就能显示该包名当前安装版本的签名 MD5。这个工具显示的是手机上已安装应用的签名最直观。方式二keytool 命令行。如果是 release keystorekeytool -exportcert -alias your_alias -keystore release.keystore | openssl dgst -md5输出会带(stdin)前缀把这部分去掉再去除冒号、转大写就是微信要的 32 位 MD5 字符串。方式三用apksigner verify --print-certs从 APK 里提取签名证书信息再手动算 MD5。需要注意微信这里用的算法是MD5不是 SHA1 也不是 SHA256。Android 应用市场很喜欢用 SHA 系列微信偏偏要求 MD5两者别搞混。我去开放平台填签名的时候就不止一次见过同事把 SHA1 值贴上去然后调一晚上都调不通。2.4 审核和测试期间的注意点新创建的移动应用默认是开发中状态需要提交审核审核通过后 AppID 才能正式使用。审核注意事项应用需要有下载链接或应用市场页面App Store、应用宝、官网链接都行不能是空链接必须提供包含微信登录入口的应用截图审核周期一般 3 到 7 个工作日不是实时的项目排期要把这段时间算进去如果没有线上下载链接可以先在开放平台传一个测试 APK过审后再改成正式链接。这里建议提前准备好材料因为审核一旦被打回修改后重新提交又是几个工作日很影响排期。3. 依赖与初始化插件选型、双端配置文件3.1 插件选型理由Flutter 里做微信登录社区最常用的是flutter_wechat_auth。选它而不是其他插件的理由它对 Android/iOS 的原生微信 SDK 做了统一封装支持调用微信登录、分享等能力内部通过 MethodChannel 调用原生通过 EventChannel 持续接收回调结果Flutter 侧拿到的 API 是异步 Future符合常规使用习惯相比早期常用的fluttter_wechat和wechat_kitflutter_wechat_auth的维护状态更活跃对较新的 Flutter SDK 适配更快一些在pubspec.yaml里加依赖dependencies: flutter_wechat_auth: ^1.3.1然后执行flutter pub get。要注意插件的原生 SDK 版本与 Flutter SDK 版本存在隐性绑定。如果你用的是比较新的 Flutter3.x 系列构建时出现类似 the current configured flutter sdk is not known to be fully supported 的提示不要急着升级 Flutter先确认插件版本是否兼容或者查一下插件是否有对应新 SDK 的更新版本。3.2 Android 侧配置顺序微信 SDK 在 Android 上有几个硬性条件按顺序排查。第一步核对 applicationId。打开android/app/build.gradle确认applicationId与开放平台登记的包名完全一致一个字符都不能差。很多项目会在不同 buildType 里加applicationIdSuffix如果加了.debug后缀包名就变了微信授权会失败。第二步设置 minSdkVersion。微信 SDK 对 minSdk 有要求建议不小于 21。具体配置如下defaultConfig { applicationId com.example.myapp minSdkVersion 21 targetSdkVersion 34 }第三步改 AndroidManifest.xml。需要在application节点里添加微信回调 Activity 和 AppID 配置application meta-data android:nameWECHAT_APPID android:valuewxa1234567890abcdef / activity android:namecom.tencent.wechat.sdk.WechatAuthActivity android:exportedtrue android:launchModesingleTask / /application第四步处理 Android 11 的包可见性。如果 targetSdkVersion 是 30 及以上还需要在 Manifest 里声明微信的包名否则会出现调不起微信的问题queries package android:namecom.tencent.mm / /queries第五步混淆规则。release 包开了 Proguard/R8 的话需要在android/app/proguard-rules.pro里加 keep 规则-keep class com.tencent.wxop.** { *; } -keep class com.tencent.wechat.sdk.** { *; }不加的话release 包一混淆微信 SDK 的类可能被裁剪或改名表现为 debug 正常、线上授权没反应。另外提一句很多项目在升级 AGP 后会在构建日志里看到 You are applying Flutters main Gradle plugin imperatively using the apply script 这行警告。这个警告本身不影响微信登录功能但如果你同时改过 Gradle 配置要确认 Flutter 插件正常应用了否则原生侧代码不会被编译进去这属于构建层面的问题优先级在能跑起来之后再去管。3.3 iOS 侧配置iOS 的配置比 Android 啰嗦一些但逻辑其实就几条。第一Podfile 的平台版本。打开ios/Podfile确认platform :ios, 12.0微信 SDK 对 deployment target 有要求太低会编译不过或者出现 API 冲突。第二Info.plist 里的 LSApplicationQueriesSchemes。在ios/Runner/Info.plist里加keyLSApplicationQueriesSchemes/key array stringweixin/string /array这个字段用于检测微信是否安装。少了它canOpenURL返回 false登录按钮点击后 Flutter 侧会直接走微信未安装分支。第三URL Types。在 Xcode 的 TARGETS → Runner → Info → URL Types 里添加一个 URL Scheme格式是wx 你的 AppID。例如 AppID 是wxa1234567890abcdefURL Type 的 Scheme 就是wxwxa1234567890abcdef全小写。这一步等效于往 Info.plist 里加 CFBundleURLTypeskeyCFBundleURLTypes/key array dict keyCFBundleURLName/key stringwechat/string keyCFBundleURLSchemes/key array stringwxwxa1234567890abcdef/string /array /dict /array第四回调处理。iOS 13 之后如果项目用了 SceneDelegate微信回调的 openURL 可能不会自动回到原来的路径插件一般会在 AppDelegate 和 SceneDelegate 里都做 hook。如果你自己改过这两个文件注意别把插件的回调处理覆盖掉。第五universalLink 参数。插件初始化时要求传 universalLink。如果你只做微信登录这个参数可以暂时填一个占位值但如果后续要做微信分享、拉起小程序Universal Links 就得认真配置。在苹果开发者后台关联域名把 apple-app-site-association 文件放到服务器对应路径然后把完整链接传给插件。这个配置比较繁琐但值得提前规划因为微信开放平台的 AppID 一旦确定后面改 Universal Links 域名还要重新走微信侧的校验流程。3.4 初始化代码与通信回调机制配置文件折腾完回到 Dart 侧。在main.dart里尽早初始化插件import package:flutter_wechat_auth/flutter_wechat_auth.dart; Futurevoid main() async { WidgetsFlutterBinding.ensureInitialized(); await WechatAuth.instance.registerApp( appId: wxa1234567890abcdef, universalLink: https://your.domain.com/app/, ); runApp(const MyApp()); }registerApp要在应用启动早期完成不要放到某个页面里才调用。微信登录的回调是基于全局通道的等到页面级再注册可能错过回调或者出现状态错乱。微信 SDK 回调原生后插件通过 EventChannel 把结果推回 Dart。这个链路本身是稳定的但前提是 Dart 侧的回调监听器要在合适的时机注册好。好消息是loginWithWechat()返回的是一个 Future相当于把发起登录和等待回调封装在了一起不需要额外手动注册 Stream 监听。4. 登录态设计从调起微信到拿到后端 session4.1 核心登录方法代码示例与关键行解释这是登录方法的骨架FutureLoginResult wxLogin() async { if (!await WechatAuth.instance.isWechatInstalled()) { return LoginResult.fail(未检测到微信请先安装微信); } final resp await WechatAuth.instance.loginWithWechat(); if (resp.errCode 0 resp.code ! null) { return await _exchangeCodeForSession(resp.code!); } else { return LoginResult.fail(_mapWechatError(resp.errCode)); } }几个容易被忽略的点isWechatInstalled()会走原生 canOpenURL 或 package manager 查询。如果返回 false优先怀疑 LSApplicationQueriesSchemes 或 queries 配置而不是微信真的没装。resp.code是授权码有效期 5 分钟只能使用一次。用户如果连续点两次登录微信每次都会重新产生 code之前的 code 立即作废。errCode 0只是微信侧授权成功并不等于登录成功。真正的成功标志是后端完成了 code 换 token并返回了你自己的登录态。后端接口调用示例FutureLoginResult _exchangeCodeForSession(String code) async { try { final data await dio.post( /api/auth/wechat-login, data: {code: code, platform: Platform.isIOS ? ios : android}, ); final token data[token] as String; await _saveToken(token); return LoginResult.success(user: data[user]); } catch (e) { return LoginResult.fail(登录失败$e); } }注意 platform 参数建议传。因为微信开放平台里 Android 和 iOS 是两个应用后端换 token 时用的 appid 不同加上这个字段后端处理起来会舒服很多。4.2 用户点击登录后发生了什么状态机设计很多初学者只把代码写完当成功但在真实 App 里登录按钮要处理的远不止一个返回值。我把整个交互拆成几个状态idle未登录按钮可点invoking正在调起微信Android 上是 Activity 跳转iOS 上是 URL 打开都是从当前 App 切出去waitingBack已经切到微信等待用户授权后回跳exchanging拿到 code正在请求后端success拿到了 session进入已登录界面failure失败或用户取消回到 idle给用户一个再次尝试的入口其中waitingBack最容易出问题因为这个阶段 App 可能已经退到后台甚至被系统回收。我的建议是所有跟等待相关的 UI 变化都要放在状态管理容器里而不是放在某个页面的局部 State。微信登录的回调不会因为 Navigator push 而丢失因为 Future 是在调用这个方法的地方挂起的但如果整个页面被 dispose而状态只存在于那个页面里回调确实可能看起来丢了。用 Riverpod 举例final authControllerProvider StateNotifierProviderAuthController, AuthState((ref) AuthController()); class AuthController extends StateNotifierAuthState { Futurevoid loginWithWechat() async { state AuthState.loading(); final result await wxLogin(); result.ok ? state AuthState.authenticated(result.user!) : state AuthState.error(result.message); } }页面里监听这个 state按钮 loading、错误提示、登录后跳转都由 state 驱动。这样即使中间发生了页面跳转或 Widget 重建登录流程的状态不会丢。4.3 token 存储与后续请求附带登录成功后Flutter 侧保存的是后端返回的自定义登录态而不是微信的 openid 或 access_token。原因很直接后端 token 有自己的时效和刷新机制前端只管带着它访问接口微信的 access_token 应当只存在于后端前端保存它既浪费又危险存储建议用flutter_secure_storage它在 iOS 上走 KeychainAndroid 上走 EncryptedSharedPreferences比明文存储安全一个档次const storage FlutterSecureStorage(); await storage.write(key: session_token, value: token);每次请求在拦截器里附带dio.interceptors.add( InterceptorsWrapper( onRequest: (options, handler) async { final token await storage.read(key: session_token); if (token ! null) { options.headers[Authorization] Bearer $token; } return handler.next(options); }, ), );冷启动时先读 token再去后端校验有效性。有效就直接进主界面不需要再弹微信无效再走登录流程。这里有个产品层面的原则不要自动静默调起微信登录用户没点按钮之前App 不应该自己唤起微信。这既是体验问题也是微信开放平台审核时会关注的行为。4.4 退出登录一个容易想多的地方微信登录机制里的登录是一次授权关系的确立。用户在微信里同意之后你的 App 在微信侧就有了长期授权关系除非用户在微信的隐私-授权管理里主动解除否则后续发起新的登录授权时微信可能直接返回一个 code不再每次弹确认页具体取决于微信版本和用户设置。所以 App 内的退出登录实际只需要做两件事清掉本地 token、清掉内存中的用户状态。不要尝试调用微信接口来撤销登录微信开放平台并没有提供面向 App 内退出登录的通用接口。如果你确实想让用户完全断开微信授权只能引导用户去微信的授权管理里操作。5. 双端实测中的坑与排查思路含日志定位方法5.1 Android 高频错误 1调起微信提示应用未注册或直接无反应这是我见过次数最多的错误。现象点击微信登录微信 App 被唤起但弹出应用未注册提示或者干脆白屏一下然后没有反应。排查顺序核对开放平台包名。打开开放平台 App 详情确认绑定的包名和当前 build.gradle 里的 applicationId 严格一致注意大小写。核对签名 MD5。用签名工具或 keytool 算出的 MD5 与开放平台登记的一致。检查 Manifest 里的 WECHAT_APPID 是否一致。同一个包名下只能有一个微信应用值必须是开放平台分配的那个 wx 开头的 AppID。如果以上都对考虑签名缓存问题。微信 App 会缓存它见过的应用签名如果你之前在开放平台填的签名和现在包里实际签名不同微信端会按未注册处理。更换签名后的调试包建议先清除微信 App 的缓存数据再重试。日志定位法在终端跑adb logcat -s WechatSDK WechatAuthActivity复现点击操作正常流程里能看到微信 SDK 打印出调用方包名和签名信息。如果日志显示签名匹配失败基本就是签名问题不用再找别的原因。5.2 iOS 高频错误 2点击按钮回到微信授权页一闪而过或回调不了iOS 上最常见的翻车点不在 Dart 代码而在 Xcode 配置。现象一点击登录后直接返回微信未安装。优先检查 LSApplicationQueriesSchemes 里有没有weixin其次检查真机是否真的装了微信。现象二微信打开了但授权页没出来或者授权完成回不来。检查 URL TypesScheme 必须是wx 完整 AppID全部小写。大小写错、少一位、多一位回调都不通。现象三能授权但 Dart 侧收不到结果。检查 AppDelegate / SceneDelegate 里的 openURL 处理是否被自己覆盖了。插件往往通过运行时 hook 或依赖 Flutter 的 deep linking 机制来分发回调如果你手写了一个application(_:open:options:)然后没有走 Flutter 的默认处理回调就会断在原生层。解决办法是保留插件默认的 AppDelegate 配置不要做多余拦截。日志定位法在 Xcode 的 Console 里按进程过滤或者直接在 AppDelegate 里打日志确认openURL有没有触发、url 内容是什么。如果触发了但格式不对立刻就能定位是 URL Type 的问题。5.3 跨端通用坑模拟器问题。Android 模拟器上可以装微信但登录授权受限比较严重iOS 模拟器装微信也不方便。微信登录这种涉及真实 App 跳转的功能强烈建议直接真机调试这是效率最高的做法。Proguard 混淆。Android release 包出现登录无反应优先怀疑混淆规则按前面第 3 节加 keep 规则再打包。多环境 AppID 串用。项目同时有 dev、prod 环境不要图省事全用同一个 AppID。否则你在 dev 环境测试时微信返回的用户身份会被后端和 prod 环境混在一起账号体系会乱。更稳妥的是每个环境在微信开放平台单独建应用各用各的包名和签名。后端验签失败。前端链路全通、用户在微信里也点了允许、code 也拿到了但后端换 token 失败。检查后端用的 appid 和 secret 是否和当前移动应用一致微信接口是否用了 POSTcode 是否已经被前一次请求消费。一个 code 只能用一次第二次请求会报无效或已使用。微信版本过旧。如果用户手机上的微信版本太老调起登录时也可能出现异常行为。可以在登录按钮页面加一个版本检测提示但微信本身会做大部分兼容处理这个坑属于少数情况遇到了优先换新版本微信测试。5.4 一个典型的日志定位法实操我自己的排查习惯是固定一个流程遇到问题按顺序过确认 AppID 正确wx开头长度和字符别错。确认基础能力Android 看 ManifestiOS 看 Info.plist 和 URL Types。确认开放平台配置包名、签名、平台类型。真机复现采集原生日志。Flutter 侧打点在调用loginWithWechat()前后各打一条日志记录返回值 errCode。这个流程走完90% 的问题都能定位。剩下那 10% 通常和微信 App 版本、系统限制有关换台手机、换个微信号试一下往往就有结果。这个定位流程是我从几次深夜排查里总结出来的。前两次遇到微信登录问题都是在为什么代码没问题但功能不起来上卡了很久最后才发现少配了一个 queries 或者填错了签名。微信登录这种东西真不是写完 Dart 代码就算完把开放平台后台和双端配置文件当成正式环境来管理才能减少那类昨天还好好的今天就不行了的惊悚事件。最后分享一个小习惯每次改过签名、包名、AppID 之后我都会把真机上微信的缓存清掉再测试。微信对应用身份的缓存很顽固不清理的话你新配的签名可能还是旧值容易误导排查方向。
Flutter 双端集成微信登录全指南：从 OAuth 到踩坑排查
做 Flutter 开发这两年要说哪个功能最容易被低估开发量我第一个想到的就是微信登录。表面上看它只是一句调起微信、用户点一下确认、回调里拿到 code真正动手做的时候开放平台审核、包名签名绑定、iOS 的 URL Scheme、Android 的回调 Activity、再加上 Flutter 与原生之间的通信时序每一层都能让你半夜对着日志发呆。这篇就完整记录一次 Flutter 在 Android/iOS 双端集成微信登录的全过程包含我踩过的坑和排查思路给正要接这个功能的人一份可以直接照做的实操记录。1. 微信登录的完整链路前端只是其中一环1.1 微信 OAuth 授权码模式的移动端版本微信登录本质上走的是 OAuth 2.0 的 Authorization Code授权码模式但移动端和网页端在执行路径上有很大区别。先把这条链路画清楚后面排查问题才有地图。完整流程是这样的用户点击登录按钮Flutter 通过插件调起微信 SDK微信 App 被唤起展示授权确认页面用户在微信里点允许微信通过回调把 auth_code 交还给你的 App你的 App 把 code 发给自己的后端后端拿 appid、secret、code 去微信服务器换取 access_token、openid、unionid后端按 user 维度建立账号或登录态返回自定义 token前端保存 token完成登录这里最核心的认知点是access_token 不应该出现在前端。很多团队第一次做的时候习惯把 token 全放前端然后发现微信的 access_token 有刷新机制、有有效期限制前端根本处理不干净。微信移动应用登录里前端只跟 auth_code 打交道拿到 code 就完成任务剩下的脏活累活都应该放在后端。授权码本身也有讲究code 有效期只有五分钟而且只能使用一次。这意味着用户如果点了一次登录拿到 code请求后端失败了第二次不能拿同一个 code 重试只能重新拉起微信再授权一次。这个细节在联调的时候特别容易让人困惑你会觉得我刚明明拿到 code 了为什么后端说无效大概率就是之前已经消费过一次了。1.2 前端、SDK、后端的分工边界从分层视角来看微信登录的职责分配是这样的原生 SDK 层负责和微信 App 通信。Android 上通过 Intent 跳到微信的授权 ActivityiOS 上通过 URL Scheme 唤起微信然后把用户的选择结果code 或 errCode通过插件通道传回 Flutter。Flutter 插件层把原生回调封装成 Dart 的 Future 或 Stream屏蔽平台差异。Dart 业务层负责发起登录、处理回调、调用后端接口、保存登录态。这里面容易被忽略的是第二层和第三层之间的回调时序问题。微信登录插件正是依赖原生到 Flutter 的通信通道来完成回调的——具体来说是 MethodChannel 负责 Dart 调用原生EventChannel 负责把原生的回调结果推回 Dart。如果你把登录结果的监听放在一个会被销毁的 Widget 里页面一重建回调就可能看起来丢了实际是监听者已经不存在了。所以我的建议是登录相关的逻辑不要放在页面级 Widget 的 State 里而是放到一个全局的 AuthController 或者 ChangeNotifier 里面这样能保证回调产生时监听者一定还存在。1.3 移动端登录和扫码登录的关键差异如果团队同时要做 PC 端微信扫码登录千万别拿 App 登录的流程硬套。扫码登录是开放平台的网站应用交互方式是网页先展示二维码再轮询扫码结果移动端登录是 SDK 直呼微信不存在轮询。两者在开放平台创建的应用类型就不同一个是移动应用一个是网站应用需要分别申请。这个区分看起来基础但我真见过有人申请了网站应用想在 App 里调微信登录调了半天也没调起来——因为在微信那边你的 App 身份根本没被登记。还有一个容易混淆的点是个人微信和企业微信个人微信登录走的是微信开放平台这套流程企业微信登录完全是另一套体系参数、回调、SDK 都不一样别指望换一个 AppID 就能通用。2. 开放平台注册与参数绑定包名、签名、应用名一个都不能错2.1 开通开发者账号与创建移动应用要调用微信登录第一步是去微信开放平台注册开发者账号。注意这里有几个微信平台的区分微信公众平台mp.weixin.qq.com管公众号、小程序微信开放平台open.weixin.qq.com管 App 接入、网站应用、第三方平台微信商户平台pay.weixin.qq.com管支付微信登录属于开放平台不在公众平台。很多第一次做的人会跑到公众平台里找 App 登录入口找不到就开始怀疑人生。注册时需要准备邮箱以及主体信息个人或企业。个人主体的开发者账号也能接入 App 登录但某些需要高级权限的能力会受限所以企业项目建议直接用企业主体注册。在开放平台里创建移动应用后需要填写应用名称、简介、图标、下载链接。这里有一个不少团队踩过的坑同一个 App 的 Android 和 iOS 版要在开放平台建两个移动应用分别拿到各自的 AppID 和 AppSecret。代码里 Android 用 Android 的 AppIDiOS 用 iOS 的 AppID。如果图省事只建了一个另一个平台调微信登录时就会出问题。2.2 包名、签名的绑定逻辑微信开放平台创建 Android 应用时会要求填两个关键信息包名PackageName和签名MD5。包名对应 Android 工程里的 applicationId签名对应 APK 签名证书的 MD5 值去掉冒号、大写微信为什么要绑这两个信息因为 Android 的 App 身份就是由包名和签名共同确定的。拿包名相同但签名不同的 APK 安装到同一台手机上系统都会当成另一个应用。微信在收到调用请求时会校验调用方的包名和签名是否和开放平台登记的一致不一致就直接拒绝。签名这块最经典的坑是开发时用 debug 签名调试成功了发版时切到 release 签名微信登录瞬间失效。debug keystore 和 release keystore 是两套完全不同的证书MD5 值不一样。正确的做法是正式项目从一开始就用 release 签名跑联调可以在 build.gradle 里把 debug 的 signingConfig 指向 release或者按环境申请两个 AppIDdebug 环境一套release 环境一套代码里根据 BuildConfig.DEBUG 切换实在只有一套 AppID那就以线上正式包签名为准开发期安装的调试包必须使用相同签名的 keystore2.3 获取签名 MD5 的正确姿势获取签名 MD5 有几种方式我按可靠程度排序。方式一微信官方签名获取工具App。直接在应用市场搜输入包名就能显示该包名当前安装版本的签名 MD5。这个工具显示的是手机上已安装应用的签名最直观。方式二keytool 命令行。如果是 release keystorekeytool -exportcert -alias your_alias -keystore release.keystore | openssl dgst -md5输出会带(stdin)前缀把这部分去掉再去除冒号、转大写就是微信要的 32 位 MD5 字符串。方式三用apksigner verify --print-certs从 APK 里提取签名证书信息再手动算 MD5。需要注意微信这里用的算法是MD5不是 SHA1 也不是 SHA256。Android 应用市场很喜欢用 SHA 系列微信偏偏要求 MD5两者别搞混。我去开放平台填签名的时候就不止一次见过同事把 SHA1 值贴上去然后调一晚上都调不通。2.4 审核和测试期间的注意点新创建的移动应用默认是开发中状态需要提交审核审核通过后 AppID 才能正式使用。审核注意事项应用需要有下载链接或应用市场页面App Store、应用宝、官网链接都行不能是空链接必须提供包含微信登录入口的应用截图审核周期一般 3 到 7 个工作日不是实时的项目排期要把这段时间算进去如果没有线上下载链接可以先在开放平台传一个测试 APK过审后再改成正式链接。这里建议提前准备好材料因为审核一旦被打回修改后重新提交又是几个工作日很影响排期。3. 依赖与初始化插件选型、双端配置文件3.1 插件选型理由Flutter 里做微信登录社区最常用的是flutter_wechat_auth。选它而不是其他插件的理由它对 Android/iOS 的原生微信 SDK 做了统一封装支持调用微信登录、分享等能力内部通过 MethodChannel 调用原生通过 EventChannel 持续接收回调结果Flutter 侧拿到的 API 是异步 Future符合常规使用习惯相比早期常用的fluttter_wechat和wechat_kitflutter_wechat_auth的维护状态更活跃对较新的 Flutter SDK 适配更快一些在pubspec.yaml里加依赖dependencies: flutter_wechat_auth: ^1.3.1然后执行flutter pub get。要注意插件的原生 SDK 版本与 Flutter SDK 版本存在隐性绑定。如果你用的是比较新的 Flutter3.x 系列构建时出现类似 the current configured flutter sdk is not known to be fully supported 的提示不要急着升级 Flutter先确认插件版本是否兼容或者查一下插件是否有对应新 SDK 的更新版本。3.2 Android 侧配置顺序微信 SDK 在 Android 上有几个硬性条件按顺序排查。第一步核对 applicationId。打开android/app/build.gradle确认applicationId与开放平台登记的包名完全一致一个字符都不能差。很多项目会在不同 buildType 里加applicationIdSuffix如果加了.debug后缀包名就变了微信授权会失败。第二步设置 minSdkVersion。微信 SDK 对 minSdk 有要求建议不小于 21。具体配置如下defaultConfig { applicationId com.example.myapp minSdkVersion 21 targetSdkVersion 34 }第三步改 AndroidManifest.xml。需要在application节点里添加微信回调 Activity 和 AppID 配置application meta-data android:nameWECHAT_APPID android:valuewxa1234567890abcdef / activity android:namecom.tencent.wechat.sdk.WechatAuthActivity android:exportedtrue android:launchModesingleTask / /application第四步处理 Android 11 的包可见性。如果 targetSdkVersion 是 30 及以上还需要在 Manifest 里声明微信的包名否则会出现调不起微信的问题queries package android:namecom.tencent.mm / /queries第五步混淆规则。release 包开了 Proguard/R8 的话需要在android/app/proguard-rules.pro里加 keep 规则-keep class com.tencent.wxop.** { *; } -keep class com.tencent.wechat.sdk.** { *; }不加的话release 包一混淆微信 SDK 的类可能被裁剪或改名表现为 debug 正常、线上授权没反应。另外提一句很多项目在升级 AGP 后会在构建日志里看到 You are applying Flutters main Gradle plugin imperatively using the apply script 这行警告。这个警告本身不影响微信登录功能但如果你同时改过 Gradle 配置要确认 Flutter 插件正常应用了否则原生侧代码不会被编译进去这属于构建层面的问题优先级在能跑起来之后再去管。3.3 iOS 侧配置iOS 的配置比 Android 啰嗦一些但逻辑其实就几条。第一Podfile 的平台版本。打开ios/Podfile确认platform :ios, 12.0微信 SDK 对 deployment target 有要求太低会编译不过或者出现 API 冲突。第二Info.plist 里的 LSApplicationQueriesSchemes。在ios/Runner/Info.plist里加keyLSApplicationQueriesSchemes/key array stringweixin/string /array这个字段用于检测微信是否安装。少了它canOpenURL返回 false登录按钮点击后 Flutter 侧会直接走微信未安装分支。第三URL Types。在 Xcode 的 TARGETS → Runner → Info → URL Types 里添加一个 URL Scheme格式是wx 你的 AppID。例如 AppID 是wxa1234567890abcdefURL Type 的 Scheme 就是wxwxa1234567890abcdef全小写。这一步等效于往 Info.plist 里加 CFBundleURLTypeskeyCFBundleURLTypes/key array dict keyCFBundleURLName/key stringwechat/string keyCFBundleURLSchemes/key array stringwxwxa1234567890abcdef/string /array /dict /array第四回调处理。iOS 13 之后如果项目用了 SceneDelegate微信回调的 openURL 可能不会自动回到原来的路径插件一般会在 AppDelegate 和 SceneDelegate 里都做 hook。如果你自己改过这两个文件注意别把插件的回调处理覆盖掉。第五universalLink 参数。插件初始化时要求传 universalLink。如果你只做微信登录这个参数可以暂时填一个占位值但如果后续要做微信分享、拉起小程序Universal Links 就得认真配置。在苹果开发者后台关联域名把 apple-app-site-association 文件放到服务器对应路径然后把完整链接传给插件。这个配置比较繁琐但值得提前规划因为微信开放平台的 AppID 一旦确定后面改 Universal Links 域名还要重新走微信侧的校验流程。3.4 初始化代码与通信回调机制配置文件折腾完回到 Dart 侧。在main.dart里尽早初始化插件import package:flutter_wechat_auth/flutter_wechat_auth.dart; Futurevoid main() async { WidgetsFlutterBinding.ensureInitialized(); await WechatAuth.instance.registerApp( appId: wxa1234567890abcdef, universalLink: https://your.domain.com/app/, ); runApp(const MyApp()); }registerApp要在应用启动早期完成不要放到某个页面里才调用。微信登录的回调是基于全局通道的等到页面级再注册可能错过回调或者出现状态错乱。微信 SDK 回调原生后插件通过 EventChannel 把结果推回 Dart。这个链路本身是稳定的但前提是 Dart 侧的回调监听器要在合适的时机注册好。好消息是loginWithWechat()返回的是一个 Future相当于把发起登录和等待回调封装在了一起不需要额外手动注册 Stream 监听。4. 登录态设计从调起微信到拿到后端 session4.1 核心登录方法代码示例与关键行解释这是登录方法的骨架FutureLoginResult wxLogin() async { if (!await WechatAuth.instance.isWechatInstalled()) { return LoginResult.fail(未检测到微信请先安装微信); } final resp await WechatAuth.instance.loginWithWechat(); if (resp.errCode 0 resp.code ! null) { return await _exchangeCodeForSession(resp.code!); } else { return LoginResult.fail(_mapWechatError(resp.errCode)); } }几个容易被忽略的点isWechatInstalled()会走原生 canOpenURL 或 package manager 查询。如果返回 false优先怀疑 LSApplicationQueriesSchemes 或 queries 配置而不是微信真的没装。resp.code是授权码有效期 5 分钟只能使用一次。用户如果连续点两次登录微信每次都会重新产生 code之前的 code 立即作废。errCode 0只是微信侧授权成功并不等于登录成功。真正的成功标志是后端完成了 code 换 token并返回了你自己的登录态。后端接口调用示例FutureLoginResult _exchangeCodeForSession(String code) async { try { final data await dio.post( /api/auth/wechat-login, data: {code: code, platform: Platform.isIOS ? ios : android}, ); final token data[token] as String; await _saveToken(token); return LoginResult.success(user: data[user]); } catch (e) { return LoginResult.fail(登录失败$e); } }注意 platform 参数建议传。因为微信开放平台里 Android 和 iOS 是两个应用后端换 token 时用的 appid 不同加上这个字段后端处理起来会舒服很多。4.2 用户点击登录后发生了什么状态机设计很多初学者只把代码写完当成功但在真实 App 里登录按钮要处理的远不止一个返回值。我把整个交互拆成几个状态idle未登录按钮可点invoking正在调起微信Android 上是 Activity 跳转iOS 上是 URL 打开都是从当前 App 切出去waitingBack已经切到微信等待用户授权后回跳exchanging拿到 code正在请求后端success拿到了 session进入已登录界面failure失败或用户取消回到 idle给用户一个再次尝试的入口其中waitingBack最容易出问题因为这个阶段 App 可能已经退到后台甚至被系统回收。我的建议是所有跟等待相关的 UI 变化都要放在状态管理容器里而不是放在某个页面的局部 State。微信登录的回调不会因为 Navigator push 而丢失因为 Future 是在调用这个方法的地方挂起的但如果整个页面被 dispose而状态只存在于那个页面里回调确实可能看起来丢了。用 Riverpod 举例final authControllerProvider StateNotifierProviderAuthController, AuthState((ref) AuthController()); class AuthController extends StateNotifierAuthState { Futurevoid loginWithWechat() async { state AuthState.loading(); final result await wxLogin(); result.ok ? state AuthState.authenticated(result.user!) : state AuthState.error(result.message); } }页面里监听这个 state按钮 loading、错误提示、登录后跳转都由 state 驱动。这样即使中间发生了页面跳转或 Widget 重建登录流程的状态不会丢。4.3 token 存储与后续请求附带登录成功后Flutter 侧保存的是后端返回的自定义登录态而不是微信的 openid 或 access_token。原因很直接后端 token 有自己的时效和刷新机制前端只管带着它访问接口微信的 access_token 应当只存在于后端前端保存它既浪费又危险存储建议用flutter_secure_storage它在 iOS 上走 KeychainAndroid 上走 EncryptedSharedPreferences比明文存储安全一个档次const storage FlutterSecureStorage(); await storage.write(key: session_token, value: token);每次请求在拦截器里附带dio.interceptors.add( InterceptorsWrapper( onRequest: (options, handler) async { final token await storage.read(key: session_token); if (token ! null) { options.headers[Authorization] Bearer $token; } return handler.next(options); }, ), );冷启动时先读 token再去后端校验有效性。有效就直接进主界面不需要再弹微信无效再走登录流程。这里有个产品层面的原则不要自动静默调起微信登录用户没点按钮之前App 不应该自己唤起微信。这既是体验问题也是微信开放平台审核时会关注的行为。4.4 退出登录一个容易想多的地方微信登录机制里的登录是一次授权关系的确立。用户在微信里同意之后你的 App 在微信侧就有了长期授权关系除非用户在微信的隐私-授权管理里主动解除否则后续发起新的登录授权时微信可能直接返回一个 code不再每次弹确认页具体取决于微信版本和用户设置。所以 App 内的退出登录实际只需要做两件事清掉本地 token、清掉内存中的用户状态。不要尝试调用微信接口来撤销登录微信开放平台并没有提供面向 App 内退出登录的通用接口。如果你确实想让用户完全断开微信授权只能引导用户去微信的授权管理里操作。5. 双端实测中的坑与排查思路含日志定位方法5.1 Android 高频错误 1调起微信提示应用未注册或直接无反应这是我见过次数最多的错误。现象点击微信登录微信 App 被唤起但弹出应用未注册提示或者干脆白屏一下然后没有反应。排查顺序核对开放平台包名。打开开放平台 App 详情确认绑定的包名和当前 build.gradle 里的 applicationId 严格一致注意大小写。核对签名 MD5。用签名工具或 keytool 算出的 MD5 与开放平台登记的一致。检查 Manifest 里的 WECHAT_APPID 是否一致。同一个包名下只能有一个微信应用值必须是开放平台分配的那个 wx 开头的 AppID。如果以上都对考虑签名缓存问题。微信 App 会缓存它见过的应用签名如果你之前在开放平台填的签名和现在包里实际签名不同微信端会按未注册处理。更换签名后的调试包建议先清除微信 App 的缓存数据再重试。日志定位法在终端跑adb logcat -s WechatSDK WechatAuthActivity复现点击操作正常流程里能看到微信 SDK 打印出调用方包名和签名信息。如果日志显示签名匹配失败基本就是签名问题不用再找别的原因。5.2 iOS 高频错误 2点击按钮回到微信授权页一闪而过或回调不了iOS 上最常见的翻车点不在 Dart 代码而在 Xcode 配置。现象一点击登录后直接返回微信未安装。优先检查 LSApplicationQueriesSchemes 里有没有weixin其次检查真机是否真的装了微信。现象二微信打开了但授权页没出来或者授权完成回不来。检查 URL TypesScheme 必须是wx 完整 AppID全部小写。大小写错、少一位、多一位回调都不通。现象三能授权但 Dart 侧收不到结果。检查 AppDelegate / SceneDelegate 里的 openURL 处理是否被自己覆盖了。插件往往通过运行时 hook 或依赖 Flutter 的 deep linking 机制来分发回调如果你手写了一个application(_:open:options:)然后没有走 Flutter 的默认处理回调就会断在原生层。解决办法是保留插件默认的 AppDelegate 配置不要做多余拦截。日志定位法在 Xcode 的 Console 里按进程过滤或者直接在 AppDelegate 里打日志确认openURL有没有触发、url 内容是什么。如果触发了但格式不对立刻就能定位是 URL Type 的问题。5.3 跨端通用坑模拟器问题。Android 模拟器上可以装微信但登录授权受限比较严重iOS 模拟器装微信也不方便。微信登录这种涉及真实 App 跳转的功能强烈建议直接真机调试这是效率最高的做法。Proguard 混淆。Android release 包出现登录无反应优先怀疑混淆规则按前面第 3 节加 keep 规则再打包。多环境 AppID 串用。项目同时有 dev、prod 环境不要图省事全用同一个 AppID。否则你在 dev 环境测试时微信返回的用户身份会被后端和 prod 环境混在一起账号体系会乱。更稳妥的是每个环境在微信开放平台单独建应用各用各的包名和签名。后端验签失败。前端链路全通、用户在微信里也点了允许、code 也拿到了但后端换 token 失败。检查后端用的 appid 和 secret 是否和当前移动应用一致微信接口是否用了 POSTcode 是否已经被前一次请求消费。一个 code 只能用一次第二次请求会报无效或已使用。微信版本过旧。如果用户手机上的微信版本太老调起登录时也可能出现异常行为。可以在登录按钮页面加一个版本检测提示但微信本身会做大部分兼容处理这个坑属于少数情况遇到了优先换新版本微信测试。5.4 一个典型的日志定位法实操我自己的排查习惯是固定一个流程遇到问题按顺序过确认 AppID 正确wx开头长度和字符别错。确认基础能力Android 看 ManifestiOS 看 Info.plist 和 URL Types。确认开放平台配置包名、签名、平台类型。真机复现采集原生日志。Flutter 侧打点在调用loginWithWechat()前后各打一条日志记录返回值 errCode。这个流程走完90% 的问题都能定位。剩下那 10% 通常和微信 App 版本、系统限制有关换台手机、换个微信号试一下往往就有结果。这个定位流程是我从几次深夜排查里总结出来的。前两次遇到微信登录问题都是在为什么代码没问题但功能不起来上卡了很久最后才发现少配了一个 queries 或者填错了签名。微信登录这种东西真不是写完 Dart 代码就算完把开放平台后台和双端配置文件当成正式环境来管理才能减少那类昨天还好好的今天就不行了的惊悚事件。最后分享一个小习惯每次改过签名、包名、AppID 之后我都会把真机上微信的缓存清掉再测试。微信对应用身份的缓存很顽固不清理的话你新配的签名可能还是旧值容易误导排查方向。
