在HarmonyOS 6应用开发中，用户时常在手机“设置”->“存储”->“应用详情”页面中发现，一个看似简单的应用竟占用了可观的存储空间，并被清晰地划分为“应用”、“数据”和“缓存”三个部分。用户可能会困惑：“缓存是什么？能不能清理？数据里又存了什么？” 而对于开发者而言，如何精确地获取、监控和管理自己应用所产生的这些存储数据，既是优化用户体验、满足系统合规性要求的关键，也是衡量应用性能与质量的重要指标。本文将深入解析HarmonyOS 6中应用存储空间管理的核心机制，并提供从查询统计到清理优化的完整实战指南。

一、功能设计：从用户困惑到开发者需求

在用户侧，存储空间管理直接关系到设备的使用体验。一个“数据”不断膨胀的应用会让用户感到不安，而无法有效清理的“缓存”则可能白白浪费宝贵的存储资源。

在开发者侧，我们需要一套清晰的方案来实现以下目标：

1. 透明化：让应用明确知晓自身在磁盘上的“ footprint ”。

2. 可管理：提供安全、合规的缓存清理与数据管理能力。

3. 可优化：基于存储数据分析，优化文件读写策略，减少不必要的空间占用。

核心API：

API/属性	说明
bundleManager.BundleStats	应用包存储统计信息对象
appSize	应用安装包本身的大小
dataSize	应用运行产生的数据总大小
cacheSize	应用产生的可清理缓存大小
bundleManager.getBundleStats()	获取指定应用的存储统计信息

二、核心原理：BundleStats 深度解析

HarmonyOS 通过 bundleManager.BundleStats对象来精确统计应用存储。理解其每个字段的含义及对应的物理路径，是进行有效管理的前提。

1. 应用 (appSize) - 只读的“基座”

• 含义：appSize表示应用安装文件本身所占用的空间（单位：字节）。这通常是指 HAP 包安装后，在系统指定目录中展开的文件总和。

• 统计路径：/data/storage/el1/bundle

• 开发者注意：此部分空间由系统管理，应用在运行时无法修改或删除此目录下的文件。它代表了应用的“静态”体积。

2. 缓存 (cacheSize) - 可再生的“临时工”

• 含义：cacheSize表示应用缓存文件的大小。缓存旨在提升应用性能（如图片缓存、临时下载文件），其内容在存储空间不足时可被系统自动清理，且不会影响应用核心功能。

• 统计路径：

  • /data/storage/${el1-el5}/base/cache

  • /data/storage/${el1-el5}/base/haps/${moduleName}/cache

• 开发者注意：${el1-el5}对应不同的加密等级，${moduleName}为模块名。应用应将自己生成的、可丢弃的临时文件存于此。这是开发者可以且应该主动管理的主要区域。

3. 数据 (dataSize) - 宝贵的“用户资产”

• 含义：dataSize表示应用文件存储的总大小，不包括上述的 appSize。它包含了用户数据、配置、数据库等需要持久化保存的核心信息。

• 统计路径：

  • 本地文件：/data/storage/${el1-el5}/base(注意：缓存目录是它的子目录，统计时已被排除)。

  • 分布式文件：/data/storage/el2/distributedfiles

  • 数据库文件：/data/storage/${el1-el5}/database

• 开发者注意：此部分数据是应用的“血肉”，清理需格外谨慎，必须由用户明确触发或在应用内提供安全的管理入口。

三、完整实战：存储查询与管理组件实现

1. 获取应用存储统计信息

首先，我们需要获取当前应用的存储详情。以下是一个封装的存储信息服务类：

// utils/StorageStatsUtil.ets
import { bundleManager } from '@kit.BundleManagerKit';
import { BusinessError } from '@ohos.base';

/**
 * 应用存储统计工具类
 */
