官方教程：

https://twikoo.js.org
https://twikoo.js.org

📋 教程概览

  • 完全免费：Vercel 提供充足的免费额度，MongoDB Atlas 提供 500 MiB 永久免费数据库
  • 功能完整：支持回复、点赞、邮件通知、表情包、反垃圾等
  • 维护简单：无需自备服务器，无需操心运维

🔧 一、准备阶段

1.1 注册 GitHub 账号

Twikoo 一键部署需要关联 GitHub 账号。访问 GitHub 注册账号（这个应该都有了跳过）。

1.2 注册 Vercel 账号

访问 Vercel，点击 Sign Up，选择 Continue with GitHub，使用 GitHub 账号授权登录即可。

1.3 注册 MongoDB Atlas 账号

访问 MongoDB Atlas 注册账号。推荐直接使用 Sign in with Google 或 Sign in with GitHub 快速登录，无需单独设置密码。

🗄️ 二、创建 MongoDB 数据库

2.1 创建免费集群

登录 MongoDB Atlas 后进入控制台，按以下步骤操作：

  1. 点击 Create Cluster 或 Build a Database 按钮
  2. 在 Shared Clusters（免费）区域点击 Create a cluster（标签为 FREE 的那一档）
  3. 选择云服务商：推荐选择 AWS
  4. 区域选择：推荐选择 Oregon (us-west-2)。该数据中心基建成熟、故障率低，且使用清洁能源。如果希望更低延迟，也可以选择离 Vercel 后端较近的区域。
  5. 保持其他默认设置，点击 Create Cluster 创建集群

创建过程大约需要 1-3 分钟。

2.2 设置数据库用户

集群创建完成后：

  1. 左侧菜单点击 Database Access
  2. 点击 Add New Database User
  3. Authentication Method 选择 Password
  4. 填写 Username 和 Password：
    • 用户名建议使用 twikooUser 或类似名称
    • 密码可使用下方的 Auto Generate 自动生成一个强壮密码（不含特殊字符），务必复制保存！
  5. 在 Database User Privileges 下方点击 Add Built In Role，选择 Atlas Admin（赋予该用户全部读写权限）
  6. 点击 Add User

2.3 配置网络白名单

  1. 左侧菜单点击 Network Access
  2. 点击 Add IP Address
  3. 在 Access List Entry 中输入 0.0.0.0/0（允许所有 IP 地址连接）
  4. 点击 Confirm 保存

💡 说明：Vercel 部署的云函数出口 IP 地址不是固定的，无法预先指定单一 IP，因此使用 0.0.0.0/0 是最简单可靠的方式。若担心安全问题，可后续通过 MongoDB 的 IP 白名单功能进一步限制。

2.4 获取数据库连接字符串

  1. 左侧菜单点击 Database（或 Clusters）
  2. 在集群列表中找到刚创建的免费集群，点击 Connect 按钮
  3. 选择 Drivers
  4. 复制显示的连接字符串，格式类似：
    1
    mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
  5. 重要：将连接字符串中的 <username> 和 <password> 替换为你在 2.2 步设置的实际用户名和密码
    • 替换后格式示例：mongodb+srv://twikooUser:YourPassword123@cluster0.xxxxx.mongodb.net/...

将这份连接字符串妥善保存，下一步会用到。

🚀 三、部署 Twikoo 到 Vercel

3.1 一键部署

使用 Twikoo 官方提供的 Vercel 一键部署模板：

一键部署

点击后会自动跳转到 Vercel，按以下步骤操作：

  1. 如果未登录，Vercel 会要求登录（使用 GitHub 账号）
  2. 点击 Continue 继续
  3. 在 Configure Project 页面，保持默认设置，点击 Deploy

3.2 配置环境变量

部署完成后，进行以下配置：

  1. 进入 Vercel 控制台，点击刚创建的 Twikoo 项目

  2. 左侧菜单选择 Environment Variables

  3. 添加以下环境变量：

Key Value
MONGODB_URI 上一步获取并替换过的 MongoDB 连接字符串
  1. 点击 Save 保存

⚠️ 注意：变量名是 MONGODB_URI（不是 MONGODB_URL 或其他写法），请仔细核对。

3.3 关闭 Vercel Authentication（重要！）

