使用 JavaScript SDK 存储和提供文件
client.storage 的日常存储流程:存储桶管理、单部分和分段上传、流式下载、HMAC 签名 URL 和垃圾恢复。
该页面已自动翻译。英文版具有权威性。
桶管理#
存储桶 对文件进行分组并决定它们是否是公共的。创建和删除存储桶需要 service_role 密钥。列出存储桶需要登录用户或 service_role 密钥(匿名密钥接收 403 FORBIDDEN)。
typescript
// 创建公共存储桶(任何人都可以读取没有 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。
上传、下载、列出、删除#
typescript
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)#
typescript
// 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()) 标识。在公共和私有存储桶上,用户无法覆盖或销毁其他用户的对象。
移动、复制、元数据和垃圾#
typescript
// 复制文件(保留原始内容类型和自定义元数据)
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 参考。