export class StorageStatsUtil {
  /**
   * 获取当前应用的详细存储统计信息
   * @returns Promise<BundleStats> 存储统计对象
   */
  static async getCurrentAppStorageStats(): Promise<bundleManager.BundleStats> {
    try {
      // 获取当前应用自身的包名
      const ownBundleInfo: bundleManager.BundleInfo = await bundleManager.getBundleInfoForSelf(
        bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT
      );
      const ownBundleName: string = ownBundleInfo.name;

      // 获取当前应用的存储统计信息
      const stats: bundleManager.BundleStats = await bundleManager.getBundleStats(
        ownBundleName
      );

      console.info(`[StorageStats] 应用: ${this.bytesToSize(stats.appSize)}`);
      console.info(`[StorageStats] 数据: ${this.bytesToSize(stats.dataSize)}`);
      console.info(`[StorageStats] 缓存: ${this.bytesToSize(stats.cacheSize)}`);
      console.info(`[StorageStats] 总计: ${this.bytesToSize(stats.appSize + stats.dataSize + stats.cacheSize)}`);

      return stats;
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error(`[StorageStats] 获取存储信息失败: Code ${err.code}, ${err.message}`);
      throw new Error(`获取存储信息失败: ${err.message}`);
    }
  }

  /**
   * 监听应用存储变化（模拟轮询，实际可结合文件变化通知）
   * @param callback 回调函数
   * @param intervalMs 轮询间隔（毫秒），默认10秒
   * @returns 清除监听函数
   */
  static watchStorageChanges(
    callback: (stats: bundleManager.BundleStats) => void,
    intervalMs: number = 10000
  ): () => void {
    let isWatching: boolean = true;

    const checkStorage = async () => {
      if (!isWatching) return;

      try {
        const stats = await this.getCurrentAppStorageStats();
        callback(stats);
      } catch (error) {
        console.error(`[StorageStats] 轮询获取存储信息失败: ${error.message}`);
      }

      if (isWatching) {
        setTimeout(checkStorage, intervalMs);
      }
    };

    // 立即执行一次
    checkStorage();

    // 返回清理函数
    return () => {
      isWatching = false;
      console.info('[StorageStats] 已停止监听存储变化');
    };
  }

  /**
   * 将字节数转换为易读的格式（KB, MB, GB）
   * @param bytes 字节数
   * @returns 格式化后的字符串
   */
  static bytesToSize(bytes: number): string {
    if (bytes === 0) return '0 B';

    const k: number = 1024;
    const sizes: string[] = ['B', 'KB', 'MB', 'GB', 'TB'];
    const i: number = Math.floor(Math.log(bytes) / Math.log(k));

    // 保留两位小数
    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
  }

  /**
   * 获取详细的存储目录分析
   * @returns Promise<StorageDetail> 存储详情
   */
  static async getStorageDetail(): Promise<StorageDetail> {
    const stats = await this.getCurrentAppStorageStats();

    // 在实际项目中，这里可以遍历文件目录，获取更细粒度的分类大小
    // 例如：数据库大小、图片缓存大小、日志文件大小等
    // 此处返回基于统计信息的分析

    return {
      total: stats.appSize + stats.dataSize + stats.cacheSize,
      app: {
        size: stats.appSize,
        description: '应用安装文件，不可清理'
      },
      data: {
        size: stats.dataSize,
        description: '用户数据、配置和数据库',
        breakdown: {
          database: 0, // 可通过检查数据库目录计算
          preferences: 0, // 可通过检查配置文件计算
          userFiles: 0   // 剩余数据文件
        }
      },
      cache: {
        size: stats.cacheSize,
        description: '临时缓存文件，可安全清理',
        breakdown: {
          imageCache: 0,  // 图片缓存
          networkCache: 0, // 网络缓存
          tempFiles: 0     // 其他临时文件
        }
      }
    };
  }
}

// 存储详情接口
export interface StorageDetail {
  total: number;
  app: StorageCategory;
  data: DataCategory;
  cache: CacheCategory;
}

export interface StorageCategory {
  size: number;
  description: string;
}

export interface DataCategory extends StorageCategory {
  breakdown: {
    database: number;
    preferences: number;
    userFiles: number;
  };
}

export interface CacheCategory extends StorageCategory {
  breakdown: {
    imageCache: number;
    networkCache: number;
    tempFiles: number;
  };
}

2. 存储管理主界面组件

接下来，我们实现一个完整的存储管理界面，用于展示详情并提供清理功能。

