Wrangler 配置

最小配置

使用 Sandbox SDK 所需的最小配置：

{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": ["nodejs_compat"],
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}

name = "my-sandbox-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]

[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

[[migrations]]
new_sqlite_classes = [ "Sandbox" ]
tag = "v1"

必需设置

Sandbox SDK 构建在 Cloudflare Containers 之上。你的配置需要三个部分：

containers - 定义容器镜像（你的运行时环境）
durable_objects.bindings - 将 Sandbox Durable Object 绑定到你的 Worker
migrations - 初始化 Durable Object 类

上面显示的最小配置包含所有必需设置。有关详细配置选项，请参阅 Containers 配置文档。

备份存储

要使用备份与恢复 API，你需要 R2 存储桶绑定（binding）与预签名 URL 凭据。容器使用预签名 URL 直接向/从 R2 上传与下载备份归档，这需要 R2 API 令牌凭据。

1. 创建 R2 存储桶

npx wrangler r2 bucket create my-backup-bucket

2. 添加绑定与环境变量

{
	"vars": {
		"BACKUP_BUCKET_NAME": "my-backup-bucket",
		"CLOUDFLARE_ACCOUNT_ID": "<YOUR_ACCOUNT_ID>",
	},
	"r2_buckets": [
		{
			"binding": "BACKUP_BUCKET",
			"bucket_name": "my-backup-bucket",
		},
	],
}

[vars]
BACKUP_BUCKET_NAME = "my-backup-bucket"
CLOUDFLARE_ACCOUNT_ID = "<YOUR_ACCOUNT_ID>"

[[r2_buckets]]
binding = "BACKUP_BUCKET"
bucket_name = "my-backup-bucket"

3. 将 R2 API 凭据设为 secrets

npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY

在 Cloudflare 仪表板 ↗ 的 R2 > Overview（概览） > Manage R2 API Tokens（管理 R2 API 令牌） 下创建 R2 API 令牌。该令牌需要对你的备份存储桶具备 Object Read & Write（对象读取和写入） 权限。

SDK 使用这些凭据生成预签名 URL，允许容器直接在 R2 之间传输备份归档。完整设置演练请参阅备份与恢复指南。

故障排除

找不到绑定

错误：TypeError: env.Sandbox is undefined

解决方案：确保你的 wrangler.jsonc 包含 Durable Objects 绑定（binding）：

{
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

缺少 migrations

错误：Durable Object 未初始化

解决方案：为 Sandbox 类添加 migrations：

{
	"migrations": [
		{
			"new_sqlite_classes": ["Sandbox"],
			"tag": "v1",
		},
	],
}

[[migrations]]
new_sqlite_classes = [ "Sandbox" ]
tag = "v1"