# 小程序备份列表（backuplist）参数说明

# 一、参数作用

backuplist 是备份参数列表，用于在主加载失败时自动切换到备用加载地址，提高小程序加载成功率。

当以下任一情况发生时，系统会自动尝试使用 backuplist 中的备用参数重新加载：

触发场景	说明
内核加载失败	主参数对应的内核版本加载失败时
页面加载超时	主 URL 在规定时间内未加载完成
JS 模块加载失败	主地址的 JS 模块加载失败，且小程序尚未成功加载过
尝试下一个备份	页面状态监听器主动请求切换备份

切换策略：从备份列表中选取「最久未尝试」的项进行加载；同一备份在 15 分钟内 不会重复尝试，避免频繁重试。当加载失败时，若仍有内容可尝试则不会触发 MiniAppObserver.onMiniAppLoadFail, 而当所有内容都尝试失败后, 才会回调 MiniAppObserver.onMiniAppLoadFail。

# 二、如何传入 backuplist

参数名：backuplist（不区分大小写）

# 方式一：URL 参数（JSON 数组）

在启动小程序的 URL 后追加 backuplist 参数，值为 JSON 数组字符串（需 URL 编码）。

格式 1：纯 URL 字符串数组

?backuplist=["jsvconfig://http/xxxx/backup1/app.config","jsvconfig://http/xxxx/backup2/app.config"]

格式 2：完整配置对象数组

每个元素可以是包含完整启动参数的 JSON 对象：

?backuplist=[{"url":"https://backup1.example.com/app.mjs","coreVersionRange":"1021977","engine":"xxx"},{"url":"https://backup2.example.com/app.mjs","coreVersionRange":"1021977","engine":"xxx"}]

示例命令：

am start -n com.tvcode.sjcenter/com.tvcode.chmarket.MainActivity \
  --es URL "https://main.example.com/app.mjs?ENGINE=embedded&COREVERSIONRANGE=1021977" \
  --es backuplist '["jsvconfig://http/xxxx/backup1/app.config","jsvconfig://http/xxxx/backup2/app.config"]'
  
# 或者

am start -n com.tvcode.sjcenter/com.tvcode.chmarket.MainActivity \
  --es URL "https://main.example.com/app.mjs?ENGINE=embedded&COREVERSIONRANGE=1021977&backuplist=%5B%22jsvconfig%3A%2F%2Fhttp%2Fxxxx%2Fbackup1%2Fapp.config%22%2C%22jsvconfig%3A%2F%2Fhttp%2Fxxxx%2Fbackup2%2Fapp.config%22%5D"

1
2
3
4
5
6
7
8

# 方式二：Intent / Bundle 传入

通过 Intent 或 Bundle 启动时，backuplist 支持以下类型：

类型	说明
`List`	元素可为 `String`（URL）、`Intent`、`Bundle`、`JSONObject`
`Parcelable[]`	同上，以数组形式传入

示例（伪代码）：

// 方式 A：List<String> 传入多个备份 URL
List<String> backupUrls = Arrays.asList(
    "jsvconfig://http/xxxx/backup1/app.config",
    "jsvconfig://http/xxxx/backup2/app.config"
);
intent.putStringArrayListExtra("backuplist", new ArrayList<>(backupUrls));

// 方式 B：List<Bundle> 传入完整参数
ArrayList<Bundle> backupBundles = new ArrayList<>();
Bundle b1 = new Bundle();
b1.putString("URL", "https://backup1.example.com/app.mjs");
b1.putString("COREVERSIONRANGE", "1021977");
b1.putString("ENGINE", "xxxx");
backupBundles.add(b1);
intent.putParcelableArrayListExtra("BACKUPLIST", backupBundles);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 方式三：jsvconfig 配置

在 jsvconfig（JSON 配置）中传入：

