本规范面向HarmonyOS应用开发者，用于应用沙箱目录选择、存储占用管理、文件生命周期管理及常见存储问题排查。 适用范围包括应用自身、小程序容器、插件和第三方SDK产生的数据，宿主应用应对其沙箱内全部数据的存储合规性负责。
适用设备：手机、平板、PC/2in1。
应用形态适用性：鸿蒙应用（不含元服务）。
术语 | 定义 |
|---|---|
可清理缓存 | 应用运行中产生的可再生的数据，清理后无任何功能影响。 |
可清理数据 | 应用运行中产生的非必需数据，清理后不影响应用基本功能，但部分数据可能需要重新获取或不可恢复。 |
必要数据 | 应用正常运行所必需的数据，清理后将导致应用无法正常使用、核心功能异常或用户登录状态丢失。 |
无主文件 | 因引用丢失导致应用无法识别和管理的残留文件。 |
本规范围绕两个核心维度展开：
应用文件存储在沙箱目录下，目录决定文件的存储语义。本节介绍沙箱目录的结构、用途及清理策略。
目录结构
data/
└─── storage/
├─── el1/
│ ├─── base/
│ ├─── bundle/
│ └─── database/
├─── el2/
│ ├─── base/
│ │ ├─── cache/
│ │ ├─── files/
│ │ ├─── preferences/
│ │ ├─── temp/
│ │ └─── haps/
│ │ └─── <module-name>/
│ │ ├─── cache/
│ │ ├─── files/
│ │ ├─── preferences/
│ │ └─── temp/
│ ├─── database/
│ │ └─── <module-name>/
│ └─── distributedfiles/
├─── el3/
├─── el4/
└─── el5/
目录用途
沙箱目录 | Context属性名称 | 说明 |
|---|---|---|
bundle | bundleCodeDir | 存放HAP资源包、可复用库及插件资源，随应用安装生成，应用不可写入。 |
files | filesDir | 存放默认长期保存的私有文件，如用户持久性文件、媒体文件。 |
cache | cacheDir | 存放可重新下载或重新生成的缓存文件，如视频缓存、图片缓存。 |
temp | tempDir | 存放运行期间临时产生的数据。 |
preferences | preferencesDir | 存放配置类或首选项数据，仅适用于少量数据。 |
database | databaseDir | 存放数据库文件。 |
distributedfiles | distributedFilesDir | 存放跨设备共享及协作文件。 |
各目录的详细说明和注意事项见HarmonyOS应用沙箱目录。
目录清理
应用沙箱目录的清理可通过以下方式实现：
HarmonyOS 公共目录按文件类型和用途划分为以下功能目录：
目录名称 | 目录标识 | 说明 |
|---|---|---|
下载目录 | Download | 存放用户下载的文件。 |
文档目录 | Documents | 存放用户文档类文件。 |
桌面目录 | Desktop | 存放用户桌面文件，当前支持2in1设备，从API版本26.0.0开始支持tablet设备。 |
应用应当让用户准确感知存储占用，确保展示数据与系统统计一致。
【应当】 向用户展示应用总存储占用时，整体数值取自storageStatistics.getCurrentBundleStats()，总占用计算公式为appSize + dataSize（dataSize已包含缓存数据，不应额外叠加cacheSize）。
【推荐】 按可清理缓存、可清理数据和必要数据分类展示存储占用，各类别数据范围互斥且由应用根据业务场景确定。
【不得】 将自行扫描的部分目录数据展示为应用完整存储占用。
【不得】 将清理后不影响应用正常使用的文件归入必要数据。
【推荐】 存储占用数据加载完成前，展示加载状态或留空而非零值，避免用户误判为无可清理数据。
应用应当提供存储清理入口并保障清理执行效果，确保清理真实生效且覆盖完整。
【应当】 提供应用内存储清理入口或存储空间管理页面。
【推荐】 支持从系统设置存储页面一键跳转至应用内清理入口或存储空间管理页面。
【推荐】 执行清理操作前展示可清理内容及其占用大小，并向用户确认清理范围，防止误清理用户必要数据。
【不得】 清理操作导致应用异常退出。
【应当】 清理操作应覆盖所有已统计的可清理数据，清理范围应与统计范围一致。
【推荐】 清理过程中展示进度，完成后更新存储占用展示，失败时提示原因。
应用应当从源头减少存储占用，避免不必要的重复与冗余。
文件去重
【推荐】 同一文件多处使用时，通过共享或去重机制，避免创建不必要的独立副本。
【推荐】 同一文件多次执行相同处理时，保持处理方式一致以复用已有产物，避免重复产出相同文件。
【应当】 避免HAP与HSP间包含重复的so和资源文件。
文件压缩
【推荐】 发送或上传高清视频、图片等文件时，若需在本地保留副本，默认以压缩格式保存，并提供保留原始质量选项。
【推荐】 长期存储且访问频率低的文件优先以压缩格式存储，按需解压使用。
【推荐】 数据库空闲空间占比较高时，压缩回收空闲空间，避免数据库文件远大于有效数据量。
端云协同
【推荐】 对已完全同步至云端且本地长期未访问的文件，可释放本地存储空间、保留用户可见入口，用户访问时从云端按需下载恢复。
按需获取
【推荐】 资源按需获取，避免一次性获取全量资源。
应用应感知存储空间余量状态，空间不足时采取相应措施，避免异常退出。
【应当】 处理存储空间不足导致的写入失败，避免因写入失败导致异常退出。
【推荐】 执行大文件写入等空间敏感操作前检查系统剩余空间，不足时中断写入并提示用户。
【推荐】 当检测到存储空间不足或自身占用较大时，主动清理缓存或过期文件。
文件创建时应按文件性质和用途选择存放目录并确定其归属。
目录选择
【应当】 根据文件性质（缓存、临时、持久等）以及目录用途选择存放位置。
【推荐】 在cacheDir、filesDir等沙箱目录下按业务维度创建子目录，避免大量文件未分类存放。
【不得】 将缓存文件或临时文件放在filesDir、databaseDir、preferencesDir等非缓存目录下。
【不得】 将用户手动保存、下载的内容放在cacheDir或tempDir目录下。
【应当】 向公共目录写入的文件应为用户主动保存的内容，非用户主动保存的文件应写入沙箱目录。
归属管理
【应当】 文件应可从业务数据中追溯（如记录文件路径），避免产生无主文件。
【应当】 多账号场景下，不同账号的文件应隔离存放，避免跨账号访问。
【应当】 引入第三方SDK或库时，应识别其产生文件的存放位置与性质。
文件存续期间应以容量、期限与归属为条件持续管控，防止无限增长与过期残留。文件不再满足存续条件时则进行清理。
容量管控
【应当】 缓存目录应设置容量上限，超限时按淘汰策略清理缓存文件。
【应当】 日志文件应设置容量上限，超限时轮转。
期限管控
【应当】 缓存文件、临时文件与日志文件应设置保留期限，过期时清理。
【应当】 资源新版本生效后，旧版本文件应予以清理，避免持续累积占用空间。
归属管控
【应当】 检测无主文件，并将其纳入清理范围。
【应当】 存放目录因应用变更而废弃时，应对旧目录进行清理或纳入清理范围。
文件销毁应明确清理的触发条件与保障机制，防止文件残留。
触发条件
【应当】 任务完成、失败或用户主动取消时，删除该任务产生的所有临时文件。
【应当】 用户删除业务数据（如聊天记录、对话、草稿、离线内容等）时，删除关联的本地文件。
【应当】 账号注销时，清理与该账号关联的全部文件。
【推荐】 账号切换时，清理非当前账号的可清理缓存。
保障机制
【应当】 异常退出后，应在下次启动时检测并清理未清理的临时文件，或先提供恢复机制、恢复失败时清理。
【推荐】 缓存和过期文件的清理可在应用启动时或空闲时触发。
以下是常见业务场景中的典型问题及优化建议：
问题 | 典型场景 | 优化建议 |
|---|---|---|
重复副本 | 同一视频发送后缓存目录与持久化目录各存一份；或发送给不同好友时分别保留副本。 | 使用引用计数或共享机制去重。 |
离线资源堆积 | 离线资源包（如小程序、web页面资源）升级后旧版本持续堆积。 | 新版本生效后及时删除旧版本。 |
资源全量加载 | 应用启动时一次性下载全部页面资源，未访问的资源也长期占用存储空间。 | 按需加载，首次访问时下载。 |
原始文件未压缩 | 视频非原图发送后本地保留原始视频而非压缩版本。 | 非原图发送后保留压缩版本替代原始文件。 |
完成后未清理 | 视频导出或发布、文件上传至云盘完成后，产生的中间文件和临时副本未删除。 | 流程完成后删除中间文件和临时副本。 |
中断后未清理 | 视频编辑或发布过程中取消操作、应用异常退出后，流程中产生的中间文件未被清理。 | 取消或退出时清理未完成的中间文件；异常退出后下次启动时检测并清理残留文件。 |
删除后未释放 | 删除对话或草稿后，关联的媒体文件未被同步删除。 | 删除操作应即时释放关联文件或提供自动过期机制。 |
缓存无限增长 | 视频播放或内容浏览产生的缓存持续积累，缓存目录持续膨胀。 | 设置容量上限和过期淘汰策略。 |
离线内容误清 | 用户主动缓存或离线保存的内容存放在cacheDir，被系统自动清理后导致内容不可用。 | 用户主动离线保存的内容存入filesDir。 |
旧目录残留 | 应用数据存放目录变更后，旧目录废弃未清理。 | 数据存放目录变更时将旧目录纳入清理范围。 |
缺少清理入口 | 应用未提供存储空间管理或缓存清理入口，用户无法主动清理存储占用。 | 提供应用内存储清理入口或存储空间管理页面。 |
清理统计偏差 | 清理页面展示容量与系统统计不一致：统计遗漏目录或重复统计导致偏差。 | 使用系统storageStatistics.getCurrentBundleStats API获取统计数据，确保分类互斥不重不漏。 |
清理范围不完整 | 清理页面未覆盖全部可清理目录，部分缓存数据虽被统计但无法通过清理操作删除。 | 清理操作覆盖所有可清理目录，统计范围与清理范围一致。 |