跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

存储

最后更新 查看 MarkdownAgent 设置

将 S3 兼容存储桶（R2、S3、GCS）挂载到沙箱文件系统，以实现持久数据访问。mountBucket() 支持 R2 绑定挂载、开发期间的本地 R2 绑定同步，以及远程 S3 兼容端点挂载。

方法

mountBucket()

将 S3 兼容存储桶挂载到沙箱中的本地路径。

await sandbox.mountBucket(
  bucket: string,
  mountPath: string,
  options?: MountBucketOptions
): Promise<void>

参数：

  • bucket - 存储桶标识符
    • 省略 options.endpoint 时，传入 Worker R2 绑定名称（例如 "MY_BUCKET"）
    • 提供 options.endpoint 时，传入远程存储桶名称（例如 "my-r2-bucket"）
  • mountPath - 挂载的本地文件系统路径（例如 "/data"）
  • options（可选）- 挂载配置（见 MountBucketOptions）
// Mount an R2 bucket by Worker binding name
await sandbox.mountBucket("MY_BUCKET", "/data");

// Read/write files directly
const data = await sandbox.readFile("/data/config.json");
await sandbox.writeFile("/data/results.json", JSON.stringify(data));

// Mount a remote S3-compatible bucket, including explicit R2 endpoints
await sandbox.mountBucket("my-bucket", "/storage", {
	endpoint: "https://s3.amazonaws.com",
	credentials: {
		accessKeyId: env.AWS_ACCESS_KEY_ID,
		secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
	},
});

// Mount an R2 bucket during local development with wrangler dev
await sandbox.mountBucket("MY_BUCKET", "/local-data", {
	localBucket: true,
});

// Mount a prefix from an R2 binding
await sandbox.mountBucket("MY_BUCKET", "/user-data", {
	prefix: "/users/user-123",
	readOnly: true,
});
// Mount an R2 bucket by Worker binding name
await sandbox.mountBucket('MY_BUCKET', '/data');

// Read/write files directly
const data = await sandbox.readFile('/data/config.json');
await sandbox.writeFile('/data/results.json', JSON.stringify(data));

// Mount a remote S3-compatible bucket, including explicit R2 endpoints
await sandbox.mountBucket('my-bucket', '/storage', {
  endpoint: 'https://s3.amazonaws.com',
  credentials: {
    accessKeyId: env.AWS_ACCESS_KEY_ID,
    secretAccessKey: env.AWS_SECRET_ACCESS_KEY
  }
});

// Mount an R2 bucket during local development with wrangler dev
await sandbox.mountBucket('MY_BUCKET', '/local-data', {
  localBucket: true
});

// Mount a prefix from an R2 binding
await sandbox.mountBucket('MY_BUCKET', '/user-data', {
  prefix: '/users/user-123',
  readOnly: true
});

抛出：

  • InvalidMountPointError - 挂载路径无效或与现有挂载冲突
  • BucketAccessError - 存储桶不存在或权限不足

unmountBucket()

卸载先前挂载的存储桶。

await sandbox.unmountBucket(mountPath: string): Promise<void>

参数：

  • mountPath - 存储桶挂载的路径（例如 "/data"）
// Mount, process, unmount
await sandbox.mountBucket("MY_BUCKET", "/data");
await sandbox.exec("python process.py");

// Unmount
await sandbox.unmountBucket("/data");
// Mount, process, unmount
await sandbox.mountBucket('MY_BUCKET', '/data');
await sandbox.exec('python process.py');

// Unmount
await sandbox.unmountBucket('/data');

类型

MountBucketOptions

interface RemoteMountBucketOptions {
  endpoint: string;
  provider?: BucketProvider;
  credentials?: BucketCredentials;
  credentialProxy?: boolean;
  readOnly?: boolean;
  s3fsOptions?: string[];
  prefix?: string;
}

interface LocalMountBucketOptions {
  localBucket: true;
  prefix?: string;
  readOnly?: boolean;
}

interface R2BindingMountBucketOptions {
  endpoint?: never;
  prefix?: string;
  readOnly?: boolean;
  s3fsOptions?: string[];
}

type MountBucketOptions =
  | RemoteMountBucketOptions
  | LocalMountBucketOptions
  | R2BindingMountBucketOptions;

mountBucket() 支持以下三种模式：

  • R2 绑定挂载 - 省略 endpoint，在生产环境中按 Worker 绑定名称挂载

    • 对 R2 使用无凭据的出站拦截
    • 支持 prefix、readOnly 与 s3fsOptions

  • 本地 R2 绑定挂载 - 在 wrangler dev 期间设置 localBucket: true

    • 通过本地同步直接使用 Worker R2 绑定
    • 支持 prefix 与 readOnly

  • 远程端点挂载 - 设置 endpoint 以挂载任意 S3 兼容提供商

    • 支持显式 credentials 或环境变量自动检测
    • 设置 credentialProxy: true 以使凭据不进入容器（出站拦截）
    • 支持 provider、prefix、readOnly 与 s3fsOptions

字段详情：

  • endpoint（仅远程端点模式）- S3 兼容端点 URL

    • R2：'https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com'
    • S3：'https://s3.amazonaws.com'
    • GCS：'https://storage.googleapis.com'

  • localBucket（仅本地开发模式）- 在使用 wrangler dev 进行本地开发时，通过 Worker 的 R2 绑定挂载 R2 存储桶

    • 为 true 时，SDK 直接同步 R2 绑定，而不是使用 S3 端点

  • provider（仅远程端点模式）- 存储提供商提示

    • 启用特定于提供商的优化
    • 取值：'r2'、's3'、'gcs'

  • credentials（仅远程端点模式）- API 凭据

    • 包含 accessKeyId 与 secretAccessKey
    • 若未提供，则使用环境变量

  • credentialProxy（仅远程端点模式）- 通过 Durable Object 路由 S3 请求以进行签名

    • 为 true 时，凭据永远不会写入容器磁盘。Durable Object 在网络层拦截并重新签名所有出站 S3 请求，然后再转发到上游。
    • 支持 AWS SigV4 ↗ 签名（用于包括 R2 在内的 S3 兼容端点）以及用于 Google Cloud Storage 的 HMAC 签名
    • 要求从你的 Worker 入口导出 ContainerProxy
    • 默认：false（向后兼容 — 建议设为 true；将在未来版本中成为默认值）

  • readOnly（可选）- 以只读模式挂载

    • 默认：false

  • prefix（可选）- 存储桶内要挂载的子目录

    • 指定后，只有此前缀下的内容在挂载点可见
    • 必须以 / 开头（例如 /data/uploads 或 /data/uploads/）
    • 默认：挂载整个存储桶

  • s3fsOptions（仅 R2 绑定与远程端点模式）- 高级 s3fs 挂载标志

    • 类型：string[]
    • 示例：['use_cache=/tmp/cache', 'stat_cache_expire=1']

BucketProvider

用于自动 s3fs 标志优化的存储提供商提示。

type BucketProvider = "r2" | "s3" | "gcs";
  • 'r2' - Cloudflare R2（推荐，应用 nomixupload 标志）
  • 's3' - Amazon S3
  • 'gcs' - Google Cloud Storage

相关资源

这篇文档对您有帮助吗？