react-native-mmkv

react-native-mmkv 是一个面向 React Native 的高性能、同步键值存储库，底层由 Nitro Modules（JSI）驱动腾讯的 MMKV C++ 引擎。本技能是一份聚焦参考，供 AI 编程助手在使用了 react-native-mmkv 的项目中作答，要求其使用该库真实存在的 API，而非虚构接口，并路由到对应的 references/*.md 参考文件。

心智模型

react-native-mmkv 是 React Native 的高性能同步键值存储库，由 Nitro Modules（JSI）驱动腾讯的 MMKV C++ 引擎，比 AsyncStorage 快约 30 倍。有三个容易踩坑的点：

一切都是同步的。没有 await，没有 Promise。storage.getString('key') 立即返回结果。这正是其意义所在——MMKV 对文件做内存映射，并在进程内读写。
它是键值存储，不是数据库。所有数据都缓存在内存中，总体积应保持在约 100 MB 以下；更大的数据集请使用 react-native-nitro-sqlite 或 WatermelonDB。没有固定存储上限，但如果过大将触发内存警告。
V4 是一次破坏性重写。构造函数由 new MMKV() 改为 createMMKV()，.delete() 改为 .remove()，且 react-native-nitro-modules 现在是必需的同级依赖。参见升级指南。

V4 要求 React Native 0.75+。它同时适用于新架构和旧架构（Nitro 向后兼容）。

路由表——问题到参考文件

在编写代码前，加载 references/ 中匹配的文件。每个参考文件均引用库中的真实 API。

用户询问内容 → 阅读文件：

创建 MMKV 实例、配置项（id、path、encryptionKey、mode、readOnly、compareBeforeSet）、createMMKV() 工厂 → references/create-instance.md
获取/设置值、所有数据类型（string、number、boolean、buffer、通过 JSON 的对象）、键管理（contains、getAllKeys、remove、clearAll）、大小、trim、importAllFrom → references/crud-operations.md
React hooks（useMMKVString、useMMKVNumber、useMMKVBoolean、useMMKVBuffer、useMMKVObject、useMMKV、useMMKVListener、useMMKVKeys）、响应式 UI → references/hooks.md
在 React 之外监听值变化、addOnValueChangedListener、清理监听器 → references/listeners.md
加密（encrypt、decrypt、recrypt）、AES-128 与 AES-256、encryptionKey 配置 → references/encryption.md
从 AsyncStorage 迁移、数据传输模式、完成标志 → references/migrate-from-async-storage.md
zustand persist 中间件、redux-persist、jotai atomWithMMKV、react-query persister、MobX → references/state-management.md
V4 升级、V3 的破坏性变更、new MMKV() → createMMKV()、.delete() → .remove() → references/upgrade-v4.md
存储大小限制、内存警告、何时改用数据库 → references/limits-and-gotchas.md

如果问题不匹配任何一行，先阅读 references/create-instance.md——大多数安装配置问题都从那里开始。

安装

npm install react-native-mmkv react-native-nitro-modules cd ios && pod install

Expo：

npx expo install react-native-mmkv react-native-nitro-modules npx expo prebuild

安装后需重新构建应用。无需额外的原生接线。

快速参考——完整的 MMKV 实例 API

import { createMMKV, existsMMKV, deleteMMKV } from 'react-native-mmkv'

const storage = createMMKV({ id: 'my-store' })

// 属性（只读） storage.id // string storage.length // 键的数量 storage.byteSize // 文件总字节数 storage.size // （已废弃——请使用 byteSize） storage.isReadOnly // boolean storage.isEncrypted // boolean

// 写入 storage.set('key', 'string' | 42 | true | arrayBuffer)

// 读取 storage.getString('key') // string | undefined storage.getNumber('key') // number | undefined storage.getBoolean('key') // boolean | undefined storage.getBuffer('key') // ArrayBuffer | undefined

// 键 storage.contains('key') // boolean storage.getAllKeys() // string[] storage.remove('key') // boolean （注意：V3 中为 .delete()） storage.clearAll() // void

// 加密 storage.encrypt('password') storage.encrypt('password', 'AES-256') storage.decrypt() storage.recrypt('newPassword' | undefined) // （已废弃——请使用 encrypt()/decrypt()）

// 维护 storage.trim() // 释放未使用空间 storage.importAllFrom(otherStorage) // 返回导入的数量

// 监听器 const sub = storage.addOnValueChangedListener((key) => { ... }) sub.remove()

// 静态辅助方法 existsMMKV('my-store') // boolean deleteMMKV('my-store') // boolean

测试

使用 Jest 或 Vitest 测试时会自动使用模拟的 MMKV 实例。在测试中正常使用 createMMKV() 即可——无需手动 mock。

验证技能已加载

合适的测试问题：

"如何用 MMKV 持久化 zustand 状态？" → 应生成使用 storage.set、storage.getString、storage.remove 的 StateStorage 适配器——而不是 AsyncStorage 的包装。

"如何从 AsyncStorage 迁移到 MMKV？" → 应展示带完成标志的批量复制模式，而不是直接替换。

"存储限制是多少？" → 应说明没有固定限制，但由于数据是内存映射的，应保持在约 100 MB 以下；更大的数据集请使用 SQLite。

参考文件

文件 → 描述：

create-instance.md → createMMKV() 工厂、所有配置项
crud-operations.md → 设置/获取所有类型、键管理、对象、buffer
hooks.md → 响应式使用 MMKV 的所有 React hooks
listeners.md → addOnValueChangedListener、清理
encryption.md → 加密/解密实例、AES 选项
migrate-from-async-storage.md → 从 AsyncStorage 的完整迁移模式
state-management.md → zustand、redux-persist、jotai、react-query、MobX
upgrade-v4.md → V3 → V4 破坏性变更与迁移
limits-and-gotchas.md → 存储限制、多进程、日志、常见陷阱

问题 → 参考文件映射

问题 → 参考文件 → 操作：

不知从何入手 → create-instance.md → 用 createMMKV() 创建实例
需要响应式 UI 更新 → hooks.md → 使用 useMMKVString / useMMKVObject 等
加密敏感数据 → encryption.md → 调用 storage.encrypt(key)
应用使用 AsyncStorage，想要切换 → migrate-from-async-storage.md → 批量迁移后替换调用
Zustand/Redux/Jotai 持久化 → state-management.md → 为你的状态库接入适配器
从 V3 升级到 V4 → upgrade-v4.md → new MMKV() → createMMKV()、.delete() → .remove()
存储增长过大 → limits-and-gotchas.md → trim 或迁移到 SQLite
多进程数据共享 → limits-and-gotchas.md → 设置 mode: 'multi-process'

适用场景与限制

适用场景：React Native 应用中需要高性能、同步的键值存取，例如缓存、偏好设置、小型持久化状态，以及配合 zustand、redux-persist、jotai、react-query、MobX 等状态管理库做持久化。限制：它是键值存储而非数据库，数据缓存在内存中，建议总体积控制在约 100 MB 以下，超大或复杂查询型数据集应改用 react-native-nitro-sqlite 或 WatermelonDB；V4 要求 React Native 0.75+，且相对 V3 存在破坏性变更需迁移。本技能资料未提供收费、价格或平台相关的信息。

技能介绍