从零部署 Do-Blog 到 Cloudflare Workers：一份完整的避坑指南

用 Cloudflare Workers + D1 + KV 搭建一个带后台的博客，全程免费，全球加速。

前言

Do-Blog 是一个专为 Cloudflare Workers 设计的博客系统，自带管理后台，支持 Markdown 写作、分类标签、评论、JWT 认证等功能。公开页面采用纯服务端渲染，零客户端 JavaScript，对 SEO 非常友好。

本文记录从克隆仓库到成功登录后台的完整流程，并重点标注几个容易踩坑的配置细节。

环境准备

在开始之前，确认本地具备以下条件：

Node.js >= 18
Cloudflare 账户（免费套餐即可）
Git（用于克隆仓库）
Wrangler CLI >= 3.0（通过 npx 调用，无需全局安装）

第一步：克隆仓库并安装依赖

git clone https://github.com/Hello-Application-XH/Do-Blog.git
cd Do-Blog
npm install --legacy-peer-deps

--legacy-peer-deps 是必要的。wrangler@4.148.0 要求 @cloudflare/workers-types 为 ^5.x 版本，但项目默认锁定的是 ^4.x，直接 npm install 会因 peer 依赖冲突而失败。

如果克隆时遇到 TLS 握手错误，可以尝试切换 SSL 后端：

git config --global http.sslBackend openssl

或使用镜像加速：

git clone https://ghfast.top/https://github.com/Hello-Application-XH/Do-Blog.git

第二步：登录 Cloudflare

npx wrangler login

浏览器会自动打开完成 OAuth 授权，成功后终端显示 Successfully logged in.

第三步：创建 D1 数据库

npx wrangler d1 create Do-Blog

执行后会输出一个 database_id，复制这个值，稍后填入 wrangler.toml。

第四步：创建 KV 命名空间

npx wrangler kv namespace create DO-BLOG

同样会输出一个 id，复制保存。

第五步：配置 wrangler.toml

这是整个部署过程中最容易出错的一步。打开项目根目录的 wrangler.toml，按以下内容配置：

name = "doblog"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

[vars]
BLOG_ENV = "production"

[[d1_databases]]
binding = "DB"
database_name = "Do-Blog"
database_id = "你的D1数据库UUID"

[[kv_namespaces]]
binding = "BLOG_KV"
id = "你的KV命名空间ID"

[triggers]
crons = ["*/5 * * * *"]

关键提醒：binding 的值必须与代码中使用的变量名完全一致。

Do-Blog 代码里访问数据库用的是 env.DB，访问 KV 用的是 env.BLOG_KV。所以：

D1 的 binding 必须是 "DB"，不能写成 "Do-Blog" 或其他名字
KV 的 binding 必须是 "BLOG_KV"，不能写成 "DO_BLOG"

database_name 和 id 才是资源的真实名称和 ID，它们和 binding 是两回事。很多部署失败都是因为把这两个概念混用了。

第六步：初始化数据库

# 创建表结构
npx wrangler d1 execute Do-Blog --remote --file=schema.sql

# 写入初始数据（管理员账户、默认设置、默认分类）
npx wrangler d1 execute Do-Blog --remote --file=seed.sql

这一步会创建 9 张表和 10 个索引，并写入默认管理员账户。

验证是否成功：

npx wrangler d1 execute Do-Blog --remote --command="SELECT COUNT(*) FROM users;"

如果返回用户表的记录数而不是报错，说明初始化成功。你也可以用 npx wrangler d1 list 查看数据库的 num_tables 字段，确认不再是 0。

第七步：设置 JWT 密钥

npx wrangler secret put JWT_SECRET

终端会提示输入密钥值，粘贴一个 32 位以上的随机字符串。可以用下面的命令生成：

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

第八步：部署

npx wrangler deploy

部署完成后，终端会返回一个 *.workers.dev 的 URL，那就是你的博客地址。

第九步：登录后台

访问 你的URL/admin，默认管理员账户是 admin，首次登录时输入的密码会被系统用 PBKDF2-SHA256 哈希后存储。

重要提示：这个密码设置是一次性的，后续修改只能通过 D1 数据库操作。所以首次登录时请务必设置一个强密码。

常见问题排查

部署时报错 `KV namespace '<YOUR_KV_NAMESPACE_ID>' is not valid`

说明 wrangler.toml 里的 KV id 还是占位符。执行 npx wrangler kv namespace list 获取真实 ID 并替换。

登录时提示"网络错误"，日志显示 `Cannot read properties of undefined (reading 'prepare')`

这是 env.DB 为 undefined 的典型表现，根源是 wrangler.toml 里的 binding 名称写错了。检查 D1 的 binding 是否为 "DB"，KV 的 binding 是否为 "BLOG_KV"。

数据库 `num_tables` 显示为 0

说明 schema.sql 没有执行成功。重新执行第六步的初始化命令。

修改配置后问题依旧

wrangler.toml 的修改需要重新部署才能生效。执行 npx wrangler deploy 后，新配置才会应用到线上 Worker。

查看实时日志

排查服务器端错误最直接的方式：

npx wrangler tail

保持这个窗口打开，然后去页面触发操作，终端会实时打印 Worker 的日志和报错堆栈。

结语

Do-Blog 的部署流程本身并不复杂，主要的坑集中在 wrangler.toml 的绑定配置上。只要记住 binding 是代码里的变量名、必须和源码一致，database_name / id 才是资源的真实标识，基本就能顺利跑起来。

部署成功后，你可以从修改前端 SSR 模板的 CSS 和 HTML 结构入手，把它改造成自己喜欢的视觉风格。

前言