# @amazon-devices/react-native-mmkv 中文文档 规范地址：https://npmcn.com/package/%40amazon-devices/react-native-mmkv/ 版本：1\.0\.12 npm 元数据更新时间：2026-10-29T18:38:43.590Z 中文译文更新时间：2026-11-06T03:28:53.259Z 软件包许可：See license in LICENSE 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40amazon-devices/react-native-mmkv 原文对照：https://npmcn.com/package/%40amazon-devices/react-native-mmkv/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：77.2 MB，221 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：react \*，react-native \* - 首次发布：2025-09-25T06:09:37.290Z - 最新版本发布：2026-10-29T18:38:43.348Z - 近 30 天下载量：5585（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：6（近 12 个月 4 个） ## 中文简介 React Industrial 的快捷键/值存储. ~30x比 AsyncStorage 更快! 在Android,iOS和Web上工作. ## 安装 ```sh npm install @amazon-devices/react-native-mmkv ``` 也可以使用：`pnpm add @amazon-devices/react-native-mmkv`、`yarn add @amazon-devices/react-native-mmkv`、`bun add @amazon-devices/react-native-mmkv` ## README [![react-native-mmkv](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/package/img/banner-light.png)](https://margelo.io/) # 缩略语:MMKV ### React Natural 的快捷键/值存储 . [![](https://img.shields.io/github/followers/mrousavy?label=Follow%20%40mrousavy&style=social)](https://github.com/mrousavy?tab=followers) [![](https://img.shields.io/twitter/follow/mrousavy?label=Follow%20%40mrousavy&style=social)](https://twitter.com/mrousavy) [![This library helped you? Consider sponsoring!](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/.github/funding-octocat.svg)](https://github.com/sponsors/mrousavy) - **缩略语:MMKV** 是WeChat开发的高效而小型的移动密钥值存储框架. 见 [10分/米克瓦](https://github.com/Tencent/MMKV) 更多信息 - **反应-内生-mmkv** 是允许您轻松使用的库 **缩略语:MMKV** 通过快速和直接的JS 绑定在本地的 C++ 库里. ## 特征 - **获取** 财务报告和审定财务报表 **设定** 字符串、布尔、数字和矩阵 - **完全同步** 电话,没有自动/等待, 没有承诺,没有桥. - **加密** 支持(安全存储) - **多个实例** 支持(将用户数据与全球数据分开) - **自定义存储位置** - **业绩好** 因为一切 **以 C++ 写** - **~30x 速度快于 AsyncStorage** - 用途 [**司法独立协会**](https://reactnative.dev/docs/the-new-architecture/landing-page#fast-javascriptnative-interfacing) 财务报告和审定财务报表 [**C++ 组合 涡轮摩多**](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/turbo-modules-xplat.md) 而不是"老"桥 - **iOS系统**, (中文(简体) ), **机器人** 财务报告和审定财务报表 **网页** 支助 - 易于使用 **反应钩** API 密码 ## 反应-内生-mmkv V3 > \[大 反应-内生-mmkv V3现为纯C++涡轮模具,并 **需要启用新架构**. (反应-内生 0.75+) > > - 如果您想要使用反应- native-mmkv 3.x.x,您需要启用应用程序中的新架构(参见 [应用的新建筑](https://github.com/reactwg/react-native-new-architecture/blob/main/docs/enable-apps.md)(中文(简体) ) > - 如果您尚不能使用新架构, 请暂时降级以反应- native- mmkv 2. x. ## 基准 [存储奔驰](https://github.com/mrousavy/StorageBenchmark) 比较流行的存储库, 通过读取存储值 1000 次 : [![](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/package/img/benchmark_1000_get.png)](https://github.com/mrousavy/StorageBenchmark) **MMKV 与其他存储库**: 从存储器读取值 1000 次 . 在iPhone 11 Pro上用毫秒测量,更下等. ## 安装 ### 原生反应 ```sh yarn add react-native-mmkv cd ios && pod install ``` ### 博览 ```sh npx expo install react-native-mmkv npx expo prebuild ``` ## 使用量 ### 创建新实例 要创建 MMKV 存储的新实例, 请使用 `MMKV` 建筑师。 建议您在整个应用程序中重新使用这个实例,而不是每次创建一个新的实例,所以 `export` 页:1 `storage` 对象. #### 默认 ```js import { MMKV } from 'react-native-mmkv' export const storage = new MMKV() ``` 使用默认的 MMKV 存储 ID () 创建新的存储实例`mmkv.default`) (中文(简体) ). #### App 组或扩展 如果您想要在您的应用程序和其他应用程序或应用程序扩展名之间共享 MMKV 数据, 请打开 `Info.plist` 创建 `AppGroup` 键,包含您的应用程序组值。 MMKV随后会自动将数据存储在应用组内,通过使用MMKV的多处理模式,从同一组中的其他应用或应用扩展读取并写入. 见 [配置应用组](https://developer.apple.com/documentation/xcode/configuring-app-groups)。 。 。 . #### 自定义 ```js import { MMKV, Mode } from 'react-native-mmkv' export const storage = new MMKV({ id: `user-${userId}-storage`, path: `${USER_DIRECTORY}/storage`, encryptionKey: 'hunter2', mode: Mode.MULTI_PROCESS }) ``` 这使用自定义的 MMKV 存储 ID 创建了新的存储实例 。 通过使用自定义存储 ID, 您的存储从默认的 MMKV 存储您的应用程序中分离 . 下列值可以配置 : - `id`MMKV案的身份证 如果你想使用多个实例,请使用不同的ID. 例如,您可以将全球应用程序的存储器和登录用户的存储器分开. (如果 `path` 或者说 `encryptionKey` 字段,否则默认为: `'mmkv.default'`(中文(简体) ) - `path`: MMKV实例的根道. 默认情况下, MMKV 在内部存储文件 `$(Documents)/mmkv/`您可以在 MMKV 初始化上自定义 MMKV 的根目录(文档 : [iOS系统](https://github.com/Tencent/MMKV/wiki/iOS_advance#customize-location) 编号 : [机器人](https://github.com/Tencent/MMKV/wiki/android_advance#customize-location)(中文(简体) ) - `encryptionKey`: MMKV实例的加密/解密密钥. 默认情况下,MMKV将所有的密钥值以纯文本存储在文件中,依靠iOS/Android的沙盒来确保文件被加密. 如果您担心信息泄露, 您可以选择加密 MMKV 。 (文件: [iOS系统](https://github.com/Tencent/MMKV/wiki/iOS_advance#encryption) 编号 : [机器人](https://github.com/Tencent/MMKV/wiki/android_advance#encryption)(中文(简体) ) - `mode`: MMKV 的处理行为 - 当设定为 `MULTI_PROCESS`,MMKV实例将假设数据可以从外部改变(例如App Clips,扩展或App Groups). ### 设定 ```js storage.set('user.name', 'Marc') storage.set('user.age', 21) storage.set('is-mmkv-fast-asf', true) ``` ### 获取 ```js const username = storage.getString('user.name') // 'Marc' const age = storage.getNumber('user.age') // 21 const isMmkvFastAsf = storage.getBoolean('is-mmkv-fast-asf') // true ``` ### 钩子 ```js const [username, setUsername] = useMMKVString('user.name') const [age, setAge] = useMMKVNumber('user.age') const [isMmkvFastAsf, setIsMmkvFastAf] = useMMKVBoolean('is-mmkv-fast-asf') ``` ### 密钥 ```js // checking if a specific key exists const hasUsername = storage.contains('user.name') // getting all keys const keys = storage.getAllKeys() // ['user.name', 'user.age', 'is-mmkv-fast-asf'] // delete a specific key + value storage.delete('user.name') // delete all keys storage.clearAll() ``` ### 对象 ```js const user = { username: 'Marc', age: 21 } // Serialize the object into a JSON string storage.set('user', JSON.stringify(user)) // Deserialize the JSON string into an object const jsonUser = storage.getString('user') // { 'username': 'Marc', 'age': 21 } const userObject = JSON.parse(jsonUser) ``` ### 加密 ```js // encrypt all data with a private key storage.recrypt('hunter2') // remove encryption storage.recrypt(undefined) ``` ### 缓冲 ```js const buffer = new ArrayBuffer(3) const dataWriter = new Uint8Array(buffer) dataWriter[0] = 1 dataWriter[1] = 100 dataWriter[2] = 255 storage.set('someToken', buffer) const buffer = storage.getBuffer('someToken') console.log(buffer) // [1, 100, 255] ``` ### 大小 ```js // get size of MMKV storage in bytes const size = storage.size if (size >= 4096) { // clean unused keys and clear memory cache storage.trim() } ``` ## 用 Jest 或 Vitest 进行测试 在使用 Jest 或 Vitest 测试时会自动使用被嘲笑的 MMKV 实例, 这样您就可以使用 `new MMKV()` 按照正常的测试。 参见 [软件包/实例/测试/MMKV.ts](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/package/example/test/MMKV.test.ts) 以杰斯特为例. ## 文档 - [钩子](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/HOOKS.md) - [价值变化](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/LISTENERS.md) - [从AsyncStorage 移动](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/MIGRATE_FROM_ASYNC_STORAGE.md) - [使用带有再加速度的 MMKV](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/WRAPPER_REDUX.md) - [使用带有后坐力的MMKV](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/WRAPPER_RECOIL.md) - [使用 MMKV 和 暴徒- 持久性存储器](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/WRAPPER_MOBX.md) - [使用 MMKV 有暴徒- 持久性](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/WRAPPER_MOBXPERSIST.md) - [使用带有 zustand 持久中件的 MMKV](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/WRAPPER_ZUSTAND_PERSIST_MIDDLEWARE.md) - [使用带Jotai的 MMKV](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/WRAPPER_JOTAI.md) - [使用 MMKV 反应- 平滑](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/docs/WRAPPER_REACT_QUERY.md) - [这个图书馆有什么不同 **反应-内生- mmkv- 存储**? 吗?](https://github.com/mrousavy/react-native-mmkv/issues/100#issuecomment-886477361) ## 本地存储和记忆存储(网络) 如果用户选择在浏览器中禁用localStorage,库会自动提供有限的内存存储作为替代. 然而,这种内存存储不会持续数据,用户如果刷新页面或关闭浏览器,可能会经历数据丢失. 为了优化用户体验,考虑在您的应用中执行一个合适的解决方案来解决这个情景. ## 限制 - 反应-内生-mmkv V3需要反应-内生-0.74或更高. - 反应- 内生- mmkv V3 需要 [新结构](https://reactnative.dev/docs/the-new-architecture/landing-page)/ TurboModules 启用 . - 由于反应-内生-mmkv使用JSI进行同步本地方法引用,远程调试(如与Chrome)已不再可能. 相反,你应该使用 [翻转](https://fbflipper.com/) 或者说 [反应 DevTools](https://react.dev/learn/react-developer-tools)。 。 。 . ## 一体化 ### 翻转 使用 [翻转-插件-反应-内置式-mmkv](https://github.com/muchobien/flipper-plugin-react-native-mmkv) 使用 Flipper 调试您的 MMKV 存储器 。 你也可以简单 `console.log` 一个MMKV的例子. ### 重装 使用 [反应-反应-内生- mmkv](https://www.npmjs.com/package/reactotron-react-native-mmkv) 以自动日志写入您的 MMKV 存储中. [如何用 Reactotron 设置此插件, 请查看文件 .](https://www.npmjs.com/package/reactotron-react-native-mmkv) ## 社区迪斯科尔 [**加入Margelo社区迪斯科尔**](https://discord.gg/6CSHz2qAvA) 以聊天方式讨论反应- native-mmkv 或其他 Margelo 库. ## 采用规模 提供了反应-内生- mmkv _一样_我在闲暇时间工作. 如果你正在将反应-原生-mmkv整合到生产应用中,请考虑 [资助这一项目](https://github.com/sponsors/mrousavy) 财务报告和审定财务报表 [联系我](mailto:me@mrousavy.com?subject=Adopting%20react-native-mmkv%20at%20scale) 以获得溢价企业支持,帮助解决问题,优先处理错误修正,请求特性,帮助整合反应-内置-mmkv,等等. ## 捐款 见 [贡献指南](https://npmcn.com/package/%40amazon-devices/react-native-mmkv/CONTRIBUTING.md) 学习如何为储存库和发展工作流程作出贡献. ## 许可证 麻省理工学院 ## 常见问题 ### @amazon-devices/react-native-mmkv 是什么？ React Industrial 的快捷键/值存储\. ~30x比 AsyncStorage 更快\! 在Android,iOS和Web上工作\. ### 如何安装 @amazon-devices/react-native-mmkv？ 在项目目录运行 npm install @amazon-devices/react-native-mmkv，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @amazon-devices/react-native-mmkv 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @amazon-devices/react-native-mmkv 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @amazon-devices/react-native-mmkv 可以商用吗？ @amazon-devices/react-native-mmkv 使用 See license in LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。 ### @amazon-devices/react-native-mmkv 的下载量有多少？ 根据 npm 官方下载统计，@amazon-devices/react-native-mmkv 在 2026/10/06 – 2026/11/04 这 30 天内被下载 5,585 次，日均约 186 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @amazon-devices/react-native-mmkv 还在维护吗？ 最新版本 1\.0\.12 发布于 2026/10/30（9 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 4 个；首次发布于 2025/09/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。