HostApp 核心 H5 架构踩坑与进化史

国际化最直观的痛点是：同一个页面，要在不同的国家、不同的渠道、带着不同的语言参数发出去。以前我们傻傻地搞过"构建时拆包"，针对每个语种发一份静态 Bundle。结果运营同学疯了，投放链接天天配错，CDN 刷新能把人搞 PTSD。

后来我们一拍大腿，直接换成了运行时策略。

// 伪代码：在入口处给语言打个底
FUNCTION 初始化海外文案()
    DEFINE 支持的语言列表 = [TYPE_LANG_A, TYPE_LANG_B, TYPE_LANG_C, TYPE_LANG_D]

    // 解析优先级：URL 参数 -> 浏览器缓存 -> HostApp 注入上下文 -> TYPE_LANG_D 默认兜底
    DEFINE 当前语言 = 逐级解析(URL参数 -> 浏览器缓存 -> HostApp注入上下文)

    // 白名单外回落 TYPE_LANG_C（产品约定备用语种，不走 TYPE_LANG_D 默认链）
    IF 当前语言 不在 支持的语言列表 THEN
        SET 当前语言 = TYPE_LANG_C
    END IF

    LocalizationCore.激活语言(当前语言)
    GlobalConfigProvider.同步底层UI组件文案(当前语言)
END FUNCTION

跨境电商最魔幻的场景是：商品在后端是用 A 币种（基准币）标价的，用户人在海外，想用 B 币种（展示币）看，但到了最后一步下单，对不起，我们只收 C 币种（结算币）。为了不让代码变成一坨糨糊，我们把汇率模块强行劈成了三层：

LAYERS: 眼见为实层|视图|搞清楚用户到底想看什么钱。优先听 HostBridge 的，其次看 URL 里的白名单参数，再没有就老老实实隐藏参考价，千万别瞎猜，不然用户以为占了便宜，结账时会来投诉的。 情报贩子层|数据|负责去网关捞最新的汇率，并且做好缓存。 精算师层|展现|把后端给的"分"转换成"元"，算好汇率，格式化输出。

这里有两个在真实战壕里总结出来的防爆规范：

RULES: Promise 状态锁|防刷|一个列表页有几十个商品卡片，如果每个卡片在挂载时都去问一次"现在汇率是多少"，后端网关会被打爆的。 严禁在 JS 里直接算"元"|防爆|0.1 + 0.2 !== 0.3 这个著名的梗，在普通网页里顶多算个显示 Bug，在收银台里就是实打实的 P0 级资损事故。我们强行规定：后端给的金额一律是整数（分），前端计算一律用标准高精度数学库，算完汇率再四舍五入。

// 伪代码：汇率接口的 Singleflight 状态锁
DEFINE 全局唯一请求锁 = NULL

FUNCTION 捞汇率配置()
    IF 全局唯一请求锁 已经存在 THEN
        RETURN 全局唯一请求锁 // 后面来的别催了，和前面那哥们用同一个结果
    END IF

    SET 全局唯一请求锁 = 发起网络请求('/api/rate/config')

    TRY
        DEFINE 结果 = AWAIT 全局唯一请求锁
        RETURN 结果
    FINALLY
        SET 全局唯一请求锁 = NULL // 完事了把锁解开
    END TRY
END FUNCTION

我们的 H5 页面经常要通过 PromoHub 投放到各种奇奇怪怪的地方，有时候在自家的 HostApp 里，有时候在别人的第三方软件里。宿主环境不同，页面的长相和脾气就得跟着变。

刘海屏、安全区、原生导航栏……这些都是 H5 的宿敌。我们用了一个很轻量的"场景适配器"：应用一启动，先在页面 URL 里抓取 scene 标记。如果在自家 App 里（scene=app_internal），那好，通知原生容器把导航栏藏起来，H5 页面自己去算顶部留白，把 Notch（刘海）空出来。如果在第三方环境（scene=ext_webview），那就得小心翼翼地把底部的虚拟主页键（Safe Area）用样式顶上去，免得按钮被挡住。

上层业务组件不需要知道这些破事，它们只需要套上一个 LayoutWrapper：

// 伪代码：动态刘海留白适配
FUNCTION 计算顶部留白(基础高度)
    IF scene == SCENE_APP_INTERNAL AND 原生导航栏已隐藏 THEN
        RETURN 基础高度 // 空出刘海或状态栏距离
    ELSE
        RETURN 0 // 端外 WebView 或纯浏览器，无需额外留白
    END IF
END FUNCTION

在端外跑的时候，应用难免会用到原生能力。如果我们直接调用 window.HostBridge.xxx()，页面就当场碎给你看。所以，所有的桥接调用，必须做能力检测和降级。

