跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

使用 Cloudflare Workers 连接 MySQL 数据库

最后更新 查看 MarkdownAgent 设置

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

前置条件

要继续,请:

  1. 若尚未注册,请注册 Cloudflare 账户 ↗。

  2. 安装 npm ↗。

  3. 安装 Node.js ↗。

    使用 Vite+ (vp env) ↗ 安装和管理 Node.js 版本。

    有关支持的 Node.js 版本,请参阅 Wrangler 系统要求。

  4. 确保你可以访问 MySQL 数据库。

1. 创建 Worker 应用

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

npm 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?(是否使用 Git 进行版本控制?),选择 Yes。
  • 对于 Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?(是否添加 AGENTS.md 文件以帮助 AI 编程工具理解 Cloudflare API?),选择 Yes。
  • 对于 Do you want to deploy your application?(是否部署应用?),选择 No(部署前还需要进行一些修改)。

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

现在,进入新创建的目录:

cd mysql-tutorial

2. 启用 Node.js 兼容性

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

对于 2026-08-04 或更晚的兼容性日期,Workers 和 Pages 项目默认启用 nodejs_compat 和 nodejs_compat_v2。内置运行时 API 和 polyfill 无需额外配置即可使用。这些兼容性日期不使用这两个标志。现有项目更新兼容性日期时,无需移除这些标志。

如果兼容性日期早于 2026-08-04,请将 nodejs_compat 兼容性标志添加到 Wrangler 配置文件中以启用:

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}
compatibility_flags = [ "nodejs_compat" ]

要针对 2026-08-04 或更晚的兼容性日期完全关闭 Node.js 兼容性,请先移除已有的启用标志,然后同时添加 no_nodejs_compat 和 no_nodejs_compat_v2。配置示例请参阅 Node.js 兼容性标志。

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",
	"upload_source_maps": true,
	// Set this to today's date
	"compatibility_date": "2026-11-20",
	"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"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-20"
compatibility_flags = [ "nodejs_compat" ]

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

4. 从 Worker 查询数据库

安装 mysql2 ↗ 驱动:

npm i 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-11-20",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}
compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-11-20"

[[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 团队交流。

这篇文档对您有帮助吗?