新部署的 Vercel 环境默认启用了一项名为 “Vercel Authentication” 的功能，该功能会阻止 Twikoo 的邮件通知正常发送。

  1. 在项目 Settings 中，左侧菜单选择 Deployment Protection

  2. 找到 Vercel Authentication 选项，设置为 Disabled

  3. 点击 Save 保存

3.4 重新部署

  1. 顶部选项卡点击 Deployments
  2. 在部署记录列表的最右侧，点击三个点图标（⋯）
  3. 选择 Redeploy，确认 Redeploy
  4. 等待约 30 秒，部署状态变为 Ready

3.5 验证部署是否成功

  1. 顶部选项卡点击 Overview

  2. 找到 Domains 区域，点击 Vercel 自动分配的域名（形如 twikoo-xxx.vercel.app）

  3. 如果页面显示 “Twikoo 云函数运行正常” 或类似成功提示，说明后端部署成功！

🌐 四、绑定自定义域名（可选但推荐）

💡 为什么需要绑定自定义域名？ Vercel 默认的 *.vercel.app 域名在中国大陆部分地区访问速度较慢甚至无法访问。绑定自己的域名可以显著提升访问速度，且绑定的域名可以走国内 CDN 加速。

4.1 在 Vercel 中添加域名

  1. 进入项目 Settings → Domains

  2. 在输入框中输入你要绑定的域名（如 twikoo.yourdomain.com）

  3. 点击 Add

  4. 点击learn more -> Manual setup，Vercel 会显示一条 CNAME 记录值，记录下来

4.2 配置 DNS

  1. 登录Cloudflare
  2. 添加一条 CNAME 记录（上一步生成的值）：
    • 主机记录：填写子域名前缀（如 twikoo 或 comment）
    • 记录类型：CNAME
    • 记录值：Vercel 提供的那条值（类似 cname.vercel-dns.com）
  3. 保存后等待 DNS 生效（通常几分钟到几小时）

4.3 验证域名

  1. 返回 Vercel Domains 页面
  2. 等待两个绿色对勾出现（一个表示 DNS 解析成功，一个表示 SSL 证书下发成功）
  3. 访问你的自定义域名，应该能正常看到 Twikoo 成功提示页面（步骤3.5同样的界面）

📝 五、前端集成到博客

5.1 在 Hexo Butterfly 主题中集成

  1. 找到配置文件_config.stellar.yml中的comments（250行附近）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
######## Comments ########
comments:
  service: # beaudar, utterances, giscus, twikoo, waline, artalk
  comment_title: 快来参与讨论吧~
  lazyload: false # true / false
  custom_css: # artalk,twikoo,... 可以为没有全局启用的评论加载自定义样式
  # beaudar
  # https://beaudar.lipk.org/
  beaudar:
    repo: xxx/xxx
    ·
    ·
    ·
  # Twikoo
  # https://twikoo.js.org/
  twikoo:
    js: https://gcore.jsdelivr.net/npm/twikoo@1.6/dist/twikoo.all.min.js # 建议锁定版本
    envId: https://xxx # vercel函数

  # Waline
  # https://waline.js.org/
  waline:
    js: https://gcore.jsdelivr.net/npm/@waline/client@3.1/dist/waline.js
    ·
    ·
    ·
  1. 主要更改的字段为service和twikoo如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
comments:
  service: twikoo #(改成twikoo) beaudar, utterances, giscus, twikoo, waline, artalk
  comment_title: 快来参与讨论吧~
  lazyload: false # true / false
  custom_css: # artalk,twikoo,... 可以为没有全局启用的评论加载自定义样式
  ·
  ·
  ·
  # Twikoo
  # https://twikoo.js.org/
  twikoo:
    js: https://gcore.jsdelivr.net/npm/twikoo@1.6/dist/twikoo.all.min.js # 建议锁定版本
    envId: https://twikoo.example.com # 改成你绑定的域名

🔐 六、后台管理配置

6.1 设置管理员密码

  1. 重新构建你的博客，在博客的文章下面就能看到评论组件了。
  2. 点击组件右下角的设置，注册管理员，通过这个账号可以管理你的评论和配置邮件通知功能。

📚 参考链接

如果在部署过程中遇到任何问题，欢迎评论区留言！

许可协议

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。

分享文章

快来参与讨论吧~