// 伪代码：哪怕没了App，日子也能过
MODULE 核心桥接适配器
    EXPORT FUNCTION 打开新窗口(目标链接)
        IF HostBridge.isInApp() AND HostBridge.openWeb 可用 THEN
            CALL HostBridge.openWeb({ url: targetUrl })
        ELSE
            SET 浏览器地址栏 = 目标链接 // 端外老老实实走 H5 跳转，至少保证页面别死
        END IF
    END FUNCTION
END MODULE

电商业务变色龙还快。今天上架个衣服（实物类），明天下架个景区门票（旅游类），后天又来个充值话费（虚拟服务）。如果把所有的表单逻辑、详情展示都写在一个 Detail.js 里，过不了半年，这个文件就会变成谁都不敢动的"祖传代码"。

我们的商品详情页现在是一个"空壳网关"。它拿到商品 ID 后的第一件事，是问后端：这货属于哪个业态？衣服这类实物走 TYPE_PHYSICAL 异步拉 TypeAUI，门票这类旅游场景走 TYPE_TRAVEL 拉 TypeBUI，充值话费等其余业态走 default 分支拉 FallbackUI。

// 伪代码：详情页的业务分发
FUNCTION 详情页分发核心(商品元数据)
    DEFINE 业态类型 = 商品元数据.type
    DEFINE 实际渲染组件 = NULL

    // 二级分包：看什么业态，下载什么JS，绝不多下载一字节垃圾代码
    SWITCH 业态类型
        CASE TYPE_PHYSICAL:
            SET 实际渲染组件 = 异步加载('./modules/TypeAUI')
        CASE TYPE_TRAVEL:
            SET 实际渲染组件 = 异步加载('./modules/TypeBUI')
        DEFAULT:
            SET 实际渲染组件 = 异步加载('./modules/FallbackUI')
    END SWITCH

    RETURN 渲染(实际渲染组件, 商品元数据)
END FUNCTION

架构师大白话：

这样设计的大好处是——卖衣服的前端和卖门票的前端可以在各自的目录里疯狂输出，互不干扰。而且，买衣服的用户绝对不会下载到景区地图、出行人填写的任何一行 JS 脚本，首屏加载速度直接飞起。

店铺首页更加激进，直接变成了"无头 CMS（Headless CMS）"。后端给的不是数据，而是一张"积木搭建图纸"（Schema JSON）。里面写着：第一行是个轮播图，第二行是个优惠券区块，第三行是个商品双列瀑布流。前端手里有一张组件映射表，拿到图纸后像拼积木一样循环渲染出来。运营在后台拖拽控件，前端不需要重新发版，店铺长相就能天天不重样。

有些频道页（比如门票首页）接口多、链路长、还要初始化国际化上下文，难免会有零点几秒的白屏。用户在这期间疯狂乱点，体验极差。我们的解法是：路由识别到是高频核心页面，不废话，直接第一秒挂载一个静态骨架屏。当你在登录、解析多语言、等网络请求的时候，用户眼睛里看到的是一个隐隐约约的页面结构。这不仅能极大地压低 FCP（首次内容渲染时间）损耗，还能防止后续组件异步拼装好时，页面突然"抖动"一下（也就是 CLS 布局偏移）带来的不适感。

在单页应用里，有个很恶心的体验：你从长列表页点进商品详情，然后再点返回，有些浏览器会自作聪明地帮你"恢复滚动位置"。但因为列表页的数据是异步加载的，返回的一瞬间页面还没撑开，浏览器一恢复，直接把你丢到了一个莫名其妙的中间位置，甚至直接置顶了。我们在全局入口直接剥夺了浏览器的这项权利：

// 伪代码：消灭浏览器的自作聪明
IF 浏览器支持自定义滚动恢复 THEN
    SET 浏览器历史滚动恢复模式 = 'manual' // 手动挡，放开那条路由，让我来！
END IF

改成手动挡之后，我们在列表页组件重新挂载、动态数据确认渲染完毕后，再配合本地存的 scrollTop 标记，用代码极其丝滑地把用户"送回"他刚才浏览的位置。

折腾完这一整套方案，回头看看，跨境电商前端架构最核心的其实就两个词：

KEYWORDS: 弹性|对多渠道、多环境要保持足够的弹性，底层的 Bridge、i18n 和布局永远要想好降级策略，不能在端外就直接摆烂。 克制|对包体积、精细化组件、网络请求则要保持极度的克制，能合并的请求要合并，不该加载的组件一口也别多吃。

把这些细节扣干净了，H5 也能跑出不输 Native 的底气。