在自定义域名上配置预览 URL

设置通配符 DNS、路由和 TLS，使 exposePort() 预览 URL 能在你的域名上工作。要部署 Worker 与 sandbox 镜像，请参阅 部署 Sandbox 应用。

预览 URL 需要通配符 DNS，因为每个暴露的端口都会获得唯一子域名：https://8080-abc123.yourdomain.com。

.workers.dev 域名不支持通配符子域名，因此在本地开发之外、必须通过公共主机名访问的预览 URL 需要自定义域名。

• 具有域名的有效 Cloudflare zone
• 使用 exposePort() 的 Worker
• 已安装 Wrangler CLI
• Sandbox 应用已可部署（Worker + 镜像）

在 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",
	"upload_source_maps": true,
	// Set this to today's date
	"compatibility_date": "2026-11-14",
	"routes": [
		{
			"pattern": "*.yourdomain.com/*",
			"zone_name": "yourdomain.com"
		}
	]
}

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

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

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

重新部署 Worker，使路由配置生效：

npx wrangler deploy

如果此次部署还会更改 sandbox 镜像或包，请按照 部署 Sandbox 应用 进行发布以及包/镜像配对。仅更改路由时仍可使用普通部署。仅在你有意跳过容器镜像与实例更新时，才使用 --containers-rollout=none。

测试预览 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 路由文档。

• 部署 Sandbox 应用 - 部署 Worker 与镜像
• 预览 URL - 预览 URL 的工作原理
• 暴露服务 - 暴露端口的模式
• Tunnels API - 用于开发的零配置 *.trycloudflare.com URL
• Workers 路由 - 高级路由配置
• Cloudflare DNS - DNS 管理