{
  "url": "https://main.example.com/app.jsv",
  "engine": "embedded",
  "coreVersionRange": "1021977",
  "backuplist": [
    "jsvconfig://http/xxxx/backup1/app.config",
    {
      "url": "https://backup2.example.com/app.mjs",
      "coreVersionRange": "1021976",
      "engine": "embedded"
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 三、备份项可配置参数

每个备份项支持与主参数相同的 MiniAppParams 配置，常用字段包括：

参数	说明
`url`	备份加载地址（必填）
`coreVersionRange`	内核版本要求（备份的所有 core 版本必须与主的一致）
`engine` / `engineUrl`	引擎地址 (必填)
`pluginBaseUrl`	插件下载地址（可选）
`coreUpdateUrl`	内核更新地址（可选）
其他	启动图、分辨率、启动模式等，与主参数一致

# 四、Android 监听备份切换：`onMiniAppBackupSwitching`

宿主可在 MiniAppObserver 中重写默认方法 onMiniAppBackupSwitching，在系统即将用下一套备份参数走内核就绪与 reload 之前收到通知（对应一次「主备切换」决策）。便于埋点、日志或与业务 UI 联动。

# 4.1 触发条件

规则	说明
必须有非空 `backuplist`	仅当当前启动参数里配置了非空的 `backuplist` 时才会回调；未配置备份列表时不会调用本方法。
可能多次	同一轮加载中若多次尝试备份（如超时后再切、解析下一备份 URL 等），可能多次触发。

# 4.2 参数说明

参数	类型	含义
`miniApp`	`MiniApp`	当前小程序实体。
`currentParams`	`MiniAppParams`	当前这一次 load 对应的参数快照（失败或切换前正在用的那一套）；由容器在发起加载的最早时机维护（内部 `mActiveLoadParams`），避免与滞后赋值的字段不一致。可能为 `null`。
`nextParams`	`MiniAppParams`	即将用于加载的备份参数；若当前轮已无可用下一套备份（例如列表用尽、防抖内无法切换等），则为 `null`，表示「有备份列表但这次切不过去 / 没有 next」。

接口在 com.tvcode.js_view_app.MiniAppObserver 中为 default 空实现，仅需按需重写。

# 4.3 注册方式

JSViewParent.registerMiniAppObserver(MiniAppObserver)：容器内多个 JSViewItem 的备份切换会转发给已注册的观察者。
经 MainPageProxy 设置的全局 MiniAppObserver 同样会收到转发（与现有 onMiniAppStartLoad 等一致）。

示例（节选）：

jsViewParent.registerMiniAppObserver(new MiniAppObserver() {
    @Override
    public void onMiniAppBackupSwitching(MiniApp miniApp,
            MiniAppParams currentParams, MiniAppParams nextParams) {
        if (nextParams != null) {
            // 即将切到备份：可比对 currentParams / nextParams 的 url、baseUrl 等
        } else {
            // 仍有 backuplist 配置，但当前没有可切换的下一套参数
        }
    }

    // ... 其他必须实现的方法 ...
});

1
2
3
4
5
6
7
8
9
10
11
12
13

# 五、JS 端主动发起切换备份

当发生路由切换失败时, 主动调用进行主备切换的方法: jJsvRuntimeBridge.tryNextBackupIntent();

此方法自动发起用下一个备用地址进行页面reload

import { onMounted, onBeforeUnmount } from 'vue'
import { jJsvRuntimeBridge } from 'jsview'

// 当模块加载失败时, 切换到下一个备份
let moduleFailedFunc = (failedUrl, faildCode, failedDetailString) => {
  // 日志发送...

  // 重点!!!!
  // reload并加载备用地址
  jJsvRuntimeBridge.tryNextBackupIntent();
}

onMounted = ()=>{
  // 监听路由切换的懒加载处理失败的事件
  window.JsvCoreApi.addModuleFailedAck(moduleFailedFunc);
}

onBeforeUnmount = ()=>{
  // 取消监听
  window.JsvCoreApi.removeModuleFailedAck(moduleFailedFunc);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 六、注意事项

URL 编码：通过 URL 传参时，JSON 中的 [、]、" 等需正确 URL 编码。
顺序：备份列表按顺序尝试，优先使用 startLoadTime 最小的（最久未尝试的）项。
防抖：同一备份在 15 分钟内不会重复尝试，避免无效重试。
可选：不传 backuplist 时，主加载失败将直接通知失败，不会自动切换备份。

← 拦截即将启动的程序小程序加载相关 →