Twikoo评论系统

帖前引言
本博客接入Twikoo评论系统部署

一、背景与结论

本博客是一个 Astro 项目，本身已内置两个评论系统的前端组件：Twikoo 和 Waline（位于 src/components/comment/）
服务托管在 Cloudflare Workers 上
结论：选用 Twikoo。 它是专为 Serverless 设计的评论系统，后端可以原生跑在 Cloudflare Workers 上（D1 存数据 + R2 存图片），冷启动 < 0.5s

二、为什么选 Twikoo 而不是 Waline

对比项	Twikoo	Waline
后端架构	Serverless 函数，可跑在 Cloudflare Workers	Node.js / Express 服务端
Cloudflare Workers 支持	✅ 官方文档列出的部署方式之一	❌ 官方明确表态不支持（架构与 Workers 不兼容）
数据存储	D1（SQLite）	LeanCloud
部署难度	低（wrangler 一条命令）	需 Vercel / Netlify / Docker
自带管理后台	✅	✅

Waline 若要上 Workers，只能靠社区重写项目（如 Waline_On_Worker），非官方、无保障，故放弃

三、部署 Twikoo 后端到 Cloudflare Workers

选用项目：bluerosion/twikoo-cloudflare（Workers + D1 + R2）

部署步骤

1
# 1. 拉取项目并安装依赖
2
git clone https://github.com/bluerosion/twikoo-cloudflare.git ~/git/twikoo-cloudflare
3
cd ~/git/twikoo-cloudflare && npm install
4

5
# 2. 精简依赖（Workers 免费版有 1MiB 包大小限制，清掉不兼容的包）
6
echo "" > node_modules/jsdom/lib/api.js
7
echo "" > node_modules/tencentcloud-sdk-nodejs/tencentcloud/index.js
8
echo "" > node_modules/nodemailer/lib/nodemailer.js
9

10
# 3. 登录 Cloudflare
11
npx wrangler login
12

13
# 4. 创建 D1 数据库，把输出的 database_name / database_id 填入 wrangler.toml
14
npx wrangler d1 create twikoo
15

16
# 5. 初始化数据表结构
17
npx wrangler d1 execute twikoo --remote --file=./schema.sql
18

19
# 6. 创建 R2 存储桶（评论图片上传用）
20
npx wrangler r2 bucket create twikoo
21
#    然后把 R2 域名填入 wrangler.toml 的 R2_PUBLIC_URL
22

23
# 7. 部署
24
npx wrangler deploy --minify

部署成功验证

浏览器访问 Worker 地址，应返回：

1
{"code":100,"message":"Twikoo 云函数运行正常","version":"1.6.40"}

这个地址（含 https:// 前缀）就是前端要填的 envId。

四、踩坑记录

坑 1：R2 未开通 —— `[code: 10042]`

报错现象

1
✘ [ERROR] A request to the Cloudflare API (/accounts/.../r2/buckets) failed.
2
  Please enable R2 through the Cloudflare Dashboard. [code: 10042]

原因：Cloudflare 账号还没有激活 R2 服务，只是安装了 wrangler，API 调用被拒绝。

解决：

登录 dash.cloudflare.com
进入账号级（Account），左侧导航点 R2 Object Storage
走激活流程（一般要求添加付款方式，免费额度内不扣费，免费档含 10GB 存储）
激活后重跑：npx wrangler r2 bucket create twikoo

备选方案：不想绑付款方式的话，改用 whq12520/twikoo-cf-workers（D1 + KV，无需 R2）。

坑 2：D1 绑定名错误 —— `Cannot read properties of undefined (reading 'prepare')`

报错现象

1
{"code":1000,"message":"Cannot read properties of undefined (reading 'prepare')"}

访问 Worker 地址时返回这个 JSON。

原因：把 wrangler.toml 里的 D1 binding 从 "DB" 改成了 "twikoo"，而代码里读取的是 env.DB（src/index.js:352 的 setDb(env.DB)）。绑定名对不上 → env.DB 为 undefined → 一执行 DB.prepare(...) 就抛 reading 'prepare'。

解决：把 wrangler.toml 里 binding 改回 DB，然后重新部署：

1
npx wrangler deploy --minify

如果重新部署后报 no such table: comment，说明 schema.sql 还没执行：
Terminal window
1
npx wrangler d1 execute twikoo --remote --file=./schema.sql

关键认知（避免再踩）：binding、database_name、database_id 是三个不同的东西：

字段	含义	本项目的值
`binding`	代码里读的变量名，必须叫 `DB`，不能改	`DB`
`database_name`	数据库展示名	`twikoo`
`database_id`	实际指向哪个 D1 库	（部署时生成的 UUID）

五、博客前端集成

修改博客项目的 twilight.config.yaml后重新构建并部署 Astro 站点：

1
pnpm build

六、注意事项与扩展

路径斜杠：Twikoo Workers 版不会自动归一化 /post/ 与 /post。项目前端已做去尾斜杠处理（twikoo.astro 的 getCurrentPath()），已规避。
前端版本：本地前端是 1.6.9，后端是 1.6.x，一般兼容；若接口异常可考虑把本地 twikoo.all.min.js 更新到与后端接近的版本。
同域优化：建议把 Worker 通过 Cloudflare 路由挂到站点同域名下（如 yourdomain.com/twikoo/*），省掉跨域预检，降低配额消耗。
邮件通知：因 nodemailer 与 Workers 不兼容，走 SendGrid / MailChannels 的 HTTPS API（SendGrid 免费档每天 100 封）。
已知限制（该 CF 部署项目）：process.env 不可用、腾讯云无法集成、IP 归属地仅英文、分页一次返回当前页全部评论、反垃圾仅支持 Cloudflare Turnstile。

J i y ' s 数 字 花 园

一、背景与结论

二、为什么选 Twikoo 而不是 Waline

三、部署 Twikoo 后端到 Cloudflare Workers

部署步骤

部署成功验证

四、踩坑记录

坑 1：R2 未开通 —— [code: 10042]

坑 2：D1 绑定名错误 —— Cannot read properties of undefined (reading 'prepare')

五、博客前端集成

六、注意事项与扩展

坑 1：R2 未开通 —— `[code: 10042]`

坑 2：D1 绑定名错误 —— `Cannot read properties of undefined (reading 'prepare')`