1873 字
5 分钟
Twikoo 评论系统部署到 Vercel 完整教程
2026-04-22

前言#

Twikoo 是一个简洁、安全的静态网站评论系统,支持匿名评论、邮件通知等功能。本文将详细介绍如何将 Twikoo 部署到 Vercel。

前置准备#

在开始之前,您需要准备以下内容:

  • ✅ 一个 Vercel 账号(如果没有,可以免费注册)
  • ✅ 一个 GitHub 账号(用于托管代码)
  • ✅ 一个数据库(MongoDB 或其他支持的数据库)
  • ✅ 基础的 Git 操作知识

第一步:准备数据库#

选项 1:使用 MongoDB Atlas(推荐免费)#

  1. 访问 MongoDB Atlas
  2. 注册并登录账号
  3. 创建免费的 M0 集群
  4. 配置 IP 白名单(允许 0.0.0.0/0)
  5. 创建数据库用户
  6. 获取连接字符串,格式如下:
mongodb+srv://username:password@cluster0.mongodb.net/twikoo

选项 2:使用 MongoDB Community Server#

  1. 在本地或云服务器安装 MongoDB
  2. 配置数据库
  3. 获取连接字符串

第二步:部署 Twikoo#

方法一:一键部署到 Vercel(推荐)#

  1. 访问 Twikoo 的 GitHub 仓库:twikoo/twikoo
  2. 点击「Deploy to Vercel」按钮
  3. 按照 Vercel 的指引完成部署
  4. 配置环境变量

方法二:手动部署#

  1. Fork Twikoo 仓库
  2. 登录 Vercel 并导入您的仓库
  3. 配置项目设置
  4. 添加环境变量
  5. 部署项目

第三步:配置环境变量#

部署时需要设置以下环境变量:

环境变量说明示例
MONGODB_URIMongoDB 连接字符串mongodb+srv://...
TWIKOO_ENV运行环境production
TWIKOO_PORT服务端口(可选)8080
TWIKOO_SECRET密码加盐(可选,随机字符串)your-secret-key

第四步:获取环境 ID#

部署完成后:

  1. 访问您的 Vercel 项目地址
  2. 在 Twikoo 管理后台中获取环境 ID
  3. 记录这个环境 ID,用于前端配置

环境 ID 格式示例:

https://your-twikoo-project.vercel.app

第五步:状态检查#

部署完成后,需要检查 Twikoo 是否正常运行。

方法一:浏览器访问检查#

  1. 打开浏览器
  2. 访问您的 Twikoo 地址:https://your-twikoo-project.vercel.app
  3. 查看是否显示 Twikoo 界面

✅ 正常状态: 显示 Twikoo 评论框或管理后台界面

❌ 异常状态: 页面报错或显示空白

方法二:API 接口检查#

在浏览器控制台执行以下命令:

// 检查 Twikoo API 状态
fetch('https://your-twikoo-project.vercel.app/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ event: 'GET' })
})
.then(res => res.json())
.then(console.log)
.catch(console.error);

✅ 正常响应示例:

{
"status": 0,
"data": {
"version": "1.6.x"
}
}

方法三:Vercel 日志检查#

  1. 登录 Vercel Dashboard
  2. 选择您的 Twikoo 项目
  3. 点击「Logs」查看部署日志
  4. 检查是否有错误信息

✅ 正常日志: 显示 Twikoo started successfully 或类似信息

❌ 异常日志: 显示 MongoDB 连接错误、环境变量缺失等

常见状态码#

状态码含义解决方案
status: 0正常运行✅ 无需处理
status: 10001数据库连接失败检查 MongoDB URI
status: 10002环境变量缺失检查环境变量配置
status: 10003权限验证失败检查 TWIKOO_SECRET
status: 500服务器内部错误查看 Vercel 日志

网站活动检查#

部署完成后,除了检查 Twikoo 本身的状态,还需要检查您的网站是否正常运行。

1. 检查博客评论功能#