// view/StorageManager.ets
import { StorageStatsUtil, StorageDetail } from '../utils/StorageStatsUtil';
import { bundleManager } from '@kit.BundleManagerKit';

@Component
export struct StorageManager {
  @State storageStats: bundleManager.BundleStats | null = null;
  @State storageDetail: StorageDetail | null = null;
  @State isLoading: boolean = true;
  @State cleaningCache: boolean = false;
  @State cleanResult: string = '';

  // 监听器清理函数
  private stopWatching: (() => void) | null = null;

  aboutToAppear() {
    this.loadStorageInfo();
    // 开始监听存储变化
    this.stopWatching = StorageStatsUtil.watchStorageChanges((stats) => {
      this.storageStats = stats;
      this.updateStorageDetail();
    }, 15000); // 每15秒更新一次
  }

  aboutToDisappear() {
    // 清理监听器
    if (this.stopWatching) {
      this.stopWatching();
      this.stopWatching = null;
    }
  }

  async loadStorageInfo() {
    this.isLoading = true;
    try {
      this.storageStats = await StorageStatsUtil.getCurrentAppStorageStats();
      this.storageDetail = await StorageStatsUtil.getStorageDetail();
    } catch (error) {
      console.error('加载存储信息失败:', error.message);
    } finally {
      this.isLoading = false;
    }
  }

  async updateStorageDetail() {
    if (this.storageStats) {
      this.storageDetail = await StorageStatsUtil.getStorageDetail();
    }
  }

  // 清理缓存
  async clearAppCache() {
    if (this.cleaningCache) return;

    this.cleaningCache = true;
    this.cleanResult = '';

    try {
      // 获取当前应用包名
      const ownBundleInfo = await bundleManager.getBundleInfoForSelf(
        bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT
      );

      // 调用清理缓存接口
      await bundleManager.cleanBundleCache(ownBundleInfo.name, (err: BusinessError) => {
        if (err) {
          console.error(`清理缓存失败: Code ${err.code}, ${err.message}`);
          this.cleanResult = `清理失败: ${err.message}`;
        } else {
          console.info('应用缓存清理成功');
          this.cleanResult = '缓存清理完成';
          // 重新加载存储信息
          setTimeout(() => this.loadStorageInfo(), 500);
        }
        this.cleaningCache = false;
      });

    } catch (error) {
      console.error('清理缓存过程异常:', error.message);
      this.cleanResult = `清理异常: ${error.message}`;
      this.cleaningCache = false;
    }
  }

  // 手动计算缓存目录大小（示例）
  async calculateCacheSizeManually(): Promise<number> {
    // 注意：实际遍历文件需要文件访问权限
    // 这里仅展示思路
    console.info('开始手动计算缓存大小...');
    // 实现遍历 /data/storage/el2/base/cache 等目录的逻辑
    return 0;
  }

