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

使用 Cloudflare Workers 连接 MongoDB 数据库

最后更新 查看 MarkdownAgent 设置

在本教程中,你将学习如何创建 Cloudflare Workers 应用,并使用原生 Node.js 驱动将其连接到 MongoDB 数据库。你将先从 Worker 直接连接,然后使用 Durable Object 持久化连接并降低延迟。

前置条件

继续之前:

  1. 如果还没有,请注册 Cloudflare 账户 ↗。
  2. 安装 npm ↗。
  3. 安装 Node.js ↗。使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器,以避免权限问题并切换 Node.js 版本。
  4. 确保你可以访问 MongoDB 数据库。可以使用 MongoDB Atlas ↗、自托管 MongoDB 实例或任何其他兼容 MongoDB 的主机。

1. 创建 Worker 应用

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

npm create cloudflare@latest -- mongodb-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 mongodb-tutorial

2. 启用 Node.js 兼容性

MongoDB 驱动需要 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. 添加 MongoDB 连接库

要连接 MongoDB 数据库,你需要 mongodb 库。在 Worker 应用目录中运行以下命令安装该库:

npm i mongodb

4. 配置到 MongoDB 数据库的连接

将 MongoDB 连接字符串设置为 secret,以免以明文存储。使用 wrangler secret put 和示例变量名 MONGODB_URI:

npx wrangler secret put MONGODB_URI

按 使用密钥进行本地开发 的说明,在 .env 文件中本地设置 MONGODB_URI secret:

.envtoml
MONGODB_URI="<ENTER YOUR MONGODB CONNECTION STRING>"

5. 在 Worker 中连接到 MongoDB 数据库

打开 Worker 的主文件(例如 src/index.ts),并从 mongodb 库导入 MongoClient 类:

import { MongoClient } from "mongodb";

在 fetch 事件处理程序中,创建新的 MongoClient 实例并连接到 MongoDB 数据库。

// create a new MongoClient instance using the connection string
const client = new MongoClient(env.MONGODB_URI);
// connect to the MongoDB database
await client.connect();

6. 与 movies 数据库交互

为演示如何与 movies 数据库交互,你会在收到请求时查询 movies collection 并获取一份文档。

将 src/index.ts 中的现有代码替换为以下代码:

src/index.jsjs
import { MongoClient } from "mongodb";

export default {
	async fetch(request, env, ctx) {
		const client = new MongoClient(env.MONGODB_URI);
		await client.connect();

		const movie = await client
			.db("sample_mflix")
			.collection("movies")
			.findOne(
				{ title: "The Room" },
				{ projection: { _id: 0, title: 1, imdb: 1 } },
			);

		return Response.json({ movie });
	},
};
src/index.tsts
import { MongoClient } from "mongodb";

export interface Env {
	MONGODB_URI: string;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const client = new MongoClient(env.MONGODB_URI);
		await client.connect();

		const movie = await client
			.db("sample_mflix")
			.collection("movies")
			.findOne(
				{ title: "The Room" },
				{ projection: { _id: 0, title: 1, imdb: 1 } },
			);

		return Response.json({ movie });
	},
} satisfies ExportedHandler<Env>;

此代码在 Worker 应用中建立到 MongoDB 数据库的连接,查询 movies collection,并将结果作为 JSON 响应返回。

7. 部署 Worker

运行以下命令部署 Worker:

npx wrangler deploy

部署后,你可以使用 Cloudflare Worker 与 MongoDB 数据库交互。每当向 Worker URL 发出请求时,它都会从 movies collection 获取数据并以 JSON 响应返回。

8. 使用 Durable Object 加速查询

每次 Worker 调用都会创建到 MongoDB 的新 TCP 和 TLS 连接。对于低流量场景,这可以接受。对于对延迟敏感的应用,将 MongoClient 放在 Durable Object 中,以便在请求之间持久化连接。

为 Durable Object 类创建新文件:

