---
title: Mini Program Runtime Mechanism - Memory Cache
---

## Memory Cache Lifecycle Description

To facilitate clearer understanding of the changes in a Mini Program's state when entering and resuming memory cache, new memory cache-related lifecycle events have been added to the Mini Program's **App object** to distinguish different stages and handle different logic.

### New Lifecycle Events

| Event Name | Event Identifier | Triggering Time                                                     |
| ---------- | ---------------- | ------------------------------------------------------------------- |
| Pause      | `onPause`        | Triggered when the Mini Program enters the memory cache state       |
| Resume     | `onResume`       | Triggered when the Mini Program resumes from the memory cache state |

### Compatibility Notes

To ensure that existing mini-programs are not affected, the original `App.onShow` and `App.onHide` lifecycle methods will still be triggered normally.

In scenarios involving memory caching, the triggering order of lifecycle events is as follows:

#### Entering Memory Cache

1. Trigger `App.onPause`
2. Trigger `App.onHide`

#### Resuming from Memory Cache State

1. Trigger `App.onResume`
2. Trigger `App.onShow`

```js
Page({
  onPause() {
    console.log('Entered memory cache state');
  },
  onResume() {
    console.log('Resumed from memory cache state')
  }
})
```

## 1. Mini Program Lifecycle

A mini program goes through several states from launch to termination, and its behavior varies across these states.

### 1.1 Launch

From the user's perspective, a mini program can start in two ways:

- **Cold Start:**  
  When the mini program is opened for the first time, or after it has been completely destroyed, it needs to reload all resources — this is called a cold start.

- **Warm Start:**  
  When the user reopens a mini program that was previously opened but not destroyed, it simply resumes from the background — this is called a warm start.

> In lifecycle terminology, “launch” usually refers to a cold start, while warm start means “switching from background to foreground.”

### 1.2 Foreground and Background

When the mini program is running and visible to the user, it is in the **foreground** state.  
When the user leaves the mini program, it does not immediately shut down but instead enters the **background** state, where it may continue running briefly with limited API access.

**Common ways to enter the background:**

- Tapping the top-right capsule button to exit
- Swiping right from the left edge on iOS
- Pressing the Back key on Android
- Putting the app into background via Home or gestures
- Locking the screen while the mini program is active

When the user reopens the app and returns to the mini program, it re-enters the foreground state.

### 1.3 Termination

A mini program will be completely terminated when it remains unused for a long time or system resources are low.  
Once terminated, reopening it will trigger a **cold start**.

**Common termination scenarios:**

- The mini program has been in the background for over 10 minutes
- More than three mini programs are in the background — the earliest one will be destroyed

---

## 2. Page Behavior on Cold Start

When a mini program starts cold, the initial page depends on how it’s launched:

- **Scenario A:** If no path is provided in the launch parameters, the container will open the default `entryPagePath`.
- **Scenario B:** If a path is provided, the mini program will open that specific page directly.

---

## 3. Page Behavior on Warm Start

When warm-starting, the opened page depends on configuration:

- By default, the mini program opens the same first page as during cold start.
- If `cachePageStack: true` is configured, the previous browsing state (page stack) will be restored.

> Configuration location: `global.config.ts`

| **Property**   | **Type** | **Required** | **Description**                     |
| -------------- | -------- | ------------ | ----------------------------------- |
| cachePageStack | boolean  | No           | Whether to retain all pages on exit |

---

## 4. Manual Destruction

If you want the mini program to always start fresh (cold start every time), you can explicitly disable caching:

> Configuration location: `global.config.ts`

| **Property** | **Type** | **Required** | **Description**                    |
| ------------ | -------- | ------------ | ---------------------------------- |
| disableCache | boolean  | No           | Whether to destroy the app on exit |

---

## 5. Scenarios Without Memory Caching

In certain cases, the mini program will be **closed directly** without being stored in memory.  
This means that when reopened, it will **reload completely** instead of restoring from memory.

The following conditions trigger non-caching closure:

- **Non-production builds:**  
  Development or experience versions do not use memory caching.

- **White screen on exit:**  
  If the mini program UI is blank (white screen) when closing, it will be destroyed to avoid restoring an abnormal state.

- **Incomplete process during exit:**  
  If the app is still performing startup tasks or network requests, caching will be skipped.

- **Explicitly disabled cache:**  
  If `disableCache: true` is set in `global.config.ts`, the mini program will always be destroyed on exit.

- **Experience rating enabled:**  
  If user experience rating is active, caching is disabled for consistency.

- **Running inside a native tab bar:**  
  Mini programs running within native tab environments do not support memory caching.

---

## 6. Additional Notes

- The mini program only enters memory cache mode if all caching conditions are met.
- Cached mini programs resume faster when reopened, restoring the previous user state.
- If caching is disabled or skipped, the next launch will always be a cold start.

---

## 7. Frequently Asked Questions (FAQ)

### Q1: Why does my mini program reopen on the same page after I press the Android Back button?

That happens because the mini program was **cached in memory** when you exited.  
Reopening it restores the previous state instead of reloading from scratch.

**How to fix this:**

In your global configuration file `global.config.ts`, set:

```ts
disableCache: true
```

### Q2: I want to retain the last page I was working on in a mini program so I can use it again the next time I open it. How do I configure this?

Just make sure:

- `disableCache: true` is not set
- No direct closing is triggered (see Section 5 above)

By default, the mini program automatically enters memory caching mode, and the last page will be restored the next time it is opened.

### Q3: In what situations will the mini program not be cached?

- The mini program is in the development/experience version
- A white screen appears when closing
- Background tasks are not completed when launching
- The experience rating feature is enabled
- In the Native Tab bar
- It shows that `disableCache: true` is configured.