  build() {
    Column({ space: 20 }) {
      // 标题
      Text('应用存储空间管理')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .width('100%')
        .textAlign(TextAlign.Center)
        .margin({ top: 30, bottom: 20 })

      if (this.isLoading) {
        // 加载状态
        Column() {
          LoadingProgress()
            .width(50)
            .height(50)
            .color(Color.Blue)
          Text('正在分析存储空间...')
            .fontSize(16)
            .margin({ top: 12 })
            .fontColor(Color.Gray)
        }
        .height(200)
        .width('100%')
        .justifyContent(FlexAlign.Center)
      } else if (this.storageStats && this.storageDetail) {
        // 存储概览卡片
        this.buildStorageOverviewCard()

        // 详细分类卡片
        this.buildStorageDetailCard()

        // 缓存管理卡片
        this.buildCacheManagementCard()

        // 数据管理提示
        this.buildDataManagementTip()
      } else {
        // 错误状态
        Column() {
          Image($r('app.media.ic_error'))
            .width(80)
            .height(80)
            .margin({ bottom: 16 })
          Text('获取存储信息失败')
            .fontSize(18)
            .fontColor(Color.Red)
            .margin({ bottom: 8 })
          Text('请检查存储权限或重启应用后重试')
            .fontSize(14)
            .fontColor(Color.Gray)
            .textAlign(TextAlign.Center)
          Button('重试')
            .margin({ top: 20 })
            .onClick(() => this.loadStorageInfo())
        }
        .width('100%')
        .padding(40)
        .justifyContent(FlexAlign.Center)
      }
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .backgroundColor('#F5F5F5')
  }

  @Builder
  buildStorageOverviewCard() {
    Card() {
      Column({ space: 16 }) {
        Row() {
          Text('存储空间概览')
            .fontSize(20)
            .fontWeight(FontWeight.Medium)
            .layoutWeight(1)
          Image($r('app.media.ic_storage'))
            .width(24)
            .height(24)
        }

        // 总大小进度条
        Column({ space: 8 }) {
          Row() {
            Text('已用空间')
              .fontSize(14)
              .fontColor(Color.Gray)
            Text(StorageStatsUtil.bytesToSize(this.storageStats!.appSize + this.storageStats!.dataSize + this.storageStats!.cacheSize))
              .fontSize(16)
              .fontWeight(FontWeight.Medium)
              .layoutWeight(1)
              .textAlign(TextAlign.End)
          }

          // 简易进度条
          Stack() {
            // 背景
            Column()
              .width('100%')
              .height(8)
              .backgroundColor('#E0E0E0')
              .borderRadius(4)

            // 进度 - 应用部分
            Column()
              .width(`${(this.storageStats!.appSize / (this.storageStats!.appSize + this.storageStats!.dataSize + this.storageStats!.cacheSize) * 100)}%`)
              .height(8)
              .backgroundColor('#4CAF50') // 绿色代表应用
              .borderRadius(4)

            // 进度 - 数据部分
            Column()
              .width(`${(this.storageStats!.dataSize / (this.storageStats!.appSize + this.storageStats!.dataSize + this.storageStats!.cacheSize) * 100)}%`)
              .height(8)
              .backgroundColor('#2196F3') // 蓝色代表数据
              .borderRadius(4)
              .margin({ left: `${(this.storageStats!.appSize / (this.storageStats!.appSize + this.storageStats!.dataSize + this.storageStats!.cacheSize) * 100)}%` })

            // 进度 - 缓存部分
            Column()
              .width(`${(this.storageStats!.cacheSize / (this.storageStats!.appSize + this.storageStats!.dataSize + this.storageStats!.cacheSize) * 100)}%`)
              .height(8)
              .backgroundColor('#FF9800') // 橙色代表缓存
              .borderRadius(4)
              .margin({ left: `${((this.storageStats!.appSize + this.storageStats!.dataSize) / (this.storageStats!.appSize + this.storageStats!.dataSize + this.storageStats!.cacheSize) * 100)}%` })
          }
        }

        // 分类统计
        Row({ space: 10 }) {
          Column() {
            Text('应用')
              .fontSize(12)
              .fontColor(Color.Gray)
            Text(StorageStatsUtil.bytesToSize(this.storageStats!.appSize))
              .fontSize(16)
              .fontWeight(FontWeight.Medium)
              .fontColor('#4CAF50')
          }
          .layoutWeight(1)
          .alignItems(HorizontalAlign.Center)

          Column() {
            Text('数据')
              .fontSize(12)
              .fontColor(Color.Gray)
            Text(StorageStatsUtil.bytesToSize(this.storageStats!.dataSize))
              .fontSize(16)
              .fontWeight(FontWeight.Medium)
              .fontColor('#2196F3')
          }
          .layoutWeight(1)
          .alignItems(HorizontalAlign.Center)

          Column() {
            Text('缓存')
              .fontSize(12)
              .fontColor(Color.Gray)
            Text(StorageStatsUtil.bytesToSize(this.storageStats!.cacheSize))
              .fontSize(16)
              .fontWeight(FontWeight.Medium)
              .fontColor('#FF9800')
          }
          .layoutWeight(1)
          .alignItems(HorizontalAlign.Center)
        }
      }
      .padding(20)
    }
    .width('100%')
    .backgroundColor(Color.White)
    .shadow({ radius: 8, color: '#1A000000', offsetX: 0, offsetY: 2 })
  }

  @Builder
  buildStorageDetailCard() {
    Card() {
      Column({ space: 12 }) {
        Text('存储详情分析')
          .fontSize(18)
          .fontWeight(FontWeight.Medium)
          .width('100%')

        // 应用存储
        Column({ space: 8 }) {
          Row() {
            Text('应用安装文件')
              .fontSize(14)
              .layoutWeight(1)
            Text(StorageStatsUtil.bytesToSize(this.storageStats!.appSize))
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
          }
          Text('系统目录，不可修改或清理')
            .fontSize(12)
            .fontColor(Color.Gray)
            .width('100%')
        }

        Divider()
          .margin({ vertical: 8 })

        // 用户数据
        Column({ space: 8 }) {
          Row() {
            Text('用户数据')
              .fontSize(14)
              .layoutWeight(1)
            Text(StorageStatsUtil.bytesToSize(this.storageStats!.dataSize))
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
          }
          Text('包含数据库、配置和用户文件，清理需谨慎')
            .fontSize(12)
            .fontColor(Color.Gray)
            .width('100%')
        }

        Divider()
          .margin({ vertical: 8 })

        // 缓存
        Column({ space: 8 }) {
          Row() {
            Text('缓存文件')
              .fontSize(14)
              .layoutWeight(1)
            Text(StorageStatsUtil.bytesToSize(this.storageStats!.cacheSize))
              .fontSize(14)
              .fontWeight(FontWeight.Medium)
          }
          Text('临时文件，清理可释放空间且不影响使用')
            .fontSize(12)
            .fontColor(Color.Gray)
            .width('100%')
        }
      }
      .padding(20)
    }
    .width('100%')
    .margin({ top: 12 })
    .backgroundColor(Color.White)
  }

  @Builder
  buildCacheManagementCard() {
    Card() {
      Column({ space: 16 }) {
        Text('缓存管理')
          .fontSize(18)
          .fontWeight(FontWeight.Medium)
          .width('100%')

        if (this.cleanResult) {
          Row() {
            Image($r(this.cleanResult.includes('失败') ? 'app.media.ic_warning' : 'app.media.ic_success'))
              .width(16)
              .height(16)
              .margin({ right: 8 })
            Text(this.cleanResult)
              .fontSize(14)
              .fontColor(this.cleanResult.includes('失败') ? Color.Red : '#4CAF50')
              .layoutWeight(1)
          }
          .width('100%')
          .padding(12)
          .backgroundColor(this.cleanResult.includes('失败') ? '#FFEBEE' : '#E8F5E9')
          .borderRadius(8)
        }

        Button(this.cleaningCache ? '清理中...' : '立即清理缓存')
          .width('100%')
          .height(44)
          .fontSize(16)
          .enabled(!this.cleaningCache && this.storageStats!.cacheSize > 0)
          .backgroundColor(this.storageStats!.cacheSize > 0 ? '#FF9800' : Color.Gray)
          .onClick(() => this.clearAppCache())

        if (this.storageStats!.cacheSize === 0) {
          Text('暂无缓存可清理')
            .fontSize(12)
            .fontColor(Color.Gray)
            .width('100%')
            .textAlign(TextAlign.Center)
        }
      }
      .padding(20)
    }
    .width('100%')
    .margin({ top: 12 })
    .backgroundColor(Color.White)
  }

  @Builder
  buildDataManagementTip() {
    Column({ space: 12 }) {
      Text('数据管理提示')
        .fontSize(16)
        .fontWeight(FontWeight.Medium)
        .width('100%')
        .textAlign(TextAlign.Start)

      Text('用户数据（如聊天记录、收藏内容、个人设置）通常保存在“数据”部分。如需管理，请在应用内的相应功能页面进行操作，以确保数据安全。')
        .fontSize(13)
        .fontColor(Color.Gray)
        .lineHeight(20)
    }
    .width('100%')
    .padding(20)
    .margin({ top: 12 })
    .backgroundColor(Color.White)
    .borderRadius(12)
  }
}

3. 应用主界面集成示例

最后，我们将存储管理功能集成到应用的主设置页面中。

// MainSettings.ets
import { StorageManager } from '../view/StorageManager';

@Entry
@Component
struct MainSettings {
  @State currentPage: string = 'home';