src/MongoDBConnection.jsjs
import { DurableObject } from "cloudflare:workers";
import { MongoClient } from "mongodb";

export class MongoDBConnection extends DurableObject {
	client;

	constructor(state, env) {
		super(state, env);
		this.client = new MongoClient(env.MONGODB_URI, {
			maxPoolSize: 1,
			minPoolSize: 0,
			serverSelectionTimeoutMS: 5000,
			maxIdleTimeMS: 20_000,
		});
	}

	async getMovie() {
		await this.client.connect();
		return this.client
			.db("sample_mflix")
			.collection("movies")
			.findOne(
				{ title: "The Room" },
				{ projection: { _id: 0, title: 1, imdb: 1 } },
			);
	}
}
src/MongoDBConnection.tsts
import { DurableObject } from "cloudflare:workers";
import { MongoClient } from "mongodb";

interface Env {
	MONGODB_URI: string;
}

export class MongoDBConnection extends DurableObject<Env> {
	private client: MongoClient;

	constructor(state: DurableObjectState, env: Env) {
		super(state, env);
		this.client = new MongoClient(env.MONGODB_URI, {
			maxPoolSize: 1,
			minPoolSize: 0,
			serverSelectionTimeoutMS: 5000,
			maxIdleTimeMS: 20_000,
		});
	}

	async getMovie() {
		await this.client.connect();
		return this.client
			.db("sample_mflix")
			.collection("movies")
			.findOne(
				{ title: "The Room" },
				{ projection: { _id: 0, title: 1, imdb: 1 } },
			);
	}
}

更新 Worker 入口点,将请求路由到 Durable Object:

src/index.jsjs
import { MongoDBConnection } from "./MongoDBConnection";

export default {
	async fetch(request, env) {
		const id = env.MONGODB_CONNECTION.idFromName("mongodb-connection");
		const stub = env.MONGODB_CONNECTION.get(id, { locationHint: "enam" });
		const movie = await stub.getMovie();
		return Response.json({ movie });
	},
};

export { MongoDBConnection };
src/index.tsts
import { MongoDBConnection } from "./MongoDBConnection";

interface Env {
	MONGODB_URI: string;
	MONGODB_CONNECTION: DurableObjectNamespace<MongoDBConnection>;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const id = env.MONGODB_CONNECTION.idFromName("mongodb-connection");
		const stub = env.MONGODB_CONNECTION.get(id, { locationHint: "enam" });
		const movie = await stub.getMovie();
		return Response.json({ movie });
	},
} satisfies ExportedHandler<Env>;

export { MongoDBConnection };

使用 locationHint 选项将 Durable Object 放在靠近 MongoDB 集群的位置。

在 Wrangler 文件中配置 Durable Object 绑定和迁移:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "mongodb-tutorial",
  "main": "src/index.ts",
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "MONGODB_CONNECTION",
        "class_name": "MongoDBConnection"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_classes": [
        "MongoDBConnection"
      ]
    }
  ]
}
name = "mongodb-tutorial"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-11-14"
compatibility_flags = ["nodejs_compat"]

[[durable_objects.bindings]]
name = "MONGODB_CONNECTION"
class_name = "MongoDBConnection"

[[migrations]]
tag = "v1"
new_classes = ["MongoDBConnection"]

9. 重新部署 Worker

运行以下命令部署 Worker:

npx wrangler deploy

你的 Worker 应用现已上线,可在 <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev 访问,并使用 Durable Object 持久化 MongoDB 连接。这会将查询延迟从冷请求的约 300 ms 降到预热请求的约 35 ms。

后续步骤

要使用数据库和 Workers 构建更多内容,请参阅教程并探索数据库文档。

如有任何问题、需要帮助或想分享项目,请加入 Cloudflare Developer 社区 Discord ↗,与其他开发者和 Cloudflare 团队交流。

这篇文档对您有帮助吗?