使用 Cloudflare Workers 连接 MySQL 数据库

在本教程中，你将学习如何创建 Cloudflare Workers 应用，并使用 TCP Sockets 和 Hyperdrive 连接到 MySQL 数据库。你在本教程中创建的 Workers 应用将与 MySQL 中的产品数据库交互。

前置条件

要继续，请：

若尚未注册，请注册 Cloudflare 账户 ↗。
安装 npm ↗。
安装 Node.js ↗。使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器以避免权限问题并切换 Node.js 版本。Wrangler 需要 Node 版本 16.17.0 或更高。
确保你可以访问 MySQL 数据库。

1. 创建 Worker 应用

首先，使用 create-cloudflare CLI ↗ 创建新的 Worker 应用。打开终端窗口并运行以下命令：

npm create cloudflare@latest -- mysql-tutorial

yarn create cloudflare mysql-tutorial

pnpm create cloudflare@latest mysql-tutorial

这将提示你安装 create-cloudflare ↗ 包并引导你完成设置向导。

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

对于 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（部署前我们还会做一些修改）。

若选择部署，系统将要求你进行身份验证（若尚未登录），项目将被部署。即使已部署，你仍可在本教程结束时修改 Worker 代码并再次部署。

现在，进入新创建的目录：

cd mysql-tutorial

2. 启用 Node.js 兼容性

数据库驱动程序（包括 mysql2）需要 Node.js 兼容性，必须为你的 Workers 项目进行配置。

要为 Worker 或 Pages 项目启用内置运行时 API 和 polyfill，请在你的 Wrangler 配置文件中添加 nodejs_compat 兼容性标志，并将兼容性日期设置为 2024 年 9 月 23 日或更高版本。这将为 Workers 项目启用 Node.js 兼容性。

{
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-08-17"
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"

3. 创建 Hyperdrive 配置

使用 MySQL 数据库的连接字符串创建 Hyperdrive 配置。

npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

此命令输出 Hyperdrive 配置 id，将用于 Hyperdrive 绑定（binding）。通过在 Wrangler 配置文件中指定 id 设置绑定。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hyperdrive-example",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hyperdrive-example"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"

4. 从 Worker 查询数据库

安装 mysql2 ↗ 驱动：

npm i mysql2@>3.13.0

yarn add mysql2@>3.13.0

pnpm add mysql2@>3.13.0

bun add mysql2@>3.13.0

在 wrangler.jsonc 中添加所需的 Node.js 兼容性标志和 Hyperdrive 绑定：

在 wrangler.jsonc 中添加 Node.js 兼容性标志和 Hyperdrive 绑定（binding）：

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-08-17"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

创建新的 connection 实例并传入 Hyperdrive 参数：

// mysql2 v3.13.0 or later is required
import { createConnection } from "mysql2/promise";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new connection on each request. Hyperdrive maintains the underlying
		// database connection pool, so creating a new connection is fast.
		const connection = await createConnection({
			host: env.HYPERDRIVE.host,
			user: env.HYPERDRIVE.user,
			password: env.HYPERDRIVE.password,
			database: env.HYPERDRIVE.database,
			port: env.HYPERDRIVE.port,

			// Required to enable mysql2 compatibility for Workers
			disableEval: true,
		});

		try {
			// Sample query
			const [results, fields] = await connection.query("SHOW tables;");

			// Return result rows as JSON
			return Response.json({ results, fields });
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

5. 部署 Worker

运行以下命令部署 Worker：

npx wrangler deploy

你的应用现已上线，可通过 <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev 访问。

后续步骤

要基于数据库和 Workers 构建更多内容，请参阅教程并探索数据库文档。

如有疑问、需要帮助或想分享你的项目，请加入 Cloudflare 开发者社区 Discord ↗，与其他开发者和 Cloudflare 团队交流。