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

环境变量

最后更新 查看 MarkdownAgent 设置

使用环境变量向 sandbox 传递配置、密钥和运行时设置。

SDK 配置变量

这些环境变量配置 Sandbox SDK 的行为。在 wrangler.jsonc 文件中将其设置为 Worker vars。SDK 会从 Worker 的环境绑定读取它们。

SANDBOX_TRANSPORT

类型 "http" | "websocket"
默认值 "http"

控制 SDK 到容器通信的传输协议。WebSocket 传输在单个持久连接上多路复用所有操作，在每个请求执行大量 SDK 操作时，可避免子请求限制。

{
	"vars": {
		"SANDBOX_TRANSPORT": "websocket"
	}
}
[vars]
SANDBOX_TRANSPORT = "websocket"

完整指南（包括何时使用各传输、性能考量与迁移说明）请参阅传输模式。

COMMAND_TIMEOUT_MS

类型 number（毫秒）
默认值 无（无超时）

为每次 exec() 调用设置全局默认超时。设置后，任何超过该时长的命令会在调用方抛出错误并关闭连接。

exec() 上的按命令 timeout 以及 createSession() 上的会话级 commandTimeoutMs 都会覆盖此值。有关超时优先级的更多详情，请参阅 Execute commands - Timeouts。

{
	"vars": {
		"COMMAND_TIMEOUT_MS": "30000"
	}
}
[vars]
COMMAND_TIMEOUT_MS = "30000"

设置环境变量的三种方式

Sandbox SDK 提供三种设置环境变量的方法，适用于不同用例：

1. 使用 setEnvVars() 设置 sandbox 级别

为 sandbox 中的所有命令全局设置环境变量：

const sandbox = getSandbox(env.Sandbox, "my-sandbox");

// Set once, available for all subsequent commands
await sandbox.setEnvVars({
	DATABASE_URL: env.DATABASE_URL,
	API_KEY: env.API_KEY,
});

await sandbox.exec("python migrate.py"); // Has DATABASE_URL and API_KEY
await sandbox.exec("python seed.py"); // Has DATABASE_URL and API_KEY

// Unset variables by passing undefined
await sandbox.setEnvVars({
	API_KEY: "new-key", // Updates API_KEY
	OLD_SECRET: undefined, // Unsets OLD_SECRET
});

适用场景： 多个命令需要相同的环境变量。

取消设置变量：传入 undefined 或 null 以取消设置环境变量：

await sandbox.setEnvVars({
	API_KEY: 'new-key',     // Sets API_KEY
	OLD_SECRET: undefined,  // Unsets OLD_SECRET
	DEBUG_MODE: null        // Unsets DEBUG_MODE
});

2. 使用 exec() 选项按命令设置

为特定命令传递环境变量：

await sandbox.exec("node app.js", {
	env: {
		NODE_ENV: "production",
		PORT: "3000",
	},
});

// Also works with startProcess()
await sandbox.startProcess("python server.py", {
	env: {
		DATABASE_URL: env.DATABASE_URL,
	},
});

适用场景： 不同命令需要不同的环境变量，或需要覆盖 sandbox 级别的变量。

3. 使用 createSession() 设置会话级别

创建具有自身环境变量的隔离会话：

const session = await sandbox.createSession({
	env: {
		DATABASE_URL: env.DATABASE_URL,
		SECRET_KEY: env.SECRET_KEY,
	},
});

// All commands in this session have these vars
await session.exec("python migrate.py");
await session.exec("python seed.py");

适用场景： 需要同时运行具有不同环境变量的隔离执行上下文。

取消设置环境变量

Sandbox SDK 支持通过传入 undefined 或 null 值来取消设置环境变量。这支持惯用的 JavaScript 配置管理模式：

await sandbox.setEnvVars({
	// Set new values
	API_KEY: 'new-key',
	DATABASE_URL: env.DATABASE_URL,

	// Unset variables (removes them from the environment)
	OLD_API_KEY: undefined,
	TEMP_TOKEN: null
});

此前：传入 undefined 值会抛出运行时错误。

现在：undefined 和 null 值会在 shell 中执行 unset VARIABLE_NAME。

取消设置的用例

使用后移除敏感数据：

// Use a temporary token
await sandbox.setEnvVars({ TEMP_TOKEN: 'abc123' });
await sandbox.exec('curl -H "Authorization: $TEMP_TOKEN" api.example.com');

// Clean up the token
await sandbox.setEnvVars({ TEMP_TOKEN: undefined });

有条件地设置环境：

await sandbox.setEnvVars({
	API_KEY: env.API_KEY,
	DEBUG_MODE: env.NODE_ENV === 'development' ? 'true' : undefined,
	PROFILING: env.ENABLE_PROFILING ? 'true' : undefined
});