  build() {
    Column() {
      // 顶部导航
      Row() {
        if (this.currentPage !== 'home') {
          Button()
            .icon($r('app.media.ic_back'))
            .onClick(() => {
              this.currentPage = 'home';
            })
            .margin({ right: 12 })
        }

        Text(this.currentPage === 'home' ? '设置' : '存储空间')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .layoutWeight(1)
      }
      .width('100%')
      .padding({ left: 20, right: 20, top: 12, bottom: 12 })
      .backgroundColor(Color.White)
      .border({ width: { bottom: 1 }, color: '#EEEEEE' })

      // 页面内容
      if (this.currentPage === 'home') {
        this.buildHomePage();
      } else if (this.currentPage === 'storage') {
        StorageManager();
      }
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }

  @Builder
  buildHomePage() {
    List({ space: 1 }) {
      ListItem() {
        Row() {
          Image($r('app.media.ic_storage'))
            .width(24)
            .height(24)
            .margin({ right: 16 })
          Text('存储空间')
            .fontSize(16)
            .layoutWeight(1)
          Image($r('app.media.ic_arrow_right'))
            .width(16)
            .height(16)
        }
        .padding(20)
        .onClick(() => {
          this.currentPage = 'storage';
        })
      }

      // 其他设置项...
      ListItem() {
        Row() {
          Image($r('app.media.ic_notification'))
            .width(24)
            .height(24)
            .margin({ right: 16 })
          Text('通知管理')
            .fontSize(16)
            .layoutWeight(1)
        }
        .padding(20)
      }

      ListItem() {
        Row() {
          Image($r('app.media.ic_privacy'))
            .width(24)
            .height(24)
            .margin({ right: 16 })
          Text('隐私设置')
            .fontSize(16)
            .layoutWeight(1)
        }
        .padding(20)
      }
    }
    .width('100%')
    .layoutWeight(1)
  }
}

四、高级优化与最佳实践

1. 缓存治理策略

为了避免缓存无限制增长，应在应用层面实现智能的缓存管理：

// utils/CacheManager.ets
import { fileIo } from '@kit.CoreFileKit';

export class CacheManager {
  private static readonly MAX_CACHE_SIZE = 100 * 1024 * 1024; // 100MB
  private static readonly CACHE_RETENTION_DAYS = 7; // 缓存保留7天

