文档›指南›Store and serve files (SDK) 使用 JavaScript SDK 存储和提供文件
aura.storage的日常流程，以及针对正在运行的堆栈观察到的访问规则。
8分钟 读取·级别 中间·修改于 2026年10月12日
该英文文本是根据法文原文自动生成的，尚未经过审查。
该页面已自动翻译。英文版具有权威性。
存储桶对文件进行分组并决定它们是否公开。创建和删除存储桶需要 service_role 密钥。列出它们需要登录用户或 service_role 密钥；单独的公钥获得 403。
server/buckets.tstypescript
await admin.storage.createBucket('avatars', { public: true }) // 任何人都可以阅读这些文件
await admin.storage.createBucket('invoices', { public: false }) // 只有它们的主人才能
const { data: buckets } = await admin.storage.listBuckets()
存储桶还接受 fileSizeLimit （以字节为单位）和 allowedMimeTypes。太大的上传返回 413，不允许的类型返回 400。
files.tstypescript
const bucket = aura.storage.from('invoices')
// 上传：Blob、File 或 ArrayBuffer
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
contentType: 'application/pdf',
})
// → { key, Bucket, url, size, content_type, etag }
// 替换现有文件
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })
// 列出文件夹、下载、删除
const { data: files } = await bucket.list(user.id)
const { data: blob } = await bucket.download(`${user.id}/2026-10.pdf`)
await bucket.remove([`${user.id}/2026-10.pdf`])
期待什么：
- 上传现有路径会返回
409 ，除非您传递 upsert: true。
- 上传需要登录用户或
service_role 密钥。 仅公钥即可获得 403，即使对于公共存储桶也是如此。
- 具有
.. 的路径被拒绝 和 400。
- 路径在存储桶内共享。 如果其他用户已经拥有该路径，您将获得
409。将每个用户的文件放在自己的文件夹下，例如 ${user.id}/…。
share.tstypescript
// 公共存储桶中的文件：永久 URL，无需请求即可构建
const { data } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → { publicUrl: 'https://my-app.aurabase.cloud/v1/storage/avatars/ada.png' }
// 私人文件：临时链接
const { data: signed } = await aura.storage.from('invoices').createSignedUrl(`${user.id}/2026-10.pdf`, 60)
// → { url, expires_in: 60 }
这两个链接都是在没有任何密钥的情况下获取并返回文件的。签名链接在 expires_in 秒后停止工作。为了让浏览器无需密钥即可上传，服务器会创建 createSignedUploadUrl(path) （service_role 调用）。
| 行动 | 公钥 | 登录用户 | service_role |
|---|
| 读取公共存储桶中的文件 | 是的 | 是的 | 是的 |
| 读取、列出私有存储桶中的文件 | 不 | 仅其所有者 | 是的 |
| 上传 | 不 | 是的 | 是的 |
| 替换或删除文件 | 不 | 仅其所有者 | 是的 |
| 列出存储桶 | 不 | 是的 | 是的 |
| 创建、删除桶 | 不 | 不 | 是的 |
所有者是上传文件的用户。在实际运行中，第二个用户无法列出、下载或删除第一个用户在私有存储桶中的文件，也无法替换它。
server/organise.tstypescript
await admin.storage.copy('invoices', 'a/hello.txt', 'a/copy.txt')
await admin.storage.move('invoices', 'a/copy.txt', 'a/moved.txt')
const { data: meta } = await admin.storage.getMetadata('invoices', 'a/hello.txt')
图像大小调整在 存储参考中进行了描述。
