hexo next主题 twikoo评论的搭建

发表于 更新于 阅读次数：

hexo 博客想接 twikoo 评论，前后端折腾了一晚上。前端好接，后端在大陆能访问才是真问题。Vercel 部署的后端在大陆连不上，换 Netlify 立刻就通了。完整过程记一下，省得下次再踩。

后端部署

twikoo 后端官方支持多个平台：腾讯云、Vercel、Netlify、Hugging Face、Railway。大陆访问推荐 Netlify，*.netlify.app 域名比 *.vercel.app 稳得多。Vercel 在大陆没边缘节点，DNS 经常被污染直接 RST，浏览器报 ERR_CONNECTION_TIMED_OUT。

Netlify 部署

twikoo 官方有现成模板 twikoojs/twikoo-netlify，fork 到自己 GitHub 账号，然后：

  1. 登录 Netlify → Add new site → Deploy an existing project
  2. 选 fork 出来的仓库，Deploy
  3. 部署后加环境变量 MONGODB_URI（MongoDB Atlas 免费层连接串）
  4. 重新部署

MongoDB Atlas 免费层 M0 有 500MB，存博客评论够用很久。之前 Vercel 用的同一连接串直接复用，评论数据无缝迁移。

验证后端

部署完访问你的 Netlify 域名：

1
https://<你的站点>.netlify.app/.netlify/functions/twikoo

能返回下面这个就说明后端活着：

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

前端接入

装插件

1
npm install hexo-next-twikoo@1.0.3

next 8.4+ 用 1.0.3 这个版本。

前端 JS 自托管

twikoo 前端 JS 默认从 jsdelivr 加载，国内经常被墙。跟 artalk 一样，下载下来放到博客自己托管：

1
2
3
curl -sL "https://registry.npmmirror.com/twikoo/-/twikoo-1.7.19.tgz" -o twikoo.tgz
tar xzf twikoo.tgz
cp package/dist/twikoo.all.min.js source/twikoo/

配置 _config.yml

1
2
3
4
5
6
7
twikoo:
  enable: true
  visitor: true
  # 部署在 Netlify 的 twikoo 后端
  envId: https://<你的站点>.netlify.app/.netlify/functions/twikoo
  # 自托管前端 JS（避免 jsdelivr 国内被墙）
  jsUrl: /twikoo/twikoo.all.min.js

envId 填法因平台而异，这是最容易踩的坑：

平台 envId 填法
Vercel 根 URL，如 https://xxx.vercel.app/
Netlify 必须带完整函数路径 https://xxx.netlify.app/.netlify/functions/twikoo
腾讯云/Zeabur 纯环境 ID，如 twikoo-xxxx

Netlify 只填根域名会 404，必须带 /.netlify/functions/twikoo 后缀。我第一次就栽在这，浏览器报 404 找半天原因。

验证全链路

改完配置重新生成部署，然后：

1
2
3
4
5
6
7
8
9
10
# 1. 后端连通（GET 验活）
curl -sL "https://<你的站点>.netlify.app/.netlify/functions/twikoo"

# 2. 前端 JS 可达
curl -sL "https://你的博客/twikoo/twikoo.all.min.js" -o /dev/null -w "%{http_code} %{size_download}\n"

# 3. 模拟评论 API（POST）
curl -sL -X POST "https://<你的站点>.netlify.app/.netlify/functions/twikoo" \
  -H "Content-Type: application/json" \
  -d '{"event":"COMMENT_GET","url":"https://你的博客/post/","path":"/post/"}'

POST 必须带 event 字段。字段名写错会返回 {"code":1001,"message":"请更新 Twikoo 云函数至最新版本"}，别被这句话误导，不是版本问题，是请求参数不对。

最后浏览器实测一遍：打开文章页，console 里没有 ERR_CONNECTION_TIMED_OUT、能发出评论，就成。

踩坑汇总

  1. Vercel 后端大陆不通：*.vercel.app 大陆没边缘节点，DNS 污染/RST。海外 curl 通没用，得大陆用户实测。
  2. envId 填法：Netlify 必须带 /.netlify/functions/twikoo 完整路径，Vercel 用根 URL，腾讯云用纯 ID。
  3. 前端 JS 别走 jsdelivr：国内被墙，自托管到 source/twikoo/。
  4. 前后端版本要一致：前端 1.7.19 就配后端 1.7.19，不一致会出怪问题。
  5. POST 参数：event 字段名要写对，写错被误导成版本问题。

备选方案

如果 Netlify 也不稳，还有几条路：

  • 腾讯云函数 SCF：国内访问最快（< 100ms），但要走腾讯云配置流程
  • 自建 VPS Docker：最可控，参考 artalk 模式，docker 起 twikoo 官方镜像 + 反代
  • Hugging Face：社区推荐，但默认邮件端口被屏蔽

数据都在 MongoDB Atlas 里，切平台只是换入口，评论一条不丢。