部署到生产环境

将你的 Sandbox SDK 应用部署到生产环境并支持预览 URL。预览 URL 需要通配符 DNS 路由，因为它们会为每个暴露的端口生成唯一子域名：https://8080-abc123.yourdomain.com。

.workers.dev 域名不支持通配符子域名，因此使用预览 URL 的生产部署需要自定义域名。

• 具有域名的有效 Cloudflare zone
• 使用 exposePort() 的 Worker
• 已安装 Wrangler CLI

在 Cloudflare 仪表板中，进入你的域名并创建 A 记录：

• Type：A
• Name：*（通配符）
• IPv4 address：192.0.2.0
• Proxy status（代理状态）：Proxied（橙色云朵）

这会将所有子域名路由到 Cloudflare 代理。IP 地址 192.0.2.0 是文档用地址（RFC 5737），在启用代理时会被 Cloudflare 识别。

在 Wrangler 配置中添加通配符路由：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-sandbox-app",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"routes": [
		{
			"pattern": "*.yourdomain.com/*",
			"zone_name": "yourdomain.com"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-sandbox-app"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"

[[routes]]
pattern = "*.yourdomain.com/*"
zone_name = "yourdomain.com"

将 yourdomain.com 替换为你的实际域名。这会将所有子域名请求路由到你的 Worker，并使 Cloudflare 能够自动签发 SSL 证书。

部署你的 Worker：

npx wrangler deploy

测试预览 URL 是否可用：

// Extract hostname from request
const { hostname } = new URL(request.url);

const sandbox = getSandbox(env.Sandbox, 'test-sandbox');
await sandbox.startProcess('python -m http.server 8080');
const exposed = await sandbox.exposePort(8080, { hostname });

console.log(exposed.url);
// https://8080-test-sandbox.yourdomain.com

在浏览器中访问该 URL，确认服务可访问。

• CustomDomainRequiredError：确认 Worker 未部署到 .workers.dev，并且通配符 DNS 记录与路由已正确配置。
• SSL/TLS 错误：等待几分钟以完成证书签发。确认 DNS 记录已代理，且仪表板中 SSL/TLS 模式设置为 “Full” 或 “Full (strict)”。如果 Worker 位于子域名上（例如 sandbox.yourdomain.com），Universal SSL 不会覆盖二级通配符 *.sandbox.yourdomain.com — 请参阅本页顶部的 TLS 注意事项 了解可选方案。
• 预览 URL 无法解析：确认通配符 DNS 记录存在且已代理。等待 30–60 秒以便 DNS 传播。
• 端口不可访问：确保服务绑定到 0.0.0.0（而不是 localhost），并且在 Worker 的 fetch 处理程序中首先调用了 proxyToSandbox()。

详细故障排除请参阅 Workers 路由文档。

• 预览 URL - 预览 URL 的工作原理
• 暴露服务 - 暴露端口的模式
• Tunnels API - 用于开发的零配置 *.trycloudflare.com URL（不适用于生产）
• Workers 路由 - 高级路由配置
• Cloudflare DNS - DNS 管理