App Bridge 新版迁移：老嵌入应用会遇到的白屏问题

发生了什么#

App Bridge 从早期的 script 标签模式迁移到新版后，嵌入应用的鉴权、导航、弹窗、Toast 等能力都改成了模块化调用。迁移的常见症状是「应用在后台里白屏」或「一直转圈」——通常不是代码报错，而是会话令牌没拿到或 iframe 通信失败。

关键细节#

• 新版以 npm 包形式引入，不再依赖全局脚本
• 会话令牌获取方式变化，需配合后端验证
• 导航、Modal、Toast 等改为 API 调用
• iframe 环境下的 cookie 策略变化会影响登录态
• 旧的全局对象调用会逐步失效
• 新版导航与弹窗改为 API 调用，旧写法逐步失效
• 迁移后需重新验证嵌入环境下的加载性能

对商家与开发者的影响#

白屏是最难排查的故障之一：浏览器控制台可能没有任何错误，因为问题出在 iframe 与外层的通信。排查时先看是否拿到了会话令牌。

对商家，表现是「应用打不开」。这类问题通常需要开发者介入，自己刷新没用。

对商家，遇到「应用在后台打不开」时，可以先换浏览器或无痕模式试一次，排除 cookie 与缓存因素，再联系开发者。

建议动作#

1. 迁移时优先验证会话令牌获取链路
2. 检查第三方 cookie 策略对登录态的影响
3. 保留旧版回滚分支，分批放量