Hexo Butterfly 建站实录：视觉优化与 Twikoo 评论系统

本文合并了原来的 Butterfly 美化记录与 Twikoo 部署教程，先解决阅读体验，再解决评论与互动。

为什么选 Twikoo

Hexo Butterfly 支持的评论系统很多，选 Twikoo 的理由很简单：

Butterfly 社区首选 — 教程多、踩坑成本低，遇到问题搜一下就能找到答案
MongoDB Atlas 免费 512MB — 纯文本评论用一辈子，且还在接受新用户（LeanCloud 已经对新用户关门了）
Vercel 一键部署 — 不用买服务器，不用写一行后端代码
访客无需登录 — 填个昵称就能评论，对国内读者友好
内嵌管理面板 — 直接在评论区里管理，不用切到独立后台

全套方案完全免费，唯一的硬性要求是有个自定义域名——后面会说为什么。

整体架构

用户浏览器 ──→ 你的博客 (GitHub Pages)
                 │
                 ├── 加载 twikoo JS (jsdelivr CDN)
                 │
                 └── POST 请求 ──→ twikoo.你的域名.com (Vercel)
                                      │
                                      └── 读写数据 ──→ MongoDB Atlas (免费集群)

Twikoo 的前端 JS 通过 CDN 加载，后端跑在 Vercel 的无服务器函数上，数据存在 MongoDB Atlas 免费的共享集群里。三样东西各自免费，合在一起就是个完整的评论系统。

第一步：注册 MongoDB Atlas，创建免费集群

打开 MongoDB Atlas，用 GitHub 账号登录。

创建项目与集群

点击右侧菜单的 Project Overview，创建一个新的项目
在项目中按指引创建数据库集群：
- 部署类型选 M0 Free（免费层）
- 云服务商选 AWS，区域选 Hong Kong（离国内最近、延迟最低）
- 其他选项保持默认，点击 Create Cluster，等待约 2 分钟就绪

创建数据库用户

左侧菜单 → Database Access → Add New Database User：

Authentication Method：Password
Username：填 twikoo_admin（自己记住就行）
Password：点击 Autogenerate Secure Password，立刻复制保存！丢了只能重置
Privileges：选 Atlas admin（这一步千万别漏，权限不够后面会报认证错误）

配置网络白名单

左侧 → Network Access → Add IP Address → 选择 Allow Access from Anywhere（即 0.0.0.0/0）。

⚠️ 为什么必须放通所有 IP？ Vercel 的出口 IP 不固定，无法预知具体地址。如果只开放特定 IP，Twikoo 迟早会因为 IP 轮换而连不上 MongoDB，到时你的评论区就挂了。

获取连接字符串

回到 Clusters → 点击 Connect → 选择 Drivers → 你会看到：

1	mongodb+srv://twikoo_admin:<db_password>@cluster0.abcde.mongodb.net/?retryWrites=true&w=majority

把 <db_password> 替换成刚才保存的密码。注意：密码里如果有特殊字符，必须做 URL 编码：

字符	替换
`@`	`%40`
`:`	`%3A`
`/`	`%2F`
`+`	`%2B`
`#`	`%23`
`%`	`%25`

这串最终就是 MONGODB_URI，先存记事本里，后面马上要用。

第二步：Vercel 一键部署 Twikoo

打开以下链接一键部署（或访问 Twikoo 官方文档找最新链接）：

1	https://vercel.com/import/project?template=https://github.com/twikoojs/twikoo/tree/main/src/server/vercel-min

GitHub 授权登录 → 填仓库名（任意名称，会自动创建） → Create。等待约 1 分钟部署完成。

配置环境变量

⚠️ 这是最容易翻车的步骤，请仔细看。

进入 Dashboard → Settings → Environment Variables，添加：

Key	Value
`MONGODB_URI`	你刚构造的那串 MongoDB 连接字符串

注意 Key 是 MONGODB_URI，不是 MONGODB_URL，也不要有其他变体——差一个字母都不行。

关闭 Vercel 身份验证

Settings → Deployment Protection → 把 Vercel Authentication 设为 Disabled。

⚠️ 不关掉的话，其他人访问你的评论接口会被 Vercel 的登录框挡住，直接返回 401。

重新部署

以上配置改完不会自动生效。必须去 Deployments → 最新一条右侧点 … → Redeploy。好消息是，通常改完配置后右下角会出现 Redeploy 提示按钮，点一下就行。

记住一个规律：每次改环境变量都要 Redeploy，这是 Vercel 的机制，忘了这一步是新手最常见的坑。

第三步：绑定自定义域名（关键！）

*.vercel.app 域名在国内 DNS 污染严重，不绑自定义域名几乎等于白部署。

DNS 添加 CNAME 记录

去你域名所在的 DNS 管理后台（阿里云 / 腾讯云 / Cloudflare 等），添加一条：

记录类型	主机记录	记录值
CNAME	`twikoo`	`cname.vercel-dns.com`

如果你的域名在国内注册且主要面向国内读者，推荐用 cname-china.vercel-dns.com，访问更快。

Vercel 端绑定

Settings → Domains → 输入 twikoo.lkl-zero.top → Add。等待验证通过（出现两个绿色对号）即生效，Vercel 会自动签发 SSL 证书。

第四步：验证后端部署

在 Vercel 的 Overview 页面点击预览你的项目域名，如果返回以下 JSON 说明部署成功：

{
  "code": 100,
  "message": "Twikoo 云函数运行正常，请参考 https://twikoo.js.org/frontend.html 完成前端的配置",
  "version": "1.7.11"
}

只要看到 "Twikoo 云函数运行正常" 就行，版本号可能不同。

第五步：Butterfly 主题配置

