本地开发

Hyperdrive 可在本地开发和测试 Workers 时使用。Wrangler（Workers 命令行接口）提供两种本地开发选项：

• wrangler dev（默认）：在本地机器上运行 Worker 代码。配置 localConnectionString 直接连接数据库（本地或远程）。此模式下 Hyperdrive 查询缓存不生效。
• wrangler dev --remote：在 Cloudflare 上使用已部署的 Hyperdrive 配置运行 Worker。适用于测试启用 Hyperdrive 连接池和查询缓存的场景。

默认情况下，wrangler dev 在本地机器上运行 Worker 代码。本地开发连接数据库时，配置直接指向数据库的 localConnectionString。

localConnectionString 支持本地和远程数据库：

• 本地数据库：连接本机运行的数据库实例（例如 postgres://user:password@localhost:5432/database）
• 远程数据库：通过 TLS 直接连接远程数据库（例如 postgres://user:password@remote-host.example.com:5432/database?sslmode=require 或 mysql://user:password@remote-host.example.com:3306/database?sslMode=required）。需要时须指定 SSL/TLS 模式。

推荐用环境变量，避免将凭据提交到源代码控制：

# Your configured Hyperdrive binding is "HYPERDRIVE"
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@your-database-host:5432/database"
npx wrangler dev

环境变量格式为 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>，其中 <BINDING_NAME> 是 Wrangler 配置文件 中为 Hyperdrive 分配的绑定名称。

取消环境变量：unset CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>

例如，为本地数据库设置连接字符串：

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/databasename"
npx wrangler dev

也可在 Wrangler 配置文件 中设置 localConnectionString：

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "c020574a-5623-407b-be0c-cd192bab9545",
			"localConnectionString": "postgres://user:password@localhost:5432/databasename"
		}
	]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "c020574a-5623-407b-be0c-cd192bab9545"
localConnectionString = "postgres://user:password@localhost:5432/databasename"

若同时设置了环境变量和 Wrangler 配置文件中的 localConnectionString，环境变量优先。

运行 wrangler dev --remote 时，Worker 在 Cloudflare 网络中运行并使用已部署的 Hyperdrive 配置。这意味着：

• Worker 代码在 Cloudflare 生产环境执行，而非本地
• Hyperdrive 的连接池和查询缓存处于活动状态
• 连接在 Hyperdrive 配置中配置的数据库（通过 wrangler hyperdrive create 创建）
• 会话期间的更改会与远程资源交互

此模式适用于部署前测试 Worker 在启用 Hyperdrive 功能时的行为。

在 wrangler.jsonc 中配置 Hyperdrive 绑定：

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "your-hyperdrive-id",
		},
	],
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "your-hyperdrive-id"

启动远程开发会话：

npx wrangler dev --remote

请参阅 wrangler dev 文档 了解如何配置本地开发会话。

• 使用 wrangler dev 在本地运行 Worker 和 Hyperdrive，部署前调试问题。
• 了解 Hyperdrive 工作原理。
• 了解如何 在 Hyperdrive 中配置查询缓存。