# 小程序备份列表（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`	内核更新地址（可选）
其他	启动图、分辨率、启动模式等，与主参数一致

# 四、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 时，主加载失败将直接通知失败，不会自动切换备份。

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