在本教程中,你将学习如何创建 Cloudflare Workers 应用,并使用 TCP Sockets 和 Hyperdrive 连接到 MySQL 数据库。你在本教程中创建的 Workers 应用将与 MySQL 中的产品数据库交互。
要继续,请:
-
若尚未注册,请注册 Cloudflare 账户 ↗。
-
安装
npm↗。 -
安装
Node.js↗。使用 Vite+ (
vp env) ↗ 安装和管理 Node.js 版本。有关支持的 Node.js 版本,请参阅 Wrangler 系统要求。
-
确保你可以访问 MySQL 数据库。
首先,使用 create-cloudflare CLI ↗ 创建新的 Worker 应用。打开终端窗口并运行以下命令:
npm create cloudflare@latest -- mysql-tutorialyarn create cloudflare mysql-tutorialpnpm 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数据库驱动程序(包括 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 兼容性标志。
使用 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>"安装 mysql2 ↗ 驱动:
npm i mysql2@>3.13.0yarn add mysql2@>3.13.0pnpm add mysql2@>3.13.0bun 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-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>;运行以下命令部署 Worker:
npx wrangler deploy你的应用现已上线,可通过 <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev 访问。
要基于数据库和 Workers 构建更多内容,请参阅教程并探索数据库文档。
如有疑问、需要帮助或想分享你的项目,请加入 Cloudflare 开发者社区 Discord ↗,与其他开发者和 Cloudflare 团队交流。