企业官网建设流程全解析

Recoil 的 atom 状态默认只存在于内存中，应用重启后便会丢失。本文基于 react-native-mmkv 官方提供的persistAtom封装（见仓库内 docs/WRAPPER_RECOIL.md），讲解如何利用 Recoil 的 atom effects 机制，把任意 atom 的读写无缝落到 MMKV 这一同步、高性能的原生键值存储上。读完本文，你将掌握一套可复制、可扩展的 Recoil 持久化方案，并理解其背后每个 API 调用的含义与底层实现。

为什么需要 persistAtom：Recoil 与 MMKV 的互补

Recoil 的核心状态单元是 atom，它由key与default定义，运行时存放在内存中。一旦 App 被杀掉或重启，这些状态就全部丢失。常见的做法是把状态序列化后写入磁盘，并在启动时恢复——而 react-native-mmkv 恰好是这一场景的最佳载体：

• 完全同步 API：getString、set、remove都是同步调用，没有 Promise、没有 Bridge，读取与写入即时返回（接口定义见 packages/react-native-mmkv/src/specs/MMKV.nitro.ts）；
• 原生 C++ 实现：底层由 Tencent MMKV 驱动，读写性能远高于 AsyncStorage 等异步方案；
• 多实例与加密支持：可以按业务拆分为多个存储实例，也可以对敏感数据启用 AES 加密。

Recoil 提供了一种官方的“副作用钩子”机制——atom effects。它允许你在 atom 初始化、变更、重置时执行自定义逻辑，persistAtom正是借助这一机制，把“恢复、写入、删除”三件事与 MMKV 一一对应起来。

官方 persistAtom 封装：完整代码

docs/WRAPPER_RECOIL.md给出的核心封装如下，它接收一个存储 key，返回一个 Recoil atom effect：

const persistAtom = (key) => ({ setSelf, onSet }) => { setSelf(() => { let data = storage.getString(key); if (data != null){ return JSON.parse(data); } else { return new DefaultValue(); } }); onSet((newValue, _, isReset) => { if (isReset) { storage.remove(key); } else { storage.set(key, JSON.stringify(newValue)); } }); };

使用前需先创建一个 MMKV 实例并导出复用，这也是官方推荐的做法（实例应贯穿整个 App 生命周期，避免反复创建）：

import { createMMKV } from 'react-native-mmkv'; export const storage = createMMKV();

createMMKV()不传参数时会使用默认存储 IDmmkv.default（默认值见 packages/react-native-mmkv/src/specs/MMKVFactory.nitro.ts 的defaultMMKVInstanceId）。在 Jest/Vitest 测试环境下，createMMKV会自动返回内存 Mock 实例，因此测试代码可以原样运行（见 packages/react-native-mmkv/src/createMMKV/createMMKV.ts 中isTest()分支）。

逐段拆解：persistAtom 的工作原理

这个封装虽短，但完整覆盖了持久化所需的全部生命周期，下面逐一说明每个回调的职责。

setSelf：初始化时从 MMKV 恢复状态

atom effect 的setSelf回调在 atom 首次初始化时执行，用来把外部存储中的值“注入”到 atom 内部：

setSelf(() => { let data = storage.getString(key); if (data != null){ return JSON.parse(data); } else { return new DefaultValue(); } });

• storage.getString(key)是 MMKV 的同步读取接口，若该 key 不存在则返回undefined（类型签名见 MMKV.nitro.ts）；
• 存在数据时，用JSON.parse把存储的 JSON 字符串还原成 JS 对象/数组/基本类型，交给setSelf作为 atom 的初始值；
• 不存在数据时返回new DefaultValue()——这是 Recoil 的特殊占位符，表示“使用 atom 定义里的default”，从而保证首次启动时状态回落到预期的默认值，而不是undefined。

onSet：状态变更时写回 MMKV

onSet在 atom 值被更新时触发，接收三个参数：新值newValue、旧值（本例用_忽略）以及isReset标志：

onSet((newValue, _, isReset) => { if (isReset) { storage.remove(key); } else { storage.set(key, JSON.stringify(newValue)); } });

• 普通更新：storage.set(key, JSON.stringify(newValue))先把新值序列化为 JSON 字符串，再同步写入 MMKV（set支持 string/number/boolean/ArrayBuffer，见 MMKV.nitro.ts）；
• 重置操作：当调用resetState或useRecoilState的 setter 传入DefaultValue时，isReset为true，此时直接storage.remove(key)删除对应记录——这样 MMKV 里不会残留“重置前的旧数据”，下次启动时setSelf会再次因找不到 key 而回落到默认值。