编辑 _config.butterfly.yml：

comments:
  use: Twikoo
  text: true

twikoo:
  envId: https://twikoo.lkl-zero.top   # 你的 Twikoo 后端地址
  region:
  visitor: true                          # 用 Twikoo 统计文章阅读量
  option:
    path: window.location.pathname       # 按路径区分不同页面的评论

执行 hexo clean && hexo generate && hexo deploy 部署上线。

第六步：注册管理员

有两种方式，推荐方式一：

方式一：环境变量（推荐）

Vercel → Settings → Environment Variables → 添加：

Key	Value
`TWIKOO_ADMIN_PASS`	你设的管理员密码

然后 Redeploy。之后在博客评论区点击右下角小齿轮 ⚙️，输入密码即可进入管理面板。

方式二：首次访问设置

部署后第一个打开评论区的人可以设置密码。但取决于 Twikoo 版本，不一定可靠，不建议依赖这种方式。

踩坑实录：我遇到的 5 个真实错误

坑 1：未设置环境变量

返回 {"code":1000,"message":"未设置环境变量 MONGODB_URI"}。

原因：环境变量没填，或者 Key 写错了。Key 必须是 MONGODB_URI，MONGODB_URL、MONGO_URI 都不行。而且填完后必须 Redeploy 才能生效。

解决：检查 Key 拼写，点 Redeploy。

坑 2：SSL 握手失败

返回内容包含：

1	error:0A000438:SSL routines:ssl3_read_bytes:tlsv1 alert internal error

原因：Network Access 没加 0.0.0.0/0 白名单，Vercel 的 IP 被 MongoDB Atlas 拒绝了。

解决：MongoDB Atlas → Network Access → 添加 0.0.0.0/0，然后 Vercel Redeploy。

坑 3：认证失败

返回 {"code":1000,"message":"bad auth : authentication failed"}。

原因：连接字符串里的用户名或密码与实际不符。常见情况：

密码里的特殊字符（如 @、#、%）没有做 URL 编码
混淆了 MongoDB Atlas 的登录密码和数据库用户密码——连接字符串里用的必须是后者
数据库用户的权限不够（创建用户时必须选 Atlas admin）

解决：去 Database Access 删掉旧用户，重新建一个，生成新密码替换连接字符串，确认权限选了 Atlas admin。

另外注意：直接用浏览器访问 https://twikoo.你的域名.com/ 时，由于请求头里没有携带身份信息，返回的内容不能直接反映后端真实状态。排查这类问题建议在 Vercel 的部署日志中查看。

坑 4：CORS 跨域 —— 评论区一片空白

本地 hexo server 测试时，评论区不显示，F12 Console 报错：

1 2	Access to XMLHttpRequest at 'https://twikoo.你的域名.com/' from origin 'http://localhost:4000' has been blocked by CORS policy

原因：Vercel Authentication 没关，后端收到请求先弹登录框，CORS 头没返回，浏览器直接拦截。

解决：Settings → Deployment Protection → Disabled → Redeploy。关掉开关不会自动生效，必须 Redeploy。

坑 5：不蒜子 502 干扰调试

跟 Twikoo 本身无关，但在你调试评论区的时候，Console 里不蒜子（busuanzi.ibruce.info）的 502 红色报错很碍眼，容易让你怀疑是不是评论系统出了问题。

解决：直接关掉不蒜子，顺便用 Twikoo 的 visitor: true 接管页面访问统计，一举两得。

busuanzi:
  site_uv: false
  site_pv: false
  page_pv: false

总结

步骤	关键点
MongoDB	区域选 Hong Kong，用户给 Atlas admin 权限（别忘了），白名单放 `0.0.0.0/0`
连接字符串	特殊字符必须 URL 编码，密码是数据库用户密码不是登录密码
Vercel	环境变量填 `MONGODB_URI`，关掉 Vercel Authentication，每次改动必须 Redeploy
自定义域名	国内必须绑，推荐用 `cname-china.vercel-dns.com`
Butterfly	`envId` 填完整 HTTPS 地址，`visitor: true` 顺带做阅读统计

整个过程不花一分钱，熟悉后 15 分钟能搞定——前提是不踩坑。希望这篇能帮你把坑绕过去。

阅读体验优化

评论系统之外，这个博客还做了几项克制的 Butterfly 调整。原则是帮助阅读，而不是继续叠加动画。

首页摘要

首页只显示人工编写的短摘要，不再自动截取 500 字正文。摘要应该回答“这篇文章解决什么问题、读者能得到什么”，代码和目录留到详情页。

导航与内容分层

主导航从“归档、标签、分类”改为“项目、专题、笔记”。归档仍然可以保留，但不再作为新访客的第一入口。项目页展示完整成果，专题页组织可连续阅读的文章，笔记页收纳短问题和开发记录。

代码块与交互

保留 Mac 风格代码块和清晰的行号；
点击涟漪只作为轻量反馈，不遮挡正文；
固定导航栏，长文中依靠目录定位；
默认暗色模式应尊重用户选择，并保证代码对比度；
预加载动画只在首次加载短暂出现，避免每次 PJAX 切换都打断阅读。

侧栏

侧栏保留最近文章、核心分类和少量标签。标签数量过多时，随机标签云会制造噪音，因此只显示受控标签词表中的高频项。

最终检查清单

每次修改主题后至少检查：

首页、文章页和移动端导航；
明暗主题下的正文与代码对比度；
PJAX 切换后评论、目录和自定义脚本是否重新初始化；
Twikoo 自定义域名、CORS 和环境变量；
hexo clean && hexo generate 是否产生重复路由或失效链接。

建站优化的终点不是“效果全开”，而是让读者更快找到内容、读完内容并愿意交流。