ストレージ

永続データにアクセスするため、S3 互換のストレージバケット（R2、S3、GCS）をサンドボックスのファイルシステムにマウントします。mountBucket() は、R2 バインディングマウント、開発時のローカル R2 バインディング同期、リモートの S3 互換エンドポイントマウントに対応します。

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 - バケットが存在しない、または権限が不足しています

以前にマウントしたバケットをアンマウントします。

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');

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() は次の 3 モードに対応します。

• R2 バインディングマウント - 本番で Worker のバインディング名によりマウントするには、endpoint を省略します

  • R2 向けに、認証情報なしの送信傍受（egress interception）を使います
  • prefix、readOnly、s3fsOptions に対応します

• ローカル R2 バインディングマウント - wrangler dev 中に localBucket: true を設定します

  • ローカル同期を通じて、Worker の R2 バインディングを直接使います
  • prefix と readOnly に対応します

• リモートエンドポイントマウント - 任意の S3 互換プロバイダーをマウントするには endpoint を設定します

  • 明示的な 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 は S3 エンドポイントではなく、R2 バインディングを直接同期します

• provider（リモートエンドポイントモードのみ） - ストレージプロバイダーのヒント

  • プロバイダー固有の最適化を有効にします
  • 値: 'r2'、's3'、'gcs'

• credentials（リモートエンドポイントモードのみ） - API 認証情報

  • accessKeyId と secretAccessKey を含みます
  • 指定しない場合は環境変数を使います

• credentialProxy（リモートエンドポイントモードのみ） - 署名のため、S3 リクエストを Durable Object 経由でルーティングします

  • true のとき、認証情報はコンテナのディスクに書き込まれません。Durable Object がネットワーク層ですべての送信 S3 リクエストを傍受し、再署名してから上流へ転送します。
  • S3 互換エンドポイント（R2 を含む）向けの AWS SigV4 ↗ 署名と、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']

s3fs フラグの自動最適化向けのストレージプロバイダーヒントです。

type BucketProvider = "r2" | "s3" | "gcs";

• 'r2' - Cloudflare R2（推奨。nomixupload フラグを適用します）
• 's3' - Amazon S3
• 'gcs' - Google Cloud Storage

• バケットのマウントガイド - バケットマウントの完全な手順
• Files API - ファイルの読み書き