在博客文章页面执行以下检查:

// 在浏览器控制台执行
// 检查评论框是否加载
const commentBox = document.querySelector('#twikoo-container');
console.log('评论容器:', commentBox ? '✅ 已找到' : '❌ 未找到');
// 检查 Twikoo 脚本是否加载
console.log('Twikoo 脚本:', typeof twikoo !== 'undefined' ? '✅ 已加载' : '❌ 未加载');

2. 检查评论发送功能#

  1. 打开博客文章页面
  2. 滚动到评论区
  3. 填写评论内容(昵称、邮箱、评论)
  4. 点击提交按钮
  5. 查看是否成功提交

✅ 正常状态: 显示评论内容,提示提交成功

❌ 异常状态: 显示错误信息,或评论不显示

3. 检查评论管理后台#

  1. 访问 Twikoo 管理后台:https://your-twikoo-project.vercel.app
  2. 登录管理员账号
  3. 查看是否能看到刚才的评论

✅ 正常状态: 评论列表中显示新提交的评论

4. 博客评论状态检测脚本#

在浏览器控制台执行以下脚本,检查博客评论功能是否正常:

// 博客评论功能检测脚本
(async () => {
const TWIKOO_ENV_ID = 'https://your-twikoo-project.vercel.app';
console.log('🔍 开始检测博客评论功能...\n');
// 检查 1:Twikoo 容器
const container = document.querySelector('#twikoo-container');
console.log('1. 评论容器:', container ? '✅ 存在' : '❌ 不存在');
// 检查 2:Twikoo 脚本
const scriptLoaded = typeof twikoo !== 'undefined';
console.log('2. Twikoo 脚本:', scriptLoaded ? '✅ 已加载' : '❌ 未加载');
// 检查 3:评论框
const commentBox = document.querySelector('#tcomment');
console.log('3. 评论框:', commentBox ? '✅ 已渲染' : '❌ 未渲染');
// 检查 4:API 连接
try {
const response = await fetch(TWIKOO_ENV_ID, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ event: 'GET' })
});
const data = await response.json();
console.log('4. API 连接:', data.status === 0 ? '✅ 正常' : '❌ 异常');
console.log(' Twikoo 版本:', data.data?.version || '未知');
} catch (e) {
console.log('4. API 连接:', '❌ 失败 -', e.message);
}
// 检查 5:评论数量
try {
const response = await fetch(TWIKOO_ENV_ID, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
event: 'COMMENT_LIST',
url: window.location.pathname,
pageSize: 10
})
});
const data = await response.json();
if (data.status === 0) {
console.log('5. 评论数量:', `✅ 共 ${data.data.commentList?.length || 0} 条评论`);
}
} catch (e) {
console.log('5. 评论数量:', '❌ 获取失败');
}
console.log('\n✨ 检测完成');
})();

TWIKOO_ENV_ID 替换为您的 Twikoo 环境 ID。

5. 常见博客评论问题排查#

问题可能原因解决方案
评论框不显示Twikoo 脚本加载失败检查网络连接,确认 envId 正确
评论提交失败CORS 跨域问题检查 Vercel 部署配置
评论不保存数据库连接问题检查 MongoDB 连接字符串
评论显示空白页面 JS 错误打开控制台查看错误信息
管理后台看不到评论页面 URL 不匹配检查评论的 URL 配置

6. Vercel 监控检查#

  1. 登录 Vercel Dashboard
  2. 选择您的 Twikoo 项目
  3. 查看以下指标:
    • Requests:请求数量
    • Bandwidth:带宽使用
    • Function Duration:函数执行时间
    • Errors:错误数量

✅ 正常状态: Requests 有请求,Errors 为 0 或很少

❌ 异常状态: Errors 数量持续增加,Function Duration 过长

7. 设置监控告警(推荐)#

为了及时发现问题,建议设置 Vercel 告警:

  1. 进入项目 Settings → Notifications
  2. 配置邮件通知
  3. 设置错误阈值告警
  4. 开启部署失败通知

