blog.dopana

返回

运行 wrangler dev 时,Cloudflare 的 D1 数据库立刻出现在本地。但底层发生了什么?本文深入讲解 EmDash 如何在本地开发环境中处理 SQLite3 和 API。

1. 本地开发概览#

本地开发环境本地生产本地生产浏览器http://localhost:4321Astro Dev ServerNode.jsEmDash RuntimeDB Adapterbetter-sqlite3data.dbCloudflare D1env.DBStorage Adapter本地文件系统./uploadsCloudflare R2env.MEDIA

2. Miniflare:本地 D1 模拟器#

运行 wrangler dev 会启动 Miniflare(Cloudflare 的本地模拟器)。

Miniflare 工作原理#

wrangler dev初始化 Miniflare创建 .sqlite 文件读写数据提供 Worker Runtimelocalhost:4321 就绪开发者wrangler devMiniflareSQLite3 文件开发者wrangler devMiniflareSQLite3 文件

SQLite 文件结构#

.wrangler/
  state/
    v3/
      d1/
        miniflare-D1DatabaseObject/
          <hash>.sqlite          # 数据库文件
          <hash>.sqlite-shm      # 共享内存(WAL)
          <hash>.sqlite-wal      # Write-Ahead Log
text
文件作用
<hash>.sqlite实际的 SQLite 数据库
<hash>.sqlite-shmWAL 模式的共享内存
<hash>.sqlite-wal预写日志(并发控制)

[!NOTE] <hash> 是从 database_id 派生的 HMAC 十六进制哈希。相同 Binding ID 总是映射到相同哈希。

WAL 模式的优势#

默认使用 WAL(Write-Ahead Logging)模式:

  • 读写可以同时进行
  • 写入不会阻塞读取
  • 与生产环境 D1 使用相同模式

直接访问本地 DB#

用外部工具打开 SQLite 文件:

# SQLite CLI 连接
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite

# Beekeeper Studio、SQLiteFlow 等也可以直接连接
bash

3. EmDash 的两种 DB 适配器#

EmDash 在 astro.config.mjs 中指定 DB 适配器。本地和生产使用不同的适配器。

本地开发:sqlite() 适配器#

astro.config.mjs(本地开发)
import emdash from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
  integrations: [
    emdash({
      database: sqlite({
        url: "file:./data.db",  // 本地 SQLite 文件
      }),
    }),
  ],
});
js

生产环境:d1() 适配器#

astro.config.mjs(生产)
import emdash from "emdash/astro";
import { d1 } from "emdash/db";

export default defineConfig({
  integrations: [
    emdash({
      database: d1(),  // Cloudflare D1 binding
    }),
  ],
});
js

对比#

项目本地(sqlite())生产(d1())
引擎better-sqlite3Cloudflare D1
存储data.db 文件Cloudflare 基础设施
事务SQLite 标准batch() API
并发写入单写入者(SQLite 限制)Cloudflare 管理
Schema共享共享

[!TIP] 两个适配器共享 Kysely(SQL 查询构建器)。Schema 和 migrations 在本地和生产之间完全相同。

4. 本地数据流#

GET /postsgetEmDashCollection("posts")SELECT * FROM posts执行 SQL响应数据内容HTML 响应浏览器Astro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 Database浏览器Astro Dev ServerEmDash RuntimeKysely Query BuilderSQLite3 Database

5. EmDash REST API 端点#

EmDash 在 Astro Dev Server 的同一端口提供 API。

本地开发 URL#

http://localhost:4321/_emdash/api/    # REST API
http://localhost:4321/_emdash/admin/  # 管理界面
text

主要 API 端点#

类别端点
内容 CRUDGET/POST /content/{collection}, GET/PUT/DELETE /content/{collection}/{id}
发布管理POST /content/{collection}/{id}/publish, /unpublish, /schedule
媒体GET/POST /media, POST /media/upload-url
SchemaGET/POST /schema/collections
分类GET/POST /taxonomies, GET/POST /taxonomies/{name}/terms
菜单GET/POST /menus, GET/PUT/DELETE /menus/{name}
设置GET/PUT /settings
搜索GET /search, GET /search/suggest, POST /search/rebuild

认证#

# Bearer token 认证
curl -H "Authorization: Bearer $EMDASH_TOKEN" \
  http://localhost:4321/_emdash/api/content/posts

# Session 认证(从管理面板)
# CSRF 保护:需要 X-EmDash-Request: 1 header
bash

OpenAPI 规范#

# 获取 API 规范
curl http://localhost:4321/_emdash/api/openapi.json
bash

6. 种子数据应用#

首次启动时,如果数据库为空,会从 seed/seed.json 应用种子数据。

手动应用#

# 应用 seed 到本地 DB
npx emdash seed seed/seed.json --local

# 导出 schema
npx emdash export-seed > .emdash/seed.json
bash

应用流程#

是否wrangler dev 启动首次请求DB 为空?应用 seed.json正常处理运行 migrations创建 collections创建 taxonomies创建 menus应用 settings

7. 本地 vs 远程:详细对比#

项目本地(SQLite)远程(D1)
引擎better-sqlite3Cloudflare D1
DB 适配器sqlite({ url: "file:./data.db" })d1({ binding: "DB" })
存储适配器local({ directory: "./uploads" })r2({ binding: "MEDIA" })
持久化.wrangler/state/ 或 data.dbCloudflare 基础设施
并发写入单写入者(SQLite 限制)管理型,但仍为单写入者
事务SQLite 标准batch() API
读副本无D1 Sessions API
备份复制 .sqlite 文件wrangler d1 export

8. 开发技巧#

重置数据#

# 删除 SQLite 文件重置
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite
rm .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite-*

# 重启重新创建
wrangler dev
bash

团队共享数据库#

# 持久化到共享目录
wrangler dev --persist-to=./shared-db
bash

查看本地 DB#

# 列出表
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite ".tables"

# 查看数据
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/<hash>.sqlite \
  "SELECT * FROM posts LIMIT 5;"
bash

9. 总结#

组件本地开发行为
Miniflare在 .wrangler/state/ 创建 SQLite3 文件
better-sqlite3连接本地 SQLite 的桥梁
KyselySQL 查询构建器(本地/生产共享)
EmDash API在 /_emdash/api/ 提供 REST API
seed.json首次启动时引导 schema

EmDash + Cloudflare 的本地开发环境用 SQLite3 复现 D1 的 SQL 语义。Miniflare 搭建桥梁,让开发者在本地验证生产环境行为。

参考资料#