小程序运行机制 - 内存缓存

内存缓存生命周期说明

为便于更清晰地感知小程序进入与恢复内存缓存的状态变化，小程序 App 对象 上新增内存缓存相关生命周期事件，用于区分不同阶段并处理不同逻辑。

新增生命周期事件

事件名称	事件标识	触发时机
暂停	`onPause`	小程序进入内存缓存状态时触发
恢复	`onResume`	小程序从内存缓存状态恢复时触发

兼容性说明

为保证现有小程序不受影响，原有的 App.onShow 与 App.onHide 生命周期仍会正常触发。

在涉及内存缓存的场景下，生命周期事件的触发顺序如下：

进入内存缓存

触发 App.onPause
触发 App.onHide

从内存缓存状态恢复

触发 App.onResume
触发 App.onShow

export default class App extends React.Component {
  // did mount 的触发时机是在 onLaunch 的时候
  componentDidMount() {
    console.log('App launch');
  }
  onPause() {
    console.log('进入内存缓存状态');
  }
  onResume() {
    console.log('从内存缓存状态恢复')
  }
  render() {
    return this.props.children;
  }
}

对于函数组件的 App, 可以通过 useAppEvent hook 来监听生命周期

ray 版本需 >= 1.7.39

import { useAppEvent } from '@ray-js/ray';

export default function App(props) {
  useAppEvent('onPause', () => {
    console.log('进入内存缓存状态');
  });
  useAppEvent('onResume', () => {
    console.log('从内存缓存状态恢复')
  });
  return props.children;
}

1. 小程序生命周期

小程序从启动到最终销毁，会经历多个不同的状态，在不同状态下有不同的运行表现。
整体流程如下图所示：

1.1 小程序启动

从用户的角度来看，小程序的启动可以分为两种：

冷启动：
当用户第一次打开小程序，或者小程序被销毁后再次打开时，需要重新加载全部资源并启动，这种情况称为冷启动。
热启动：
当用户之前已经打开过小程序，在短时间内再次进入时，小程序并未销毁，只是从后台恢复到前台，这称为热启动。

在生命周期术语中，我们通常将“启动”特指冷启动，而热启动一般描述为「后台切前台」。

1.2 前台与后台

当小程序启动后并展示给用户时，处于「前台」状态。
用户离开小程序时，小程序并不会立即销毁，而是进入「后台」状态，此时仍会短暂保留在内存中。

进入后台的常见方式包括：

点击右上角胶囊按钮离开小程序
iOS 从屏幕左侧右滑返回
Android 点击返回键
小程序运行时切后台（Home 键或手势）
小程序运行时锁屏

当用户再次回到 App 并打开该小程序，小程序会重新进入「前台」状态。

1.3 小程序销毁

当小程序长时间未被使用或系统资源不足时，小程序会被彻底销毁。
销毁后，再次打开即为冷启动。

常见销毁场景包括：

小程序进入后台后 10 分钟未重新进入前台；
同时打开超过三个小程序时，最早进入后台的小程序会被销毁。

2. 小程序冷启动的页面

当小程序冷启动时，打开的页面有以下情况：

A 类场景：启动场景中不带 path，小程序容器会根据 entryPagePath 进入默认页面。
B 类场景：启动场景中带有 path，小程序将直接进入对应页面。

3. 小程序热启动的页面

热启动时，小程序打开的页面规则如下：

默认情况下，热启动会回到小程序冷启动时进入的第一个页面；
若配置了 cachePageStack: true，则会保留上次的浏览状态，即恢复上次退出前的页面堆栈。

配置项位置：global.config.ts

属性	类型	必填	描述
cachePageStack	boolean	否	退出时是否保留所有页面

4. 主动销毁

如果业务上希望小程序每次启动都重新加载，可以通过如下配置项实现主动销毁：

配置项位置：global.config.ts

属性	类型	必填	描述
disableCache	boolean	否	退出时是否销毁小程序

当配置为 true 时，小程序生命周期如下图所示：

5. 不进行内存缓存的场景说明

在某些情况下，小程序关闭时会直接销毁，而不会进行内存缓存。
也就是说，下次打开时会重新加载，而非从内存中恢复。

以下情况会触发直接关闭（不缓存）：

非正式版本的小程序：如开发版、体验版等不做缓存。
关闭时有白屏：若用户关闭时小程序页面异常（如白屏），系统会直接销毁，避免恢复异常页面。
关闭时小程序流程未结束：比如仍有小程序启动流程、接口请求在执行中，此时不会缓存。
小程序主动禁用缓存：若在global.config.ts配置中设置了 disableCache: true，关闭后直接销毁。
开启了体验评分功能的小程序：当用户可对小程序进行体验评分时，为保证体感一致性，不使用缓存。
处于原生 Tab 栏的小程序：在 Native Tab 栏中的小程序不支持内存缓存，会直接关闭。

6. 补充说明

只有在满足缓存条件的情况下，小程序关闭时才会进入内存缓存状态
被缓存的小程序在再次打开时，可更快恢复到上次状态，提升体验
若不满足缓存条件或被主动销毁，下次打开小程序即为冷启动

7. 常见问题（FAQ）

Q1：为什么我点击手机的返回键退出小程序后，再次进入时还停留在上次页面？

这是因为当前小程序在关闭时被内存缓存了。
当你再次打开时，系统会直接恢复上次的状态，而不是重新启动。

解决方法： 在小程序的全局配置文件 global.config.ts 中设置：

   disableCache: true

Q2：我想保留小程序上次操作的页面，下次打开还能接着用，要怎么配置？

只需确保：

没有设置disableCache: true
没有触发直接关闭的情况（见上文第5节）

默认情况下，小程序会自动进入内存缓存模式，下次打开会恢复到上次界面。

Q3: 哪些情况下小程序不会被缓存？

小程序是开发版/体验版
关闭时出现白屏
启动时后台任务未完成
启用了体验评分功能
在 Native Tab 栏中
显示配置了 disableCache: true

#内存缓存生命周期说明

#新增生命周期事件

#兼容性说明

#进入内存缓存

#从内存缓存状态恢复

#1. 小程序生命周期

#1.1 小程序启动

#1.2 前台与后台

#1.3 小程序销毁

#2. 小程序冷启动的页面

#3. 小程序热启动的页面

#4. 主动销毁

#5. 不进行内存缓存的场景说明

#6. 补充说明

#7. 常见问题（FAQ）

#Q1：为什么我点击手机的返回键退出小程序后，再次进入时还停留在上次页面？

#Q2：我想保留小程序上次操作的页面，下次打开还能接着用，要怎么配置？

#Q3: 哪些情况下小程序不会被缓存？