跨平台三大踩坑总览：作用域、字段所有权、正文接口

跨平台移植翻车，九成翻在这三个坑里。发移植帖前请逐条自查。

坑一：作用域与 WebView 上下文隔离

三个作用域是三个世界：

1. jsLib 在 loginUrl 里不可用——上下文隔离。登录脚本需要的公共函数要么内联，要么走全局桥接。
2. webViewJs 的求值语义与普通 JS 不同：香色按 Script 语义求值，禁顶层 return，必须单表达式 IIFE。
3. onPress 的上下文在各宿主能调用的 API 不同，移动端回调和桌面事件的对象结构也不同。

自查清单：

text
□ 我的代码在哪一层运行？（规则 / 登录脚本 / WebView / 回调）
□ 这一层能访问哪些全局对象？（逐个确认，不要猜）
□ 同一段代码在两层都测试过吗？

坑二：存储与字段所有权

同名 API 在不同宿主语义不同：

• 源阅用 source.getVariable；
• Legado 用 source.getVariable / setArguments，另有 cache；
• 轻悦用 LoginInfo 与面板专用存储。

谁写谁读、生命周期多长、换机后还在不在，跨宿主完全不同。移植前先画一张字段所有权表：

text
字段名 | 谁写入 | 谁读取 | 存哪里 | 生命周期 | 用户可见吗

这张表本身就是帖子的精华部分——发移植帖时附上它，采纳率明显更高。

坑三：正文与接口

• HTTP 200 不等于业务成功；JSON 可解析不等于正文可用。
• cookie 在源阅是 CookieJar 自动带、Legado 手动管理、轻悦走 flutterBridge——同名不等于同义。
• 响应编码：URL 选项里显式声明 charset，别依赖自动探测。
• 分页语义：有的平台 nextPageUrl 以特殊符号开头即停止请求，跨平台移植时先确认目标平台的停止条件。

怎么避坑

见本节点另外两篇：《同名不等于同义术语表》和《迁移铁律：只传业务契约》。一句话版本：**业务逻辑可以跨，宿主实现不能搬。**每个坑踩过之后，把你的案例回复到对应帖子下，这是社区沉淀最快的路径。