开始使用

本指南将引导您创建您的第一个 Workers VPC 服务，允许您的 Worker 访问私有网络中的资源。

您将创建一个 Workers 应用程序，在私有网络中创建一个 Tunnel 以将其连接到 Cloudflare，然后为您希望从 Workers 访问的私有网络上的服务配置 VPC 服务。

在开始之前，请确保您已完成以下操作：

1. 注册 Cloudflare 账户 ↗。
2. 安装 Node.js ↗。

此外，您还需要：

• 访问私有网络（您的本地网络、AWS VPC、Azure VNet、GCP VPC 或本地网络）
• Connectivity Directory Bind（连接目录绑定） 角色，以便从 Workers 绑定到现有的 VPC 服务。
• 或者，Connectivity Directory Admin（连接目录管理员） 角色，以创建 VPC 服务，并从 Workers 绑定到这些服务。

使用 Wrangler 创建一个新的 Worker 项目：

npm create cloudflare@latest -- workers-vpc-app

yarn create cloudflare workers-vpc-app

pnpm create cloudflare@latest workers-vpc-app

进行设置时，请选择以下选项：

• 对于 What would you like to start with?，选择 Hello World example。
• 对于 Which template would you like to use?，选择 Worker only。
• 对于 Which language do you want to use?，选择 TypeScript。
• 对于 Do you want to use git for version control?，选择 Yes。
• 对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。

导航到您的项目目录：

cd workers-vpc-app

Cloudflare Tunnel 可创建从私有网络到 Cloudflare 的安全连接。此隧道将允许 Workers 安全地访问您的私有资源。您可以在外部云中的虚拟机或容器上创建隧道，为了本教程，您甚至可以在本地桌面上创建隧道。

仪表板将在您的隧道成功连接时进行确认。

连接隧道后，您需要确保它可以访问您希望 Workers 访问的服务。隧道应安装在可以访问您想要向 Workers VPC 公开的内部资源的机器上。在外部云中，这可能意味着配置访问控制列表（Access-Control-Lists）、安全组（Security Groups）或 VPC 防火墙规则，以确保隧道可以访问所需的服务。

既然您的隧道已在运行，请创建一个 Workers 可以用来访问您的内部资源的 VPC 服务：

npx wrangler vpc service create my-private-api \
  --type http \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --hostname <YOUR_HOSTNAME>

npx wrangler vpc service create my-database \
  --type tcp \
  --tcp-port 5432 \
  --app-protocol postgresql \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --ipv4 <YOUR_IPV4_ADDRESS>

如果您遇到权限错误，请参阅所需角色。

将 VPC 服务绑定添加到您的 Wrangler 配置文件中：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "workers-vpc-app",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"vpc_services": [
		{
			"binding": "VPC_SERVICE",
			"service_id": "<YOUR_SERVICE_ID>"
		}
	]
}

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

[[vpc_services]]
binding = "VPC_SERVICE"
service_id = "<YOUR_SERVICE_ID>"

将 <YOUR_SERVICE_ID> 替换为您在第 3 步中获得的服务 ID。

更新您的 Worker 以使用 VPC 服务绑定。以下示例：

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const url = new URL(request.url);

		// This is a simple proxy scenario.
		// In this case, you will need to replace the URL with the proper protocol (http vs. https), hostname and port of the service.
		// For example, this could be "http://localhost:1111", "http://192.0.0.1:3000", "https://my-internal-api.example.com"
		const targetUrl = new URL(
			`http://<ENTER_SERVICE_HOST>:<ENTER_SERVICE_PORT>${url.pathname}${url.search}`,
		);

		// Create new request with the target URL but preserve all other properties
		const proxyRequest = new Request(targetUrl, {
			method: request.method,
			headers: request.headers,
			body: request.body,
		});

		const response = await env.VPC_SERVICE.fetch(proxyRequest);

		return response;
	},
} satisfies ExportedHandler<Env>;

在本地测试您的 Worker。您必须使用远程 VPC 服务，要么使用在您的 wrangler.jsonc 配置文件中配置的 Workers 远程绑定，要么使用 npx wrangler dev --remote：

npx wrangler dev

访问 http://localhost:8787，测试您的 Worker 与私有网络的连接。

测试完成后，部署您的 Worker：

npx wrangler deploy

您的 Worker 现已部署，并可通过 Cloudflare Tunnel 安全地访问您的私有网络资源。如果您遇到权限错误，请参阅所需角色。

• 探索配置选项以进行高级设置
• 为生产环境设置高可用性隧道
• 查看针对 AWS、Azure、GCP 和 Kubernetes 的特定平台指南
• 查看常见用例的示例