React Native Async Storage 完全指南：异步持久化 Key-Value 存储的安装、API 与本地 E2E 测试实战

数据库移动开发【免费下载链接】async-storageAn asynchronous, persistent, key-value storage system for React Native.项目地址https://gitcode.com/gh_mirrors/as/async-storage点击查看免费下载React Native Async Storagereact-native-async-storage/async-storage是 React Native 生态中最常用的异步、持久化、Key-Value 存储系统本指南以其在 packages/default-storage/README.md 中定义的项目定位、平台支持范围与本地 E2E 测试流程为核心骨架结合本仓库的源码、配置与测试文件展开讲解它的底层实现原理、完整 API 用法以及 Android/iOS 本地端到端测试的完整操作步骤。读完本文你将掌握该存储库的安装接入方式、全部核心 API 的调用规范、多平台实现差异并能在本地独立跑通两套官方 E2E 测试流程。一、项目定位什么是 React Native Async Storage官方 README 对该项目的定位非常明确An asynchronous, unencrypted, persistent, key-value storage system for React Native.即一个异步、非加密、持久化的 Key-Value 存储系统。这一定义包含三个关键语义异步Asynchronous所有读写操作均以 Promise 形式返回不阻塞 JS 线程底层 I/O 在原生线程或独立执行器上完成非加密Unencrypted数据以明文形式落盘因此不适合存放敏感信息如令牌、密码、密钥敏感数据应使用 Keychain / Keystore 等安全存储方案持久化Persistent数据在应用重启后依然存在存储位置由各平台原生实现决定。它面向的对象是 React Native 应用用于替代LocalStorage在 JS 侧提供统一的异步接口。项目以 monorepo 形式组织其中packages/default-storage就是默认的存储后端实现包即本仓库主包其版本信息、依赖关系和脚本定义可在 package.json 中查看当前版本 2.1.0peerDependencies 要求react-native 0.65。从 JS 层看入口在 src/index.ts默认导出AsyncStorage实例同时导出useAsyncStorageHook 与相关类型原生模块的 TurboModule 声明位于 src/NativeAsyncStorageModule.ts模块名称为RNCAsyncStorage。二、支持的平台README 明确列出该项目支持以下五个平台平台引入版本说明Android一直支持默认后端为 SQLite可选 Room/Next StorageiOS一直支持基于 Application Support 目录的 manifest 文件存储macOSv1.8.1 起复用 iOS 原生实现Webv1.9.0 起基于window.localStorage的降级实现Windowsv1.10.0 起基于 C/WinRT 的本地实现以上版本号取自 README 中的 release 链接文本。另外仓库根目录 README.md 还额外列出了 visionOSv1.22.0 起。各平台对应的原生代码与文档位置Androidpackages/default-storage/android/iOSpackages/default-storage/ios/RNCAsyncStorage.mmmacOSpackages/default-storage/macos/Webpackages/default-storage/src/AsyncStorage.tsWindowspackages/default-storage/windows/三、安装与链接README 的 Getting Started 一节将详细安装文档指向 packages/website/docs/Installation.md其中给出了三种安装方式# npm npm install react-native-async-storage/async-storage # Yarn yarn add react-native-async-storage/async-storage # Expo CLI npx expo install react-native-async-storage/async-storage安装后的链接Linking规则Android 与 iOS要求 React Native 0.60构建时由 CLI autolink 自动完成原生模块链接iOS 场景使用 CocoaPods 添加原生库可执行npx pod-installWindows要求 React Native Windows 0.63同样由 autolink 处理macOS要求 React Native macOS 0.63需要在macos/Podfile中设置platform :macos, 10.14然后安装 pods。在本仓库的 iOS 示例工程中Podfileexample/ios/Podfile通过pod RNCAsyncStorage, :path ../..以本地路径方式引入该库而 iOS 的 podspec 定义在 RNCAsyncStorage.podspec它依据RCT_NEW_ARCH_ENABLED环境变量决定是否启用新架构Fabric/TurboModule编译选项。安装后的快速自检安装完成后可以在任意组件中验证模块是否成功链接。若原生模块未找到JS 层会抛出明确错误。相关逻辑位于 src/AsyncStorage.native.ts当RCTAsyncStorage为 null 时会提示你依次尝试卸载重装重建、--reset-cache重启 packager、iOS 下执行pod install、确认package.json中声明了本依赖autolink 依赖它等。四、核心 API 与使用示例完整 API 文档位于 packages/website/docs/API.mdTS 类型定义在 src/types.ts。所有方法均支持Promise与**可选回调callback**两种风格。4.1 单值操作getItem / setItem / removeItem / mergeItemgetItem(key)读取指定 key 的字符串值不存在时返回null。存储对象时必须先JSON.stringify序列化读取时再JSON.parse反序列化getMyObject async () { try { const jsonValue await AsyncStorage.getItem(key) return jsonValue ! null ? JSON.parse(jsonValue) : null } catch(e) { // read error } console.log(Done.) }setItem(key, value)写入字符串值存在则覆盖不存在则新增setObjectValue async (value) { try { const jsonValue JSON.stringify(value) await AsyncStorage.setItem(key, jsonValue) } catch(e) { // save error } console.log(Done.) }removeItem(key)删除指定 keyremoveValue async () { try { await AsyncStorage.removeItem(MyApp_key) } catch(e) { // remove error } console.log(Done.) }mergeItem(key, value)将新值与已存储的序列化 JSON做深度合并新值字段覆盖旧值未涉及的字段保留嵌套对象递归合并const USER_1 { name: Tom, age: 20, traits: { hair: black, eyes: blue } } const USER_2 { name: Sarah, age: 21, hobby: cars, traits: { eyes: green } } mergeUsers async () { await AsyncStorage.setItem(MyApp_user, JSON.stringify(USER_1)) await AsyncStorage.mergeItem(MyApp_user, JSON.stringify(USER_2)) const currentUser await AsyncStorage.getItem(MyApp_user) // 结果{ name: Sarah, age: 21, hobby: cars, traits: { eyes: green, hair: black } } }4.2 批量操作multiGet / multiSet / multiMerge / multiRemove / getAllKeys / clear批量 API 适合一次性处理大量数据由原生层批量优化且只通过一个回调返回全部结果// multiGet批量读取返回 [key, value] 数组 values await AsyncStorage.multiGet([MyApp_user, MyApp_key]) // 输出示例[ [MyApp_user, myUserValue], [MyApp_key, myKeyValue] ] // multiSet批量写入 await AsyncStorage.multiSet([[MyApp_user, value_1], [MyApp_key, value_2]]) // multiRemove批量删除 await AsyncStorage.multiRemove([MyApp_USER_1, MyApp_USER_2]) // multiMerge批量合并假设均为序列化 JSON await AsyncStorage.multiMerge(multiMerge) // getAllKeys获取当前 App 已知的全部 key keys await AsyncStorage.getAllKeys() // clear清空整个 AsyncStorage所有调用方、库的数据慎用 await AsyncStorage.clear()注意clear会删除 App 内所有使用者写入的数据官方文档与源码注释都建议优先使用removeItem/multiRemove只清理自己的 key。4.3 React Hooks 风格useAsyncStoragesrc/hooks.ts 提供了useAsyncStorage(key)返回绑定好 key 的getItem / setItem / mergeItem / removeItem方法适合函数组件内使用import React, { useState, useEffect } from react; import { View, Text, TouchableOpacity } from react-native; import { useAsyncStorage } from react-native-async-storage/async-storage; export default function App() { const [value, setValue] useState(value); const { getItem, setItem } useAsyncStorage(storage_key); const readItemFromStorage async () { const item await getItem(); setValue(item); }; const writeItemToStorage async newValue { await setItem(newValue); setValue(newValue); }; useEffect(() { readItemFromStorage(); }, []); return ( View style{{ margin: 40 }} TextCurrent value: {value}/Text TouchableOpacity onPress{() writeItemToStorage(Math.random().toString(36).substr(2, 5))} TextUpdate value/Text /TouchableOpacity /View ); }重启 App 后最后一次写入的值仍会被读取出来——这正是持久化语义的直观体现。4.4 入参校验与常见报错JS 层在调用原生模块前会做输入校验规则包括key 必须是字符串否则打印警告value 不能为null/undefined否则抛出错误提示改用removeItem删除value 若非字符串会打印警告提示先序列化multiSet的第一参数必须是[key, value]数组的数组否则抛出Expected array of key-value pairs错误。E2E 测试用例中example/examples/tests.ts也覆盖了“重复 set 覆盖”、“remove 后读取为 null”、“merge 保留旧字段并叠加新字段”、“merge 空对象不改变已有数据”等行为可作为理解 API 语义的参考。五、各平台底层实现原理5.1 AndroidSQLite传统后端与 RoomNext Storage传统后端位于 AsyncStorageModule.java基于ReactDatabaseSupplierReactDatabaseSupplier.java管理的 SQLite 数据库数据库文件名为RKStorage表名为catalystLocalStorage含keyTEXT PRIMARY KEY与valueTEXT NOT NULL两列单次 SQL 查询的 key 数量上限MAX_SQL_KEYS 999受 SQLite 变量数限制超量时自动分批multiSet使用INSERT OR REPLACE在单个事务内批量写入数据库默认大小上限为 6MBBuildConfig.AsyncStorage_db_size防止数据膨胀损坏磁盘缓存所有读写通过SerialExecutor串行化执行保证并发安全。新架构Next Storage后端位于 next/StorageModule.kt 与 next/StorageSupplier.kt改用Room实现数据库名AsyncStorage、表名Storage、版本 2首次启用时通过Migration(1, 2)将旧catalystLocalStorage表数据迁移到新表StorageSupplier.kt并把key列修正为 NOT NULL所有操作通过 Kotlin 协程在Dispatchers.IO CoroutineName(AsyncStorageScope)作用域执行mergeValues内部使用JSONObject完成合并逻辑。5.2 iOS / macOSmanifest 文件存储iOS 原生实现位于 ios/RNCAsyncStorage.mm数据目录名为RCTAsyncLocalStorage_V1位于 Application Support 目录下并通过NSURLIsExcludedFromBackupKey将其排除在 iCloud/备份之外RNCAsyncStorage.mm小值≤ 1024 字节常量RCTInlineValueThreshold直接内联写入manifest.json大值以独立文件存储兼顾读取性能兼容旧目录RNCAsyncLocalStorage_V1与 Expo 的RCTAsyncLocalStorage数据迁移。macOS 复用同一套实现packages/default-storage/macos/。5.3 WeblocalStorage 降级实现Web 平台实现位于 src/AsyncStorage.ts直接基于window.localStorage封装所有方法均返回 PromisemergeItem通过JSON.parse 递归合并实现并且显式处理了concatArrays与ignoreUndefined合并选项。它不依赖任何原生模块因此无法在纯 Web 环境运行时直接参与原生 E2E。5.4 WindowsC/WinRT 原生实现Windows 侧实现位于packages/default-storage/windows/核心文件为 windows/code/DBStorage.cpp由react-native-windows的 autolink 集成。六、本地运行 E2E 测试官方流程README 给出了 Android 与 iOS 两套完整的本地 E2E 流程。E2E 测试基于WebdriverIO Appium驱动真实模拟器中的示例 App通过 UI 元素断言存储功能行为测试用例定义在 example/tests/asyncstorage.spec.ts。6.1 Android E2E前提创建并启动带 Play services、API level 29 的 Android 模拟器对应 example/tests/android.conf.ts 中appium:automationName: UiAutomator2的驱动要求。执行三条命令yarn bundle:android yarn build:e2e:android yarn test:e2e:android三条命令分别对应 scripts/android_e2e.sh 中的三个动作bundlereact-native bundle --entry-file index.ts --platform android --bundle-output example/index.android.jsbundle --dev false打包 JS bundlebuild在example/android下执行./gradlew assembleRelease -PAsyncStorage_useNextStoragefalse --max-workers 2构建 release APK注意此处显式关闭了 Next Storage即测试传统 SQLite 后端testwdio run example/__tests__/android.conf.ts运行 WebdriverIO 测试套件。测试产物 APK 路径为example/android/app/build/outputs/apk/release/app-release.apkAppium 服务在本地127.0.0.1:4723启动测试用例会等待functional-view元素出现后逐个校验tests.ts中定义的测试组Should store value、Should clear item、Should merge items 等均显示Pass并额外运行一遍设置 native delegate 后的对照测试。6.2 iOS E2E前提创建并启动 iPhone 14 模拟器系统版本 iOS 16.4对应 example/tests/ios.conf.ts 中的platformVersion: 16.4、automationName: XCUITest。执行四条命令yarn bundle:ios pod install --project-directoryexample/ios yarn build:e2e:ios yarn test:e2e:ios其中pod install用于在示例工程 example/ios 安装 CocoaPods 依赖build动作通过xcodebuild -workspace example/ios/AsyncStorageExample.xcworkspace -scheme ReactTestApp -configuration Release -sdk iphonesimulator构建模拟器包见 scripts/ios_e2e.sh测试通过wdio run example/__tests__/ios.conf.ts驱动被测 App 位于example/ios/build/Build/Products/Release-iphonesimulator/ReactTestApp.app。6.3 macOS / Web / Windows 的补充仓库还提供了 macOS 的 E2E 脚本 scripts/macos_e2e.sh使用xcodebuild -sdk macosx并自动安装/启用 ccache 加速构建以及 package.json 中test:e2e:macos等对应脚本Web 与 Windows 平台则通过start:web、start:windows等脚本启动示例工程进行验证。七、Android 构建配置项gradle 属性通过 android/config.gradle 可以精确控制 Android 端的构建行为。以下配置项均通过 Gradle Property 注入在gradle.properties或命令行-P传入属性默认值作用AsyncStorage_useNextStoragefalse是否启用 Room 实现的 Next Storage 后端需在首次创建数据库前开启以触发旧数据迁移AsyncStorage_db_size_in_MB6数据库大小上限MB用于保护用户设备不被数据膨胀填满磁盘缓存AsyncStorage_dedicatedExecutorfalse是否为传统后端启用独立的单线程 ExecutorExecutors.newSingleThreadExecutor()代替默认的AsyncTask.THREAD_POOL_EXECUTORAsyncStorage_kotlinVersion1.9.24覆盖 Kotlin 版本AsyncStorage_next_roomVersion2.6.1覆盖 Room 版本AsyncStorage_next_kspVersion由 Kotlin 版本映射覆盖 KSP 插件版本minSdkVersion/targetSdkVersion/compileSdkVersion23/32/32沿用宿主工程的 SDK 版本配置八、参与贡献与许可证README 说明了两条贡献约定先开 Issue 再提 PRPull requests are welcome但请先创建 issue 讨论你想改动的内容避免重复劳动或方向偏差详细的贡献指南见.github/CONTRIBUTING.md。本仓库采用MIT许可证LICENSE即允许自由使用、修改与再分发只需保留版权声明与许可声明。九、总结React Native Async Storage 以“异步、非加密、持久化”的 Key-Value 模型为 React Native 应用提供了跨 Android / iOS / macOS / Web / Windows 五端一致的数据持久化能力JS 层统一暴露 Promise/回调双风格 APIAndroid 侧由 SQLite传统与 RoomNext两种后端驱动iOS/macOS 侧采用 manifest 文件方案并自动排除备份Web 侧退化为 localStorage。掌握本文的 API 用法、配置项与本地 E2E 流程即可在真实模拟器环境中验证存储功能并放心地将其接入业务代码。赞分享数据库移动开发【免费下载链接】async-storageAn asynchronous, persistent, key-value storage system for React Native.项目地址https://gitcode.com/gh_mirrors/as/async-storage点击查看免费下载相关推荐React Native Async Storage 项目全解析异步持久化键值存储与本地 E2E 实战指南React Native Async Storage 项目全解析异步持久化键值存储与本地 E2E 实战指南 导读 本文以仓库根目录 README.md htt数据库移动开发Reactotron Async Storage调试React Native存储监控完全指南Reactotron Async Storage调试React Native存储监控完全指南 Reactotron是一个强大的React和React Nati开发工具uni-app 本地数据存储 API 完全指南uni.setStorage / getStorage 跨端 key-value 存储实战uni app 本地数据存储 API 完全指南uni.setStorage / getStorage 跨端 key value 存储实战 本篇指南聚焦 uni示例工程前端移动开发跨平台上一篇【限时免费】 释放Hunyuan3D-1的全部潜力一份基于官方推荐的微调指南下一篇LangChain.js 智能代理实战指南快速搭建能调用工具的 AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考