文档Cloudflare D1 数据库
NEXTDEVKIT 边缘部署的完整 Cloudflare D1 设置指南，包含 D1 和 KV 配置。
Cloudflare D1 是 NEXTDEVKIT 的 Cloudflare Workers 部署的默认数据库，提供全球边缘数据库，具有低延迟和自动复制功能。
🚀 为什么选择 Cloudflare D1？
选择 Cloudflare D1 用于 Cloudflare Workers 部署是因为：
- ⚡ 边缘性能：数据库在边缘运行，贴近用户
- 🌍 全球复制：全球自动数据复制
- 🔧 SQLite 兼容：熟悉的 SQL 语法和操作
- 💰 成本效益：按使用付费的定价模式
- 🔄 无服务器扩展：与您的 Workers 自动扩展
- 🛡️ 内置安全：与 Cloudflare 的安全功能集成
🏗️ 数据库架构
D1 + KV 存储架构
NEXTDEVKIT 使用 Cloudflare D1 存储结构化数据，使用 Cloudflare KV 作为缓存：
| 组件 | Next.js 应用 (Worker) | Cloudflare D1 (数据库) | Cloudflare KV (缓存) |
|---|---|---|---|
| 目的 | 边缘应用程序 | 结构化数据存储 | 缓存层 |
| 功能 | 页面 | 用户数据 | 缓存数据 |
| API 路由 | 支付 | 临时数据 | |
| 中间件 | 设置 |
🔧 初始设置
1. 创建 D1 数据库
为您的 NEXTDEVKIT 项目创建新的 D1 数据库：
# 创建 D1 数据库
pnpm wrangler d1 create prod-d1-tutorial预期输出：
✅ Successfully created DB 'prod-d1-tutorial' in region WEUR
Created your new D1 database.
{
"d1_databases": [
{
"binding": "DB",
"database_name": "prod-d1-tutorial",
"database_id": "<unique-ID-for-your-database>"
}
]
}2. 创建 KV 命名空间
为缓存和会话存储创建 KV 命名空间：
# 创建 KV 命名空间
pnpm wrangler kv namespace create nextdevkit-cloudflare-template-kv预期输出：
🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
"kv_namespaces": [
{
"binding": "USERS_NOTIFICATION_CONFIG",
"id": "<BINDING_ID>"
}
]
}3. 配置 wrangler.jsonc
使用数据库和 KV 配置更新您的 wrangler.jsonc 文件：
// wrangler.jsonc
{
"name": "nextdevkit-cloudflare-template",
"compatibility_flags": ["nodejs_compat"],
// D1 数据库配置
"d1_databases": [
{
"binding": "NEXT_TAG_CACHE_D1",
"database_name": "your-database-name",
"database_id": "<unique-ID-for-your-database>",
"migrations_dir": "drizzle"
}
],
// KV 命名空间配置
"kv_namespaces": [
{
"binding": "NEXT_INC_CACHE_KV",
"id": "<unique-ID-for-your-namespace>"
}
],
}您只需将 database_name、database_id 和 kv_namespaces id 更改为您自己的数据库名称和命名空间 ID。
请不要更改 d1_databases 和 kv_namespaces 的默认绑定名称，如果您想更改名称如 NEXT_TAG_CACHE_D1 为 DB，您需要搜索名称并更新代码以使用新名称。
const { env } = await getCloudflareContext({ async: true });
if (!env.NEXT_TAG_CACHE_D1) {
throw new Error("D1 database not found");
}
dbInstance = drizzle(env.NEXT_TAG_CACHE_D1, { schema, logger: true });
return dbInstance;您需要在全局范围内搜索所有名称以找到绑定名称，并更新代码以使用新名称。
🔧 本地开发设置
1. 创建本地 D1 数据库
在本地开发环境中初始化 D1 数据库：
# 创建本地 D1 数据库
npx wrangler d1 execute your-database-name --local --command='SELECT 1'🗄️ 数据库架构配置
架构定义
D1 使用与 PostgreSQL 相同的架构，但使用 SQLite 语法：
import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
import { relations } from "drizzle-orm";
export const user = sqliteTable("user", {
id: text("id").primaryKey(),
name: text("name").notNull(),
email: text("email").notNull().unique(),
emailVerified: integer("emailVerified", { mode: "timestamp" }),
...
});数据库客户端配置
为 Cloudflare Workers 配置 D1 客户端：
import { drizzle } from 'drizzle-orm/d1';
import * as schema from './schema';
// 对于 Cloudflare Workers
...
// 对于本地开发
...🔄 架构迁移
迁移配置
为 D1 迁移配置 Drizzle：
// drizzle.config.ts
import { defineConfig } from "drizzle-kit";
export default defineConfig({
...
});迁移命令
pnpm run db:generate
pnpm run db:migrate:dev
pnpm run db:migrate:prod工作室
如果您想在 cloudflare d1 生产环境中使用 drizzle studio，您可以使用 drizzle chrome 扩展连接到数据库。
🔍 监控和调试
D1 分析
在 Cloudflare 仪表板中监控 D1 性能：
- 查询执行时间
- 数据库大小和使用情况
- 错误率和类型
- 地理性能指标
KV 分析
监控 KV 操作：
- 读/写操作
- 缓存命中率
- 存储使用情况
- 地理分布
🛠️ 故障排除
常见问题
D1 连接错误：
- 验证
wrangler.jsonc中的数据库 ID - 检查绑定名称是否与代码使用匹配
- 确保已应用迁移
KV 访问问题：
- 验证 KV 命名空间 ID
- 检查绑定配置
- 确保适当的权限
迁移失败：
- 查看 SQLite 语法兼容性
- 检查约束违规
- 验证架构更改是否有效
🔗 相关资源
🎯 下一步
现在您了解了数据库架构，深入了解您选择的平台的具体设置：