react-native-mmkv

react-native-mmkv

为使用 react-native-mmkv 的项目中的 AI 编码助手提供的精简参考。请使用此库的真实 API 作答，而非编造 API，并根据问题查阅下方对应的 references/*.md 文件。

心智模型

react-native-mmkv 是一款面向 React Native 的高性能同步键值存储库，通过 Nitro Modules（JSI）使用腾讯的 MMKV C++ 引擎。它的速度约为 AsyncStorage 的 30 倍。

以下三点最容易让人困惑：

1. 所有操作都是同步的。 不使用 await，也不使用 Promise。storage.getString('key') 会立即返回值。这正是它的核心优势——MMKV 会将文件映射到内存中，并在进程内读写。
2. 它是键值存储，而不是数据库。 所有数据都会缓存在内存中。请将总大小控制在约 100 MB 以内；对于更大的数据集，请使用 react-native-nitro-sqlite 或 WatermelonDB。存储空间没有固定上限，但数据过大时会触发内存警告。
3. 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
获取/设置值、所有数据类型（字符串、数字、布尔值、缓冲区、通过 JSON 存储的对象）、键管理（contains、getAllKeys、remove、clearAll）、size、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 持久化中间件、redux-persist、jotai atomWithMMKV、react-query 持久化器、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' })

// Properties (read-only)
storage.id          // string
storage.length      // number of keys
storage.byteSize    // total file size in bytes
storage.size        // (deprecated — use byteSize)
storage.isReadOnly  // boolean
storage.isEncrypted // boolean

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

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

// Keys
storage.contains('key')    // boolean
storage.getAllKeys()        // string[]
storage.remove('key')      // boolean  (NOTE: was .delete() in V3)
storage.clearAll()         // void

// Encryption
storage.encrypt('password')
storage.encrypt('password', 'AES-256')
storage.decrypt()
storage.recrypt('newPassword' | undefined)  // (deprecated — use encrypt()/decrypt())

// Maintenance
storage.trim()                       // free unused space
storage.importAllFrom(otherStorage)  // returns count imported

// Listeners
const sub = storage.addOnValueChangedListener((key) => { ... })
sub.remove()

// Static helpers
existsMMKV('my-store')   // boolean
deleteMMKV('my-store')   // boolean

测试

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

验证技能是否已加载

适合测试的问题：

• “如何使用 MMKV 持久化 zustand 状态？” → 应生成使用 storage.set、storage.getString、storage.remove 的 StateStorage 适配器，而不是 AsyncStorage 包装器。
• “如何从 AsyncStorage 迁移到 MMKV？” → 应展示带有完成标记的批量复制模式，而不是直接替换。
• “存储上限是多少？” → 应说明没有固定上限，但数据采用内存映射，因此应控制在约 100 MB 以内；更大的数据集应使用 SQLite。

参考资料

文件	描述
create-instance.md	createMMKV() 工厂函数及所有配置选项
crud-operations.md	设置/获取所有类型、键管理、对象、缓冲区
hooks.md	用于响应式 MMKV 用法的所有 React 钩子
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	精简数据或迁移到 SQLite
多进程数据共享	limits-and-gotchas.md	设置 mode: 'multi-process'