重置为系统默认值：

// Unset to fall back to container's default NODE_ENV
await sandbox.setEnvVars({ NODE_ENV: undefined });

常见模式

将 Worker 密钥传递到 sandbox

安全地将 Worker 中的密钥传递到 sandbox。首先使用 Wrangler 设置密钥：

wrangler secret put OPENAI_API_KEY
wrangler secret put DATABASE_URL

然后传递到 sandbox：

import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	OPENAI_API_KEY: string;
	DATABASE_URL: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "user-sandbox");

		// Option 1: Set globally for all commands
		await sandbox.setEnvVars({
			OPENAI_API_KEY: env.OPENAI_API_KEY,
			DATABASE_URL: env.DATABASE_URL,
		});
		await sandbox.exec("python analyze.py");

		// Option 2: Pass per-command
		await sandbox.exec("python analyze.py", {
			env: {
				OPENAI_API_KEY: env.OPENAI_API_KEY,
			},
		});

		return Response.json({ success: true });
	},
};

组合默认与特定变量

const defaults = { NODE_ENV: "production", LOG_LEVEL: "info" };

await sandbox.exec("npm start", {
	env: { ...defaults, PORT: "3000", API_KEY: env.API_KEY },
});

多个隔离会话

使用不同环境变量并发运行不同任务：

// Production database session
const prodSession = await sandbox.createSession({
	env: { DATABASE_URL: env.PROD_DATABASE_URL },
});

// Staging database session
const stagingSession = await sandbox.createSession({
	env: { DATABASE_URL: env.STAGING_DATABASE_URL },
});

// Run migrations on both concurrently
await Promise.all([
	prodSession.exec("python migrate.py"),
	stagingSession.exec("python migrate.py"),
]);

配置传输模式

在 Worker 的 vars 中设置 SANDBOX_TRANSPORT，以在 HTTP 与 WebSocket 传输之间切换。有关何时及如何配置各传输的详情，请参阅传输模式。

存储桶挂载凭据

挂载兼容 S3 的对象存储时，SDK 底层使用 s3fs-fuse，需要 AWS 风格的凭据。对于 R2，请从 Cloudflare 仪表板生成 API token，并使用 AWS 环境变量名提供它们：

获取 R2 API token：

  1. 在 Cloudflare 仪表板中前往 R2 > Overview（概览） ↗
  2. 选择 Manage R2 API Tokens（管理 R2 API 令牌）
  3. 创建具有 Object Read & Write 权限的 token
  4. 复制 Access Key ID（访问密钥 ID） 和 Secret Access Key（秘密访问密钥）

将凭据设置为 Worker 密钥：

wrangler secret put AWS_ACCESS_KEY_ID
# Paste your R2 Access Key ID

wrangler secret put AWS_SECRET_ACCESS_KEY
# Paste your R2 Secret Access Key

使用自动凭据检测挂载存储桶：

import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

interface Env {
	Sandbox: DurableObjectNamespace<Sandbox>;
	AWS_ACCESS_KEY_ID: string;
	AWS_SECRET_ACCESS_KEY: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const sandbox = getSandbox(env.Sandbox, "data-processor");

		// Credentials automatically detected from environment
		await sandbox.mountBucket("my-r2-bucket", "/data", {
			endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
		});

		// Access mounted bucket using standard file operations
		await sandbox.exec("python", { args: ["process.py", "/data/input.csv"] });

		return Response.json({ success: true });
	},
};

当你在调用 mountBucket() 时不显式提供凭据时，SDK 会自动从 Worker 环境中检测 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。

显式传递凭据（若使用自定义密钥名称）：

await sandbox.mountBucket("my-r2-bucket", "/data", {
	endpoint: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: env.R2_ACCESS_KEY_ID,
		secretAccessKey: env.R2_SECRET_ACCESS_KEY,
	},
});

完整的存储桶挂载文档请参阅挂载存储桶指南。

环境变量优先级

当同一变量在多个层级设置时，最具体的层级优先：

  1. 命令级别（最高）— 传递给 exec() 或 startProcess() 的选项
  2. Sandbox 或会话级别 — 使用 setEnvVars() 设置
  3. 容器默认值 — 在 Docker 镜像中通过 ENV 内置
  4. 系统默认值（最低）— 操作系统默认值

示例：

// In Dockerfile: ENV NODE_ENV=development

// Sandbox-level
await sandbox.setEnvVars({ NODE_ENV: "staging" });

// Command-level overrides all
await sandbox.exec("node app.js", {
	env: { NODE_ENV: "production" }, // This wins
});

相关资源

这篇文档对您有帮助吗？