  /**
   * 智能清理缓存
   * 当缓存超过阈值时，按文件最后访问时间清理最旧的文件
   */
  static async smartCleanCache(): Promise<{ deletedCount: number, freedSize: number }> {
    const result = { deletedCount: 0, freedSize: 0 };
    const cacheDirs = [
      '/data/storage/el2/base/cache',
      // 添加其他缓存目录...
    ];

    for (const dir of cacheDirs) {
      try {
        if (fileIo.accessSync(dir)) {
          const dirStats = await this.scanCacheDirectory(dir);
          const totalSize = dirStats.reduce((sum, file) => sum + file.size, 0);

          if (totalSize > this.MAX_CACHE_SIZE) {
            // 按最后修改时间排序，优先删除最旧的文件
            dirStats.sort((a, b) => a.lastModified - b.lastModified);

            let sizeToDelete = totalSize - this.MAX_CACHE_SIZE * 0.7; // 清理到阈值的70%
            let currentDeleted = 0;

            for (const file of dirStats) {
              if (currentDeleted >= sizeToDelete) break;

              try {
                fileIo.unlinkSync(file.path);
                result.deletedCount++;
                result.freedSize += file.size;
                currentDeleted += file.size;
              } catch (error) {
                console.warn(`无法删除文件 ${file.path}: ${error.message}`);
              }
            }
          }
        }
      } catch (error) {
        console.error(`扫描目录 ${dir} 失败: ${error.message}`);
      }
    }

    console.info(`智能清理完成: 删除 ${result.deletedCount} 个文件，释放 ${StorageStatsUtil.bytesToSize(result.freedSize)}`);
    return result;
  }

