Expo SecureStore

For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.

expo-secure-store 提供了一种在设备本地加密并安全存储键值对的方法。每个 Expo 项目都有各自独立的存储系统，无法访问其他 Expo 项目的存储。

底层平台可能会拒绝较大的负载。历史上，某些 iOS 版本会拒绝大约 2048 字节以上的值。Expo 不会强制限制，因此如果你计划存储非常大的字符串，请确保处理原生错误。

由于缺少 NSFaceIDUsageDescription 键，当可用生物识别认证时，Expo Go 中不支持 requireAuthentication 选项。

安装

If you are installing this in an existing React Native app, make sure to install expo in your project.

在 app config 中配置

如果你在项目中使用 config plugins（Continuous Native Generation (CNG)），可以使用其内置的 config plugin 来配置 expo-secure-store。该插件允许你配置一些无法在运行时设置、且需要重新构建新的应用二进制文件才会生效的属性。如果你的应用没有使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

{
  "expo": {
    "plugins": [
      [
        "expo-secure-store",
        {
          "configureAndroidBackup": true,
          "faceIDPermission": "允许 $(PRODUCT_NAME) 访问你的 Face ID 生物识别数据。"
        }
      ]
    ]
  }
}

Configurable properties

<key>NSFaceIDUsageDescription</key>
<string>允许 $(PRODUCT_NAME) 访问你的 Face ID 生物识别数据。</string>

平台值存储

Android

在 Android 上，值存储在 SharedPreferences 中，并使用 Android 的 Keystore 系统进行加密。

iOS

在 iOS 上，值通过 keychain services 以 kSecClassGenericPassword 的形式存储。由于 iOS Keychain 的底层特性，使用 expo-secure-store 存储的数据在应用被卸载后，如果使用相同的 bundle ID 重新安装，数据仍会保留。 这是 iOS Keychain 系统的预期行为，在设计应用的数据处理方式时应考虑到这一点。iOS 还提供了额外选项，可以设置值的 kSecAttrAccessible 属性，用于控制该值何时可被读取。

数据持久性

expo-secure-store 的设计目标是在应用重启和更新之间提供持久的数据存储方案。然而，不应将其作为不可替代、关键数据的唯一真实来源。

• 在 Android 上： 使用 expo-secure-store 保存的数据在应用卸载后不会被保留。
• 在 iOS 上： 如果应用使用相同的 bundle ID 重新安装，使用 expo-secure-store 保存的数据会在应用卸载后继续保留。这是由 iOS Keychain 管理已存储凭据的方式决定的。请记住，这并不能得到保证，你也不应依赖这一实现细节。

此外，任何通过将 requireAuthentication 选项设为 true 保护的数据，如果用户的生物识别设置发生变化，例如添加了新的指纹，都将变得无法访问。

免除加密提示

Apple App Store Connect 会提示你选择应用所实现的加密算法类型。这被称为 Export Compliance Information。在发布应用或提交 TestFlight 时会出现此提示。

使用 expo-secure-store 时，你可以在 app config 中将 ios.config.usesNonExemptEncryption 属性设置为 false：

{
  "expo": {
    "ios": {
      "config": {
        "usesNonExemptEncryption": false
      }
      %%placeholder-start%%... %%placeholder-end%%
    }
  }
}

设置此属性会自动处理合规信息提示。

Android 自动备份

Android Auto Backup for Apps 会自动为目标平台为 Android 6.0（API level 23）或更高版本的应用备份用户数据。

Auto Backup 系统必须配置为排除 expo-secure-store 的共享首选项条目，因为在恢复备份后无法解密它们——应用在卸载时，其条目会从 Android Key Store 中删除。

如果你的应用没有任何自定义备份配置，expo-secure-store 会自动配置 Auto Backup 系统以忽略 expo-secure-store 数据。

如果你正在使用自己的 Auto Backup 配置，你应该在 sharedpref 域下排除 SecureStore，并在 config plugin 配置 中将 configureAndroidBackup 设置为 false。

<!--  Android 12 及更高版本的 Auto Backup 配置 -->
<data-extraction-rules>
  <cloud-backup>
    <include domain="sharedpref" path="."/>
    <exclude domain="sharedpref" path="SecureStore"/>
  </cloud-backup>
  <device-transfer>
    <include domain="sharedpref" path="."/>
    <exclude domain="sharedpref" path="SecureStore"/>
  </device-transfer>
</data-extraction-rules>

<!--  Android 11 及更低版本的 Auto Backup 配置 -->
<full-backup-content>
  <include domain="sharedpref" path="."/>
  <exclude domain="sharedpref" path="SecureStore"/>
</full-backup-content>

用法

import { useState } from 'react';
import { Text, View, StyleSheet, TextInput, Button } from 'react-native';
import * as SecureStore from 'expo-secure-store';

async function save(key, value) {
  await SecureStore.setItemAsync(key, value);
}

async function getValueFor(key) {
  let result = await SecureStore.getItemAsync(key);
  if (result) {
    alert("🔐 Here's your value 🔐 \n" + result);
  } else {
    alert('该键下没有存储任何值。');
  }
}

export default function App() {
  const [key, onChangeKey] = useState('Your key here');
  const [value, onChangeValue] = useState('Your value here');

  return (
    <View style={styles.container}>
      <Text style={styles.paragraph}>保存一项内容，然后稍后取回！</Text>
      {%%placeholder-start%%Add some TextInput components... %%placeholder-end%%}

      <TextInput
        style={styles.textInput}
        clearTextOnFocus
        onChangeText={text => onChangeKey(text)}
        value={key}
      />
      <TextInput
        style={styles.textInput}
        clearTextOnFocus
        onChangeText={text => onChangeValue(text)}
        value={value}
      />
      {}
      <Button
        title="保存此键/值对"
        onPress={() => {
          save(key, value);
          onChangeKey('Your key here');
          onChangeValue('Your value here');
        }}
      />
      <Text style={styles.paragraph}>🔐 输入你的键 🔐</Text>
      <TextInput
        style={styles.textInput}
        onSubmitEditing={event => {
          getValueFor(event.nativeEvent.text);
        }}
        placeholder="输入你想获取的值对应的键"
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    paddingTop: 10,
    backgroundColor: '#ecf0f1',
    padding: 8,
  },
  paragraph: {
    marginTop: 34,
    margin: 24,
    fontSize: 18,
    fontWeight: 'bold',
    textAlign: 'center',
  },
  textInput: {
    height: 35,
    borderColor: 'gray',
    borderWidth: 0.5,
    padding: 4,
  },
});

API

import * as SecureStore from 'expo-secure-store';

Constants

Methods

Types