Back to Details

encore-bucket

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Encore Object Storage

Encore 对象存储

Instructions

指令

A 
Bucket
is a logical store for files. Encore provisions the underlying object storage (S3 on AWS, GCS on GCP, in-memory locally). Declare buckets at package level.
typescript
import { Bucket } from "encore.dev/storage/objects";

// Private bucket (default)
export const uploads = new Bucket("user-uploads", {
  versioned: false,  // Set to true to keep multiple versions
});

// Public bucket — files accessible via public URL
export const publicAssets = new Bucket("public-assets", {
  public: true,
  versioned: false,
});
Bucket
是用于存储文件的逻辑存储桶。Encore 会自动配置底层对象存储（AWS 上使用 S3、GCP 上使用 GCS，本地使用内存存储）。请在包级别声明存储桶。
typescript
import { Bucket } from "encore.dev/storage/objects";

// Private bucket (default)
export const uploads = new Bucket("user-uploads", {
  versioned: false,  // Set to true to keep multiple versions
});

// Public bucket — files accessible via public URL
export const publicAssets = new Bucket("public-assets", {
  public: true,
  versioned: false,
});

Operations

操作

typescript
// Upload
const attrs = await uploads.upload("path/to/file.jpg", buffer, {
  contentType: "image/jpeg",
});

// Download
const data = await uploads.download("path/to/file.jpg");

// Existence check
const exists = await uploads.exists("path/to/file.jpg");

// Attributes (size, content type, ETag)
const meta = await uploads.attrs("path/to/file.jpg");

// Delete
await uploads.remove("path/to/file.jpg");

// List
for await (const entry of uploads.list({})) {
  console.log(entry.key, entry.size);
}

// Public URL (only for public buckets)
const url = publicAssets.publicUrl("image.jpg");
typescript
// Upload
const attrs = await uploads.upload("path/to/file.jpg", buffer, {
  contentType: "image/jpeg",
});

// Download
const data = await uploads.download("path/to/file.jpg");

// Existence check
const exists = await uploads.exists("path/to/file.jpg");

// Attributes (size, content type, ETag)
const meta = await uploads.attrs("path/to/file.jpg");

// Delete
await uploads.remove("path/to/file.jpg");

// List
for await (const entry of uploads.list({})) {
  console.log(entry.key, entry.size);
}

// Public URL (only for public buckets)
const url = publicAssets.publicUrl("image.jpg");

Signed URLs

签名 URL

Generate temporary URLs so clients can upload/download directly without going through your service:
typescript
const uploadUrl = await uploads.signedUploadUrl("user-uploads/avatar.jpg", { ttl: 7200 });
const downloadUrl = await uploads.signedDownloadUrl("documents/report.pdf", { ttl: 7200 });
生成临时 URL，使客户端无需经过你的服务即可直接上传或下载文件：
typescript
const uploadUrl = await uploads.signedUploadUrl("user-uploads/avatar.jpg", { ttl: 7200 });
const downloadUrl = await uploads.signedDownloadUrl("documents/report.pdf", { ttl: 7200 });

Bucket References

存储桶引用

Pass bucket access to other code with a specific permission set:
typescript
import { Uploader, Downloader } from "encore.dev/storage/objects";

const uploaderRef = uploads.ref<Uploader>();
const downloaderRef = uploads.ref<Downloader>();

// Permission types: Downloader, Uploader, Lister, Attrser, Remover,
// SignedDownloader, SignedUploader, ReadWriter
通过特定的权限集将存储桶访问权限传递给其他代码：
typescript
import { Uploader, Downloader } from "encore.dev/storage/objects";

const uploaderRef = uploads.ref<Uploader>();
const downloaderRef = uploads.ref<Downloader>();

// Permission types: Downloader, Uploader, Lister, Attrser, Remover,
// SignedDownloader, SignedUploader, ReadWriter

Errors

错误

  • ObjectNotFound
    — object doesn't exist
  • PreconditionFailed
    — upload preconditions not met (e.g. 
    setIfNotExists
    )
  • ObjectsError
    — base error type
  • ObjectNotFound
    — 对象不存在
  • PreconditionFailed
    — 未满足上传前置条件（例如 
    setIfNotExists
    ）
  • ObjectsError
    — 基础错误类型

Guidelines

指南

  • Declare buckets at package level.
  • Default to private buckets; opt into 
    public: true
    only for assets meant for unauthenticated download.
  • Use signed URLs for browser uploads/downloads instead of streaming through your service.
  • Use bucket references when passing access to helpers — they encode the permission contract in the type system.
  • 在包级别声明存储桶。
  • 默认使用私有存储桶；仅当资源需要供未认证用户下载时，才设置 
    public: true
    。
  • 对浏览器上传和下载使用签名 URL，避免通过你的服务传输数据流。
  • 将存储桶访问权限传递给辅助函数时使用存储桶引用——引用会在类型系统中编码权限约定。