踩坑实录：微信小程序返回 App 失败？一次 `launchMode` 导致的 Activity 任务栈“迷航”

在 Android 应用开发中，集成微信登录、支付或小程序跳转等功能时，我们常常需要定义一个特定的回调 Activity，即 WXEntryActivity。最近，调试小程序遇到了一个让人困惑的问题：从微信小程序返回 App 时，App收到了相关信息，但无法正常展示离开的页面。

经过一番排查和调整，终于找到了问题的根源，之前代码中误将 WXEntryActivity 的 launchMode 设置为了 "singleInstance" ，修改为 "singleTask" 后，恢复正常。

本文将分析这背后的原理，进一步理解 Android Activity 的 任务栈 (Task Stack) 机制，以及这两种 launchMode 在微信回调场景中的巨大差异。

当用户在 App 内启动微信小程序，完成操作后，点击左上角的"返回 App"按钮，或者微信回调启动 WXEntryActivity 处理结果后，App 无法正确返回到启动小程序的前一个页面，表现为界面停滞或回到了一个不正确的状态。

将项目 AndroidManifest.xml 中 WXEntryActivity 的 android:launchMode 配置从 "singleInstance" 修改为 "singleTask"。

XML

ini 复制代码

<activity
    android:name="com.xxx.wxapi.WXEntryActivity"
    android:launchMode="singleTask"
    android:exported="true"
    ...
/>

理解这个问题，关键在于理解 singleInstance 对 Activity 任务栈的极端要求。

当 Activity 被设置为 singleInstance 时，系统会强制执行以下两个规则：

启动： App 的某个页面 A 启动了微信小程序。
回调： 微信小程序完成后，回调启动 WXEntryActivity。此时，WXEntryActivity 因为是 singleInstance，它被放置在了一个全新的、独立的任务栈 T2 中。
App 状态： 您的 App 主任务栈 T1 （包含 A Activity 等）仍然存在于后台。
返回失败： WXEntryActivity (在 T2 中) 处理完数据后，通常会调用 finish() 结束自己。由于 T2 栈中只有它一个 Activity，T2 任务栈也会随之销毁。然而，系统在销毁 T2 之后，并没有正确地将 T1 任务栈中的顶部 Activity (即 A) 重新带到前台。这导致用户体感上就是"无法返回"。

singleTask 模式是专门为这种"中转站"和"入口"类 Activity 设计的最佳选择。

寻找任务栈： Activity 启动时，系统会搜索系统中是否存在与该 Activity taskAffinity 匹配的任务栈。
重复利用： 如果目标任务栈（即我们的 App 主任务栈 T1）存在：
- Activity 会被放置在 T1 中。
- 如果 T1 栈中已经存在该 Activity 实例，系统会清除位于该实例之上的所有 Activity，使它成为栈顶，并调用它的 onNewIntent() 方法。
栈中唯一： 在一个任务栈内，WXEntryActivity 始终只有一个实例。

启动： App 的 Activity A 启动微信小程序。
回调： 微信小程序回调启动 WXEntryActivity。由于是 singleTask，系统会把 WXEntryActivity 直接放置在 App 的主任务栈 T1 的栈顶 ，位于 A 的上方。
- 任务栈 T1 状态： ... -> Activity B -> Activity A -> WXEntryActivity (栈顶)
正常返回： WXEntryActivity (在 T1 中) 处理完数据后，调用 finish() 结束自己。
完美衔接： WXEntryActivity 出栈后，Activity A 自然而然地成为 T1 的栈顶，系统会将其带到前台，完美地回到了启动小程序的前一个页面，符合用户预期。

对于微信回调接口 WXEntryActivity 而言，它的核心职责是：接收回调结果，处理数据，然后迅速退出，将控制权交还给 App 的主业务页面。

launchMode	适用场景	微信回调场景	结果
`singleInstance`	需要完全独立、隔离的"单一窗口"应用，如闹钟、来电显示等。	❌ 不适用，创建独立任务栈，返回时无法正确激活主 App 栈。	返回失败/卡顿
`singleTask`	业务流程中的"中转站"或"主入口"，确保其只有一个实例，且位于主任务栈。	✅ 最佳实践，确保 Activity 位于主任务栈顶部，`finish()` 后完美返回。	返回正常

建议： 在集成任何需要回调的第三方 SDK (如微信、支付宝) 时，其回调 Activity 的 launchMode 几乎都应该选择 singleTask，以确保其正确集成到 App 的主任务流程中，避免出现任务栈混乱导致的导航问题。