  /**
   * 扫描缓存目录，获取文件信息
   */
  private static async scanCacheDirectory(dirPath: string): Promise<CacheFileInfo[]> {
    const files: CacheFileInfo[] = [];
    // 实现文件遍历逻辑...
    return files;
  }
}

interface CacheFileInfo {
  path: string;
  size: number;
  lastModified: number;
}

2. 存储监控与预警

在应用启动或定期检查存储情况，避免存储空间不足导致功能异常：

// utils/StorageMonitor.ets
import { deviceInfo } from '@kit.DeviceInfoKit';

export class StorageMonitor {
  /**
   * 检查设备存储空间状态
   */
  static async checkStorageHealth(): Promise<StorageHealthStatus> {
    const status: StorageHealthStatus = {
      isHealthy: true,
      warnings: [],
      totalSpace: 0,
      freeSpace: 0,
      appUsage: 0
    };

    try {
      // 获取设备总存储和可用空间
      const diskStats = await deviceInfo.getDiskInfo();
      status.totalSpace = diskStats.totalSpace;
      status.freeSpace = diskStats.freeSpace;

      // 获取当前应用使用空间
      const bundleStats = await StorageStatsUtil.getCurrentAppStorageStats();
      status.appUsage = bundleStats.appSize + bundleStats.dataSize + bundleStats.cacheSize;

      // 检查条件
      if (status.freeSpace < 100 * 1024 * 1024) { // 少于100MB
        status.isHealthy = false;
        status.warnings.push('设备存储空间严重不足，可能影响应用正常使用');
      } else if (status.freeSpace < 500 * 1024 * 1024) { // 少于500MB
        status.warnings.push('设备存储空间较低，建议清理不必要的文件');
      }

      // 检查应用自身缓存是否过大
      if (bundleStats.cacheSize > 200 * 1024 * 1024) { // 缓存超过200MB
        status.warnings.push('应用缓存文件较大，可以考虑清理');
      }

    } catch (error) {
      console.error('检查存储健康状态失败:', error.message);
    }

    return status;
  }

  /**
   * 初始化存储监控
   */
  static initializeMonitoring() {
    // 应用启动时检查
    this.checkStorageHealth().then(status => {
      if (!status.isHealthy) {
        console.warn('存储空间不健康:', status.warnings);
        // 可以在这里触发用户提示
      }
    });

    // 每30分钟检查一次
    setInterval(() => {
      this.checkStorageHealth();
    }, 30 * 60 * 1000);
  }
}

interface StorageHealthStatus {
  isHealthy: boolean;
  warnings: string[];
  totalSpace: number;
  freeSpace: number;
  appUsage: number;
}

五、总结

通过本文的详细解析与实战，我们完整掌握了HarmonyOS 6中应用存储空间的管理机制：

要点	核心实现与说明
存储统计​	通过 bundleManager.getBundleStats()获取精确的 appSize, dataSize, cacheSize
路径理解​	明确三类存储对应的物理路径，是进行有效文件操作的基础
缓存管理​	使用 bundleManager.cleanBundleCache()或自行遍历清理缓存目录，是安全释放空间的主要手段
数据管理​	用户数据（dataSize）的清理需格外谨慎，应在应用内提供明确的管理入口
监控预警​	定期检查设备及应用自身的存储状态，可预防功能异常，提升用户体验
权限与安全​	管理存储空间需要相应的文件访问权限，清理操作应通过系统API或安全控件触发

关键收获：

1. 透明化是信任的基础：向用户清晰地展示应用存储的构成（应用、数据、缓存），能有效减少用户的困惑与担忧。

2. 主动管理优于被动清理：实现智能的缓存治理策略（如大小限制、过期清理），比等待用户发现空间不足后再提供清理入口体验更好。

3. 区分“可丢弃”与“重要”数据：严格区分缓存文件与用户数据，对缓存可积极清理，对用户数据则需提供安全、可控的管理方式。

通过将本文的存储查询、分析、清理与监控能力集成到您的应用中，不仅可以打造更专业、更可信赖的应用形象，更能从根本上优化应用的存储行为，为用户带来清爽、流畅的使用体验。