在本教程中,你将学习如何创建 Cloudflare Workers 应用,并使用原生 Node.js 驱动将其连接到 MongoDB 数据库。你将先从 Worker 直接连接,然后使用 Durable Object 持久化连接并降低延迟。
继续之前:
- 如果还没有,请注册 Cloudflare 账户 ↗。
- 安装
npm↗。 - 安装
Node.js↗。使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器,以避免权限问题并切换 Node.js 版本。 - 确保你可以访问 MongoDB 数据库。可以使用 MongoDB Atlas ↗、自托管 MongoDB 实例或任何其他兼容 MongoDB 的主机。
首先,使用 create-cloudflare CLI ↗ 创建新的 Worker 应用。打开终端窗口并运行以下命令:
npm create cloudflare@latest -- mongodb-tutorialyarn create cloudflare mongodb-tutorialpnpm 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-tutorialMongoDB 驱动需要 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 兼容性标志。
要连接 MongoDB 数据库,你需要 mongodb 库。在 Worker 应用目录中运行以下命令安装该库:
npm i mongodbyarn add mongodbpnpm add mongodbbun add mongodb将 MongoDB 连接字符串设置为 secret,以免以明文存储。使用 wrangler secret put 和示例变量名 MONGODB_URI:
npx wrangler secret put MONGODB_URI按 使用密钥进行本地开发 的说明,在 .env 文件中本地设置 MONGODB_URI secret:
MONGODB_URI="<ENTER YOUR MONGODB CONNECTION STRING>"打开 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();为演示如何与 movies 数据库交互,你会在收到请求时查询 movies collection 并获取一份文档。
将 src/index.ts 中的现有代码替换为以下代码:
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 });
},
};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 响应返回。
运行以下命令部署 Worker:
npx wrangler deploy部署后,你可以使用 Cloudflare Worker 与 MongoDB 数据库交互。每当向 Worker URL 发出请求时,它都会从 movies collection 获取数据并以 JSON 响应返回。
每次 Worker 调用都会创建到 MongoDB 的新 TCP 和 TLS 连接。对于低流量场景,这可以接受。对于对延迟敏感的应用,将 MongoClient 放在 Durable Object 中,以便在请求之间持久化连接。
为 Durable Object 类创建新文件:
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 } },
);
}
}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:
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 };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"]运行以下命令部署 Worker:
npx wrangler deploy你的 Worker 应用现已上线,可在 <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev 访问,并使用 Durable Object 持久化 MongoDB 连接。这会将查询延迟从冷请求的约 300 ms 降到预热请求的约 35 ms。
要使用数据库和 Workers 构建更多内容,请参阅教程并探索数据库文档。
如有任何问题、需要帮助或想分享项目,请加入 Cloudflare Developer 社区 Discord ↗,与其他开发者和 Cloudflare 团队交流。