跳到内容
光环标志
光环基地

使用 JavaScript SDK 存储和提供文件

client.storage 的日常存储流程:存储桶管理、单部分和分段上传、流式下载、HMAC 签名 URL 和垃圾恢复。

操作指南8分钟 读取级别 中间修改于 2026年10月28日

该页面已自动翻译。英文版具有权威性。

桶管理#

存储桶 对文件进行分组并决定它们是否是公共的。创建和删除存储桶需要 service_role 密钥。列出存储桶需要登录用户或 service_role 密钥(匿名密钥接收 403 FORBIDDEN)。

server/buckets.tstypescript
// 创建公共存储桶(任何人都可以读取没有 API 密钥的对象)
await admin.storage.createBucket('avatars', { public: true })

// 创建私有存储桶(只有对象所有者或service_role可以读取)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // 每个文件 10 MiB 限制
  allowedMimeTypes: ['application/pdf'],
})

// 列出可访问的存储桶
const { data: buckets, error } = await admin.storage.listBuckets()

存储桶还接受 fileSizeLimit (以字节为单位)和 allowedMimeTypes。太大的上传返回 413 PAYLOAD_TOO_LARGE,不允许的类型返回 400 BAD_REQUEST。

上传、下载、列出、删除#

files.tstypescript
const bucket = aura.storage.from('invoices')

// 上传:文件、Blob、缓冲区或 Uint8Array
// 文件 > 5 MiB 会自动分割成多部分
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → { key, Bucket, url, size, content_type, etag }

// 替换当前用户拥有的现有文件
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// 列出前缀/文件夹下的文件
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// 将文件下载为 Blob
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// 流式下载,无需将整个文件加载到内存中
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// 删除文件(默认移至垃圾箱,保留 30 天)
await bucket.remove([`${user.id}/2026-10.pdf`])

// 永久删除(绕过垃圾并立即释放磁盘配额)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

关键运行时行为:

  • 上传现有路径会返回 409 CONFLICT,除非提供 upsert: true。
  • 匿名上传在私有和公共存储桶上都会被 和 403 FORBIDDEN 拒绝(写入需要经过身份验证的 JWT 或服务密钥)。
  • 路径遍历保护:包含 .. 或非法字符的路径返回 400 INVALID_PATH 而不抛出未处理的异常。
  • 用户隔离:一个用户无法覆盖或删除另一用户拥有的文件 (owner_id = auth.uid())。使用用户范围的文件夹(如 ${user.id}/...)构建路径。

共享文件(公共和签名 URL)#

share.tstypescript
// 1. 公共存储桶:直接永久 URL(无需 API 密钥提供)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// 使用自定义文件名强制下载为附件
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. 私有存储桶:HMAC 带有可配置 TTL 的签名 URL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // 有效期300秒(5分钟)
  { download: true }
)
// data.signedUrl 和 data.url 包含 HMAC 签名 URL

// 3.浏览器直接上传,不暴露秘钥
// 服务器端(service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// 浏览器客户端(无需 API 密钥):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

签名 URL 密封 HTTP 方法(GET 或 PUT)、存储桶、密钥和过期时间戳。一旦过期或对象被删除,请求将收到 403 FORBIDDEN。

谁可以做什么(访问矩阵)#

行动匿名密钥 (anon)登录用户 (authenticated)服务角色 (service_role)
读取公共存储桶中的文件是的是的是的
读取私有存储桶中的文件否(403)仅限所有者 (owner_id = auth.uid())是的
上传新文件否(403)是(成为所有者)是的
替换 (upsert) 或删除否(403)仅限业主是的
列出公共存储桶中的文件是的是的是的
列出私有存储桶中的文件否(403)仅限所有者(RLS 过滤器)是的
创建、更新或删除存储桶否(403)否(403)是的
Mint 签名的上传 URL否(403)否(403)是的

所有者由 JWT 主体 (auth.uid()) 标识。在公共和私有存储桶上,用户无法覆盖或销毁其他用户的对象。

移动、复制、元数据和垃圾#

server/organise.tstypescript
// 复制文件(保留原始内容类型和自定义元数据)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// 移动或重命名文件
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// 检查对象元数据(大小、MIME 类型、ETag、自定义元数据)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// 列出当前垃圾箱中的项目(保留 30 天)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// 从垃圾中恢复对象
await admin.storage.from('invoices').restore('2026/final.pdf')

有关实时图像转换(调整大小、格式转换、旋转),请参阅 存储 SDK 参考。