自动检测脚本#

创建一个 HTML 文件用于检测 Twikoo 状态:

<!DOCTYPE html>
<html>
<head>
<title>Twikoo 状态检测</title>
</head>
<body>
<h1>Twikoo 状态检测</h1>
<div id="result">检测中...</div>
<script>
const TWIKOO_URL = 'https://your-twikoo-project.vercel.app';
fetch(TWIKOO_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ event: 'COMMENT_LIST', pageSize: 1 })
})
.then(res => res.json())
.then(data => {
document.getElementById('result').innerHTML =
data.status === 0
? '✅ Twikoo 运行正常!'
: '❌ Twikoo 异常: ' + JSON.stringify(data);
})
.catch(err => {
document.getElementById('result').innerHTML =
'❌ 连接失败: ' + err.message;
});
</script>
</body>
</html>

TWIKOO_URL 替换为您的 Twikoo 地址,然后在浏览器中打开此文件即可检测状态。

第六步:在博客中配置#

打开您的博客配置文件(src/config.ts),找到评论配置部分:

export const commentConfig: CommentConfig = {
enable: true,
system: "twikoo",
twikoo: {
envId: "https://your-twikoo-project.vercel.app", // 替换为您的环境 ID
lang: "zh_CN",
},
};

envId 修改为您的 Twikoo 部署地址。

第七步:配置 Twikoo 管理后台#

1. 登录管理后台#

访问您的 Twikoo 环境地址(例如:https://your-twikoo-project.vercel.app

2. 创建管理员账号#

  • 首次访问会提示创建管理员账号
  • 输入邮箱和密码
  • 记录登录信息

3. 配置基础设置#

登录后,在管理后台可以进行以下配置:

站点设置#

  • 设置站点名称和描述
  • 配置站点 Logo
  • 设置评论通知邮箱

评论审核#

  • 配置是否需要审核
  • 设置敏感词过滤
  • 配置垃圾评论策略

外观设置#

  • 选择评论框主题
  • 配置表情选项
  • 自定义样式

常见问题#

问题 1:部署失败#

解决方案:

  • 检查 MongoDB 连接字符串是否正确
  • 确认数据库 IP 白名单已配置
  • 查看 Vercel 部署日志

问题 2:评论无法提交#

解决方案:

  • 检查 CORS 配置
  • 确认环境 ID 配置正确
  • 检查网络连接

问题 3:管理后台无法登录#

解决方案:

  • 重置管理员密码
  • 检查数据库连接
  • 重新部署项目

进阶功能#

配置邮件通知#

  1. 在 Twikoo 管理后台开启邮件通知
  2. 配置 SMTP 设置
  3. 保存配置

自定义样式#

/* 在博客的自定义样式中添加 */
.twikoo-container {
/* 您的自定义样式 */
}

数据备份#

定期在管理后台导出评论数据:

  • 进入「数据管理」
  • 点击「导出数据」
  • 保存 JSON 文件

安全建议#

  1. 使用强密码作为管理员密码
  2. 定期更新 Twikoo 版本
  3. 开启 HTTPS(Vercel 默认已开启)
  4. 定期备份评论数据
  5. 配置 IP 访问限制(可选)

性能优化#

  • 启用评论框懒加载(本博客已配置)
  • 使用 CDN 加速静态资源
  • 配置适当的缓存策略

总结#

恭喜!您已经成功部署了自己的 Twikoo 评论系统。现在您的博客将拥有一个独立、安全的评论功能。

相关链接:


祝您使用愉快!如有问题,欢迎留言交流。

分享

如果这篇文章对你有帮助,欢迎分享给更多人!

Twikoo 评论系统部署到 Vercel 完整教程
https://github.com/Ruthlessa/Mizuki/tree/main/src/content/posts/twikoo-deployment-guide
作者
无情
发布于
2026-04-22
许可协议
CC BY-NC-SA 4.0

部分信息可能已经过时

目录