云端存储

cloud.storage 保存当前登录用户在当前小程序下的私有字符串数据，适合云存档和偏好同步。身份由受信 Host 上下文绑定，SDK 不接受用户 ID 或小程序 ID。

权限声明

需要独立声明 cloud_storage，无需公开 network 权限，本地 storage 权限不授予云端能力：

{"heybox":{"permissions":{"cloud_storage":{"enabled":true}}}}

登录要求

四个云存储方法均要求当前用户已登录小黑盒客户端。未登录时，Promise 以 HbMiniProgramSDKError（code: 'UNAUTHORIZED'）拒绝，不会自动拉起登录或发送云存储请求；业务应提示用户登录成功后重试。

云存储不要求先调用 auth.login() 获取小程序授权码，两者的用途见用户身份与登录。

import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'

try {
  const value = await hbSDK.cloud.storage.getStorage('save_1')
  // undefined 只表示 key 不存在；空字符串仍是有效值。
  if (value !== undefined) console.log(value)
} catch (error) {
  if (error instanceof HbMiniProgramSDKError && error.code === 'UNAUTHORIZED') {
    console.warn('请先登录小黑盒客户端，登录成功后再重试')
  } else {
    throw error
  }
}

读写存档

import hbSDK from '@heybox/hb-sdk'

await hbSDK.cloud.storage.setStorage('save_1', JSON.stringify({ level: 5 }))
const value = await hbSDK.cloud.storage.getStorage('save_1')
if (value !== undefined) console.log(JSON.parse(value))

const keys = await hbSDK.cloud.storage.getKeys()
await hbSDK.cloud.storage.removeItem('save_1')

cloud.storage.getStorage(key) 返回原始字符串，不存在返回 undefined；空字符串是有效值。cloud.storage.setStorage(key, value) 仅接受字符串，不自动转换 JSON；成功返回 void。cloud.storage.getKeys() 返回字符串数组。cloud.storage.removeItem(key) 删除整个键值记录，不存在也视为成功，成功返回 void。

写入与并发

同 key 的 setStorage 从第一笔待发送写入开始收集 500ms，窗口内仅保留最后一个 value，后续调用不延长窗口。合并调用的 Promise 在最终值获得远端确认后一起完成；请求失败则一起拒绝。不同 key 独立请求，同 key 串行发送；窗口已经结束但前一请求仍在途时，下一批继续排队，不能改写已发出的请求。一个 key 失败不会阻塞其他 key。

版本凭证完全由 Runtime 管理，不暴露给开发者。Runtime 沿用读到的数据凭证写入，直接写入时内部先读取当前凭证。其他设备或运行实例已改写数据时返回 VERSION_CONFLICT；不会自动刷新版本覆盖重试，应重新读取、合并后再写。写入失败时会清除该 key 缓存并拒绝已排队的同 key 操作，之后必须显式 get 成功才能继续 set，不能自动刷新凭证覆盖远端数据。

同 key 的写入和删除按调用顺序执行，删除隔开写入窗口，不跨删除合并，避免延迟写入重新创建已删除记录。队列中的最新值可以立即通过 getStorage 读取；这不表示已远端保存。关闭小程序前应等待写入 Promise 完成，尚未发送的数据无法保证保存。Runtime 销毁或账号切换时，待完成调用会被拒绝，队列与缓存被清理。

限制与错误

项目	规则
key	与本地 storage 默认规则一致，1–128 位英文字母、数字、下划线 _、连字符 -
value	字符串，最多 16KB UTF-8 字节，可为空
key 数量	每个用户在每个小程序下最多 64 个

参数非法返回 INVALID_PARAMS，新增 key 超过配额返回 STORAGE_QUOTA_EXCEEDED。异常沿用 storage 的 HbMiniProgramSDKError 和 Promise reject 机制，业务根据 code 判断，不比较提示文案。

读取使用最多 30 秒的会话缓存，相同 key 的并发读取合并；其他设备的修改可能在缓存过期后才可见。写入继续使用缓存数据对应的凭证，不能通过后台刷新绕过冲突检查。云端请求仍受 Runtime 请求闸门和网关限流约束，分别可能返回 RATE_LIMITED_BY_RUNTIME、RATE_LIMITED。

更多处理方式见错误处理。