这个“写入走 set、重置走 remove”的对称设计，保证了内存状态与磁盘存储在任何时刻都保持一致。

实际使用：把 persistAtom 挂载到 atom

persistAtom 返回的是标准的 atom effect，将它放进 atom 的 effects 数组即可启用持久化（新版本 Recoil 使用effects，早期版本为effects_UNSTABLE）：

import { atom, DefaultValue } from 'recoil'; const userAtom = atom({ key: 'user', default: null, effects: [persistAtom('user')], });

之后正常使用useRecoilState(userAtom)/useRecoilValue(userAtom)：

const [user, setUser] = useRecoilState(userAtom); // 写入：setUser 触发 onSet，数据自动 JSON 序列化后落入 MMKV setUser({ name: 'Marc', age: 21 }); // 重置：触发 isReset 分支，MMKV 中对应 key 被删除 resetUser();

要点说明：

• key参数（如'user'）同时充当 Recoil atom 的标识与 MMKV 的存储键，务必保持唯一；
• default值只在 MMKV 无对应数据时生效，二者应保持类型一致；
• 由于底层是同步调用，写入完成后立即重启 App，数据也能完整恢复，不存在异步竞态窗口。

深入进阶：让方案更健壮、更贴合业务

JSON 序列化的类型边界

persistAtom 依赖JSON.stringify/JSON.parse往返传输数据，因此：

• 仅能持久化 JSON 可表达的值：对象、数组、字符串、数字、布尔值、null；
• undefined、Date、Map、Set、函数等会被JSON.stringify降级或丢弃，如需持久化这类值，应先在业务侧转换为可序列化形态；
• 若默认值本身是复杂嵌套结构，可考虑在setSelf中增加 try/catch 或版本号字段（migration），避免历史数据格式不兼容导致解析失败。

使用独立存储实例隔离业务数据

默认的storage与所有使用默认实例的业务共用同一个存储空间。若需要隔离（例如“用户数据”与“全局配置”分开、或需要独立加密），可以创建多个实例并分别封装：

const secureStorage = createMMKV({ id: 'secure-storage', encryptionKey: 'my-encryption-key!', encryptionType: 'AES-256', }); const persistAtomSecure = (key) => ({ setSelf, onSet }) => { // 同样逻辑，只是把 storage 换成 secureStorage };

MMKV 支持id、path、encryptionKey、encryptionType、mode、readOnly、compareBeforeSet等配置项，完整说明见 packages/react-native-mmkv/src/specs/MMKVFactory.nitro.ts 与仓库 README.md。

跨组件/跨进程同步

默认的 persistAtom 只在写入方触发onSet，其他组件不会自动感知 MMKV 文件被外部进程（如 App Clip、Widget、扩展）修改。若需要跨进程同步，可借助 MMKV 的addOnValueChangedListener（见 MMKV.nitro.ts）监听键变更，再手动setSelf刷新对应 atom。注意：Recoil 的 atom effect 中setSelf也可在后续任意时刻被调用（如收到外部变更通知时），这正是扩展该封装的切入点。

测试环境的行为差异

在 Jest/Vitest 下，createMMKV()返回 Mock 实例（createMockMMKV），持久化数据仅存在于测试进程内存中，因此上述封装可以原样进入单元测试，无需 mock Recoil 或 MMKV，见 createMMKV.ts 与 packages/react-native-mmkv/src/createMMKV/createMockMMKV.ts。

与其他状态库封装的对照

本仓库的 docs 目录下还提供了同类集成指南，可互相参考设计思路：

• docs/WRAPPER_JOTAI.md：基于 Jotai 的atomWithStorage封装；
• docs/WRAPPER_ZUSTAND_PERSIST_MIDDLEWARE.md：实现 zustand persist middleware 的StateStorage适配；
• docs/WRAPPER_REDUX.md 与 docs/WRAPPER_MOBX.md：redux-persist、mobx-persist 适配。

它们共同印证了一个事实：MMKV 的同步getString/set/removeAPI 是天然的“存储适配器”，无论上层是哪个状态管理库，只需把存储接口映射到这三个方法即可完成接入。

结语

persistAtom用不到 20 行代码，就为 Recoil 的 atom 补齐了“启动恢复、变更写入、重置删除”的完整持久化闭环。它以 Recoil 官方推荐的 atom effects 为骨架、以 MMKV 同步 API 为落点，让状态持久化变成可插拔、可测试、可复用的标准能力。在此基础上，你还可以按业务需要扩展出加密实例、多实例隔离、版本迁移与跨进程同步等能力——核心代码与完整配置项均可直接在 packages/react-native-mmkv 目录下查阅与验证。