如何安装NativeStorage并导入？附示例及cordova_not_available错误求助

一、NativeStorage 安装步骤 #

NativeStorage 是 Cordova/Ionic 生态下的原生存储插件，安装分两种场景：

1. 纯 Cordova 项目 #

在项目根目录执行以下命令：

cordova plugin add cordova-plugin-nativestorage

如果安装失败，先移除旧插件再重新安装：

cordova plugin remove cordova-plugin-nativestorage
cordova plugin add cordova-plugin-nativestorage

2. Ionic + Angular 项目 #

除了安装 Cordova 插件，还需要安装 Ionic Native 的封装包（方便在 Angular 中依赖注入使用）：

# 安装 Cordova 插件
ionic cordova plugin add cordova-plugin-nativestorage
# 安装 Ionic Native 封装
npm install @ionic-native/native-storage

注意：Ionic 版本和 @ionic-native/native-storage 版本要匹配——Ionic 5 用 @ionic-native/native-storage@5.x，Ionic 6+ 用 @ionic-native/native-storage@6.x。

二、导入与使用示例 #

1. Ionic + Angular 项目 #

第一步：在 AppModule 中注册

打开 src/app/app.module.ts，导入并添加到 providers 数组：

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouteReuseStrategy } from '@angular/router';

import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
import { AppComponent } from './app.component';
import { AppRoutingModule } from './app-routing.module';

// 导入 NativeStorage
import { NativeStorage } from '@ionic-native/native-storage/ngx';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, IonicModule.forRoot(), AppRoutingModule],
  providers: [
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    NativeStorage // 添加到 providers
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

第二步：在组件中注入并使用

在需要使用的组件（比如 home.page.ts）中，通过 Platform.ready() 等待 Cordova 环境初始化完成后再调用 NativeStorage：

import { Component } from '@angular/core';
import { NativeStorage } from '@ionic-native/native-storage/ngx';
import { Platform } from '@ionic/angular';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
})
export class HomePage {

  constructor(
    private nativeStorage: NativeStorage,
    private platform: Platform
  ) {
    this.initStorage();
  }

  async initStorage() {
    // 必须等待平台就绪（Cordova 加载完成）
    await this.platform.ready();
    
    try {
      // 存储数据
      await this.nativeStorage.setItem('user_profile', {
        name: 'Alice',
        email: 'alice@example.com'
      });
      console.log('数据存储成功');

      // 读取数据
      const profile = await this.nativeStorage.getItem('user_profile');
      console.log('读取到的用户信息:', profile);
    } catch (error) {
      console.error('存储/读取失败:', error);
    }
  }
}

2. 纯 Cordova 项目 #

纯 Cordova 项目必须在 deviceready 事件触发后才能调用 NativeStorage（这是 Cordova 插件的核心规则）：

// 等待 Cordova 初始化完成
document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
  console.log('Cordova 环境已就绪');

  // 存储数据
  NativeStorage.setItem('app_settings', {
    theme: 'dark',
    notifications: true
  }, () => {
    console.log('设置存储成功');
    // 读取数据
    NativeStorage.getItem('app_settings', (data) => {
      console.log('读取到的设置:', data);
    }, (error) => {
      console.error('读取设置失败:', error);
    });
  }, (error) => {
    console.error('存储设置失败:', error);
  });
}

三、「Error storing item cordova_not_available」错误解决 #

这个错误的核心原因是 Cordova 环境未加载完成，或当前运行环境不支持 Cordova，下面是具体排查和解决步骤：

1. 确保在 Cordova 就绪后调用插件 #

这是最常见的原因！不管是 Ionic 还是纯 Cordova 项目，所有 Cordova 插件都必须在 deviceready（Ionic 中用 Platform.ready()）之后调用。

• 错误示例：直接在组件 constructor 中调用 NativeStorage，此时 Cordova 还没初始化
• 正确做法：用 await this.platform.ready()（Ionic）或 deviceready 事件（纯 Cordova）包裹所有 NativeStorage 调用

2. 不要在浏览器中测试 #

NativeStorage 是依赖原生设备的插件，浏览器环境（比如 ionic serve 或直接打开 index.html）没有 Cordova 运行环境，所以必然会报这个错。

• 正确测试方式：使用真机或模拟器运行项目：

  # Ionic 项目
  ionic cordova run android # 安卓真机/模拟器
  ionic cordova run ios     # iOS 真机/模拟器
  
  # 纯 Cordova 项目
  cordova run android
  cordova run ios
  

3. 检查插件是否正确安装 #

执行以下命令查看已安装的 Cordova 插件，确认 cordova-plugin-nativestorage 在列表中：

# Ionic 项目
ionic cordova plugin list

# 纯 Cordova 项目
cordova plugin list

如果没有，重新安装插件；如果已经存在但还是报错，尝试移除后重新添加：

cordova plugin remove cordova-plugin-nativestorage
cordova plugin add cordova-plugin-nativestorage

4. 清理项目缓存并重建 #

有时候缓存或平台配置问题会导致插件不生效，尝试以下步骤：

1. 移除现有平台：

   ionic cordova platform remove android
   # 或者 iOS
   ionic cordova platform remove ios
   

2. 重新添加平台：

   ionic cordova platform add android
   ionic cordova platform add ios
   

3. 重新构建项目：

   ionic cordova build android
   

5. 检查 Ionic Native 版本兼容性 #

如果是 Ionic 项目，确保 @ionic-native/native-storage 的版本和你的 Ionic 版本一致：

• Ionic 5 → @ionic-native/native-storage@5.x
• Ionic 6+ → @ionic-native/native-storage@6.x
  可以通过以下命令安装指定版本：

npm install @ionic-native/native-storage@6.0.0

内容的提问来源于stack exchange，提问作者Amjed Omar