什么是 Twikoo#

Twikoo 是一款轻量级开源评论系统，基于 Node.js 开发，支持 Markdown、代码高亮、表情包、图片上传（支持多种图床）、邮件/IM 通知等功能。

Twikoo vs 其他评论系统#

Twikoo 的优势#

• 部署灵活：支持 Vercel、腾讯云、Railway、Docker 等多种部署方式
• 配置丰富：7 大配置模块，覆盖评论系统的方方面面
• 界面美观：默认主题简洁，支持自定义背景
• 隐私友好：可选显示 UA、IP 属地等信息
• 迁移方便：支持从 Artalk、Disqus、Valine 导入评论

普通入口#

在博客页面任意位置快速点击三次，会弹出管理面板登录框。

隐藏入口#

如果开启了「隐藏管理面板」（HIDE_ADMIN_CRYPT），常规点击不会触发登录框，需要访问：

1
https://你的Vercel地址/?twikoo=你的暗号

登录方式#

• 腾讯云环境：需要使用私钥文件登录（私钥在腾讯云云开发控制台 → 环境 → 权限设置中可获取）
• Vercel 环境：直接输入 TWIKOO_SECRET 环境变量的值

忘记密码怎么办？#

• 腾讯云：前往云开发控制台，删除 config 记录，重新设置。
• Vercel：前往 MongoDB Atlas，编辑 configs 集合，删除 ADMIN_PASS 字段，然后去管理面板重新设置密码。

方式一：使用公共版本（无需部署）#

如果不想自己部署，可以直接使用公共的 Twikoo 服务：

1
// 在博客中引入 Twikoo
2
<script src="https://cdn.jsdelivr.net/npm/twikoo@1.6.41/twikoo.all.min.js"></script>
3

4
// 初始化
5
<div id="twikoo"></div>
6
<script>
7
  tk.init({
8
    envId: 'https://twikoo.vercel.app', // 公共版本地址
9
    el: '#twikoo',
10
  });
11
</script>

公共版本功能完整，但建议生产环境还是自己部署。

方式二：Vercel 部署（推荐）#

1. 申请 MongoDB Atlas，创建免费集群，获取连接字符串
2. 在vercel中登陆账号后进行一键部署：

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

3. 部署后，在 Vercel 的twikoo环境变量中添加 MONGODB_URI
4. 进入 Settings → Deployment Protection，设置 Vercel Authentication 为 Disabled（关键步骤，否则邮件无法发送）
5. 选择Redeploy（重新部署）
6. 访问正确的域名地址，确认显示「Twikoo 云函数运行正常」

方式三：腾讯云部署#

适合国内访问，腾讯云有免费额度：

1. 开通腾讯云开发 CloudBase
2. 创建云函数环境
3. 下载 Twikoo 源码，上传到云函数
4. 配置环境变量 MONGODB_URI、TWIKOO_SECRET

4.1 通用设置#

QQ_API_KEY 获取地址：https://api.nsuuu.com/admin/key

4.2 插件设置#

4.3 隐私设置#

4.4 反垃圾设置#

Akismet 注册地址：https://akismet.com

人工审核设置：将 AKISMET_KEY 设置为 MANUAL_REVIEW 即可开启人工审核模式。

4.5 验证码设置#

4.6 即时通知设置（IM）#

IM 通知渠道：qmsg、serverchan、pushplus、pushplushxtrip、dingtalk、wecom、bark、gocqhttp、atri、pushdeer、igot、telegram、feishu 等

Pushoo 配置参考：https://pushoo.js.org

4.7 邮件通知设置#

支持的 SMTP 服务商：126、163、1und1、AOL、DebugMail、DynectEmail、FastMail、GandiMail、Gmail、Godaddy、Hotmail、Maildev、Mailgun、Mailjet、Mandrill、Naver、Outlook365、Postmark、QQ、QQex、SES、SendCloud、SendGrid、SendPulse、SendinBlue、Sparkpost、Yahoo、Yandex、Zoho、iCloud、qiye.aliyun 等

邮件模板可用字段：${SITE_URL}、${SITE_NAME}、${PARENT_NICK}、${PARENT_COMMENT}、${NICK}、${COMMENT}、${POST_URL}、${IMG}、${PARENT_IMG}

Vercel 部署提示：如果邮件测试正常但实际收不到通知，请进入 Vercel 云函数管理 → Settings → Deployment Protection，将 Vercel Authentication 设置为 Disabled。

导出评论#

在管理面板可以导出全部评论数据为 JSON 文件。

如果评论较多、导出失败或缺失数据，建议连接 MongoDB 数据库手动导出。

导入评论#

支持从以下评论系统导入数据：

导入前建议备份 comment 数据库。

迁移注意事项#

• 迁移前建议备份现有数据
• 评论的 uid 会重新生成，原有评论链接可能失效
• 评论的创建时间会保留，但审核状态会重置
• 如果迁移失败率高，建议手动连接 MongoDB 导出后转换格式

在 Twikoo 管理面板获取 envId#

部署成功后，在 Twikoo 管理面板的「关于」页面可以查看环境 ID（envId），格式如：https://your-twikoo.vercel.app

Mizuki 主题配置#

在 src/config.ts 中修改 commentConfig：

1
export const commentConfig: CommentConfig = {
2
    enable: true,
3
    twikoo: {
4
        envId: 'https://your-twikoo.vercel.app', // 你的 Twikoo 地址
5
        lang: 'zh-CN', // 语言
6
    },
7
};

静态页面引入#

如果博客不使用主题支持，可以手动在页面中引入：

1
<!-- 引入 Twikoo -->
2
<script src="https://cdn.jsdelivr.net/npm/twikoo@1.6.41/twikoo.all.min.js"></script>
3

4
<!-- 评论区域 -->
5
<div id="twikoo"></div>
6

7
<!-- 初始化 -->
8
<script>
9
  tk.init({
10
    envId: 'https://your-twikoo.vercel.app',
11
    el: '#twikoo',
12
  });
13
</script>

禁用单篇文章评论#

在文章 frontmatter 中添加：

1
---
2
comment: false
3
---

配置方法#

在 Twikoo 管理面板设置 BLOGGER_EMAIL：

显示效果#

配置后，访客使用与博主相同的邮箱评论时，会自动显示博主标识（如红色”博主”标签），便于读者识别官方回复。

默认表情包#

Twikoo 默认使用 OwO 表情包，托管在 https://owo.imaegoo.com/owo.json。

自定义表情 CDN#

在管理面板配置 EMOTION_CDN：

自定义表情包格式#

表情包需要是一个 JSON 文件，包含表情分类和对应的 URL：

1
{
2
  "items": [
3
    {
4
      "type": "image",
5
      "container": [
6
        {
7
          "title": "表情名称",
8
          "icon": "https://example.com/emoji/normal.png",
9
          "src": "https://example.com/emoji/normal.png"
10
        }
11
      ]
12
    }
13
  ]
14
}

公开表情包列表#

• OwO 官方：https://owo.imaegoo.com/owo.json
• Twikoo 原生：https://cdn.jsdelivr.net/npm/twikoo@1.6.31/resource/owo.json

1. 设置管理面板暗号#

开启 HIDE_ADMIN_CRYPT 后，常规点击不会触发登录框，需要通过 ?twikoo=暗号 才能访问登录页面。

2. 配置 CORS 安全域名#

设置 CORS_ALLOW_ORIGIN 为你的博客域名，防止其他网站调用你的评论接口：

1
https://your-blog.com

多个域名用逗号分隔：

1
https://blog.com,https://www.blog.com

3. 限制发言频率#

4. 配置反垃圾#

• 免费方案：设置 AKISMET_KEY 为 MANUAL_REVIEW，开启人工审核
• 付费方案：配置腾讯云内容安全 QCLOUD_SECRET_ID/SECRET_KEY

5. 违禁词防护#

6. 定期备份评论数据#

在管理面板「导出」功能可以导出全部评论为 JSON，建议定期备份：

1
管理面板 → 评论管理 → 导出 → 导出评论

Q: 如何修改/重置管理员密码？#

• 腾讯云：前往云开发控制台，删除 config 记录，重新设置。
• Vercel：前往 MongoDB Atlas，编辑 configs 集合，删除 ADMIN_PASS 字段，然后去管理面板重新设置密码。

Q: 忘记隐藏入口暗号怎么办？#

在页面打开浏览器开发者工具（F12），Network 标签，刷新页面，搜索 HIDE_ADMIN_CRYPT，在返回结果中可找到暗号。

Q: 收不到邮件通知？#

1. 确认已设置 Vercel Authentication 为 Disabled
2. 邮件配置有约 10 分钟缓存
3. 博主自己评论不会收到通知，请注销后用其他邮箱测试
4. 使用国外邮件服务商，避免被判定为垃圾邮件

Q: 评论失败或管理面板进不去？#

打开浏览器 Console 查看错误：

Q: 如何开启人工审核？#

将 AKISMET_KEY 设置为 MANUAL_REVIEW 即可开启人工审核模式。所有评论会被标记为待审核状态，需要在管理面板手动审核通过后才能显示。

Q: 违禁词和屏蔽词有什么区别？#

• 违禁词（FORBIDDEN_WORDS）：包含违禁词的内容会直接标记为垃圾评论（可在管理面板手动恢复）
• 屏蔽词（BLOCKED_WORDS）：包含屏蔽词的内容会直接评论失败，用户无法提交