评论系统集成指南

为文档站点添加评论功能可以增强用户互动，收集反馈，构建社区。本教程对比三种主流评论方案，并详细讲解配置方法。

方案对比

特性	Giscus	Waline	Twikoo
数据存储	GitHub Discussions	自托管数据库	云开发/自托管
部署难度	⭐ 最简单	⭐⭐ 需部署后端	⭐⭐ 需部署
评论管理	GitHub Issues 风格	独立后台	独立后台
邮件通知	通过 GitHub	支持	支持
匿名评论	❌ 需 GitHub 登录	✅ 支持	✅ 支持
国际化	支持多语言	支持多语言	支持多语言
免费使用	✅ 完全免费	✅ 免费额度	✅ 免费额度
国内访问	一般（需代理）	快（自选部署）	快（云开发）
适合场景	技术博客、开源项目	企业文档、多用户	个人博客

方案选择建议

mermaid

graph TD
    A[选择评论系统] --> B{目标用户}
    B -->|开发者/技术博客| C{GitHub 依赖}
    B -->|普通用户/企业| D{部署能力}
    C -->|已有 GitHub 项目| E[Giscus]
    C -->|不想依赖 GitHub| F[自托管 Waline]
    D -->|有服务器| F
    D -->|无服务器/零成本| G[Twikoo 云开发版本]

Giscus 配置

Giscus 基于 GitHub Discussions，是技术博客的首选方案。

前置条件

GitHub 仓库必须公开
已安装 giscus app
仓库已启用 Discussions 功能

启用 Discussions

进入仓库 Settings > Features，勾选 Discussions。

自动配置

访问 giscus.app，填写仓库信息获取配置：

<script src="https://giscus.app/client.js"
  data-repo="your-username/your-repo"
  data-repo-id="R_xxxxx"
  data-category="Announcements"
  data-category-id="DIC_xxxxx"
  data-mapping="pathname"
  data-strict="0"
  data-reactions-enabled="1"
  data-emit-metadata="0"
  data-input-position="top"
  data-theme="preferred_color_scheme"
  data-lang="zh-CN"
  crossorigin="anonymous"
  async>
</script>

创建 VitePress 组件

vue

<!-- docs/.vitepress/components/GiscusComments.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'

const { isDark } = useData()

const giscusConfig = {
  repo: 'your-username/your-repo',
  repoId: 'R_xxxxx',
  category: 'Announcements',
  categoryId: 'DIC_xxxxx',
  mapping: 'pathname',
  reactionsEnabled: '1',
  inputPosition: 'top' as const,
  theme: 'preferred_color_scheme',
  lang: 'zh-CN'
}
</script>

<template>
  <div class="giscus-container">
    <script
      src="https://giscus.app/client.js"
      :data-repo="giscusConfig.repo"
      :data-repo-id="giscusConfig.repoId"
      :data-category="giscusConfig.category"
      :data-category-id="giscusConfig.categoryId"
      data-mapping="pathname"
      data-strict="0"
      :data-reactions-enabled="giscusConfig.reactionsEnabled"
      data-emit-metadata="0"
      :data-input-position="giscusConfig.inputPosition"
      :data-theme="isDark ? 'dark' : 'light'"
      :data-lang="giscusConfig.lang"
      crossorigin="anonymous"
      async
    />
  </div>
</template>

<style scoped>
.giscus-container {
  margin-top: 2rem;
  padding-top: 1rem;
  border-top: 1px solid var(--vp-c-divider);
}
</style>

注册为全局组件

// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import GiscusComments from './components/GiscusComments.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('GiscusComments', GiscusComments)
  }
}

在布局中使用

vue

<!-- docs/.vitepress/theme/Layout.vue -->
<script setup lang="ts">
import DefaultTheme from 'vitepress/theme'
import GiscusComments from './components/GiscusComments.vue'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #doc-after>
      <GiscusComments />
    </template>
  </Layout>
</template>

Waline 配置

Waline 功能完善，适合需要完整评论管理后台的场景。

部署方案

方案一：Vercel + LeanCloud（推荐）

注册 LeanCloud 国际版，创建应用
获取 AppID、AppKey、MasterKey
点击一键部署到 Vercel：

设置环境变量：

变量名	值
LEAN_ID	LeanCloud AppID
LEAN_KEY	LeanCloud AppKey
LEAN_MASTER_KEY	LeanCloud MasterKey

方案二：独立数据库

使用 MySQL/PostgreSQL/MongoDB：

bash

# Docker 部署
docker run -d \
  --name waline \
  -p 8360:8360 \
  -e MYSQL_HOST=db_host \
  -e MYSQL_DB=waline \
  -e MYSQL_USER=waline \
  -e MYSQL_PASSWORD=password \
  lizheming/waline

VitePress 集成

vue

<!-- docs/.vitepress/components/WalineComments.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'
import { init } from '@waline/client'
import { onMounted, watch, ref } from 'vue'

import '@waline/client/style'

const { isDark } = useData()
const walineRef = ref<HTMLElement>()

const walineUrl = 'https://your-waline.vercel.app'

let waline: ReturnType<typeof init> | null = null

onMounted(() => {
  waline = init({
    el: walineRef.value!,
    serverURL: walineUrl,
    lang: 'zh-CN',
    dark: 'html.dark',
    login: 'enable',
    meta: ['nick', 'mail', 'link'],
    requiredMeta: ['nick', 'mail'],
    pageSize: 10,
    imageUploader: false
  })
})

watch(isDark, () => {
  // Waline 自动响应主题变化
})
</script>

<template>
  <div class="waline-container">
    <div ref="walineRef" />
  </div>
</template>

<style scoped>
.waline-container {
  margin-top: 2rem;
  padding-top: 1rem;
  border-top: 1px solid var(--vp-c-divider);
}
</style>

安装依赖

bash

npm install @waline/client

管理后台

访问 https://your-waline.vercel.app/ui 进入管理后台，支持：

评论审核
用户管理
邮件通知配置
垃圾评论过滤

Twikoo 配置

Twikoo 轻量级，适合个人博客，支持腾讯云开发零成本部署。

部署方案

方案一：腾讯云开发（免费）

开通腾讯云开发
创建环境，记录环境 ID envId
在「云函数」中创建函数，选择「Twikoo」

bash

# 或使用 CLI 部署
npm install tkserver
npx tkserver deploy --envId your-env-id

方案二：Vercel 部署

bash

# 克隆 Twikoo
git clone https://github.com/twikoojs/twikoo.git
cd twikoo

# 部署到 Vercel
vercel

VitePress 集成

vue

<!-- docs/.vitepress/components/TwikooComments.vue -->
<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { useData } from 'vitepress'

const twikooEnvId = 'your-twikoo-env-id'

onMounted(async () => {
  // 动态加载 Twikoo
  const twikoo = await import('twikoo')
  twikoo.init({
    envId: twikooEnvId,
    el: '#twikoo-comment'
  })
})
</script>

<template>
  <div class="twikoo-container">
    <div id="twikoo-comment" />
  </div>
</template>

<style scoped>
.twikoo-container {
  margin-top: 2rem;
  padding-top: 1rem;
  border-top: 1px solid var(--vp-c-divider);
}
</style>

安装依赖

bash

npm install twikoo

进阶配置

评论通知

系统	邮件	微信	Telegram
Giscus	GitHub 通知	❌	❌
Waline	✅ SMTP	✅ Server酱	✅ Bot
Twikoo	✅ SMTP	✅ Server酱	✅ Bot

反垃圾策略

Waline 配置：

// 服务端环境变量
AKISMET_KEY=your-akismet-key  // Akismet 反垃圾
TURING_TEST=true              // 图灵测试

Twikoo 配置：

// 云函数配置
const config = {
  AKISMET_KEY: 'your-key',
  SCF_RECAPTCHA_TOKEN: 'your-token'
}

仅特定页面显示评论

vue

<!-- docs/.vitepress/components/ConditionalComments.vue -->
<script setup lang="ts">
import { useData } from 'vitepress'
import GiscusComments from './GiscusComments.vue'

const { frontmatter } = useData()
</script>

<template>
  <GiscusComments v-if="frontmatter.comments !== false" />
</template>

在 frontmatter 中禁用评论：

yaml

---
title: 关于页面
comments: false
---

迁移指南

从 Valine 迁移到 Waline

Waline 兼容 Valine 数据，只需修改前端配置：

// Valine 配置
new Valine({
  appId: 'xxx',
  appKey: 'xxx'
})

// Waline 配置
init({
  serverURL: 'https://your-waline.vercel.app'
})

从 Disqus 迁移

导出 Disqus 评论（XML 格式）
使用 disqus-to-waline 转换
导入到 Waline 数据库

常见问题

Q: Giscus 评论不显示？

检查仓库是否公开
确认已安装 giscus app
检查 Discussions 是否启用
确认 data-repo-id 和 data-category-id 正确

Q: Waline 邮件发送失败？

检查 SMTP 配置：

env

SMTP_SERVICE=QQ
SMTP_USER=your@qq.com
SMTP_PASS=授权码
SITE_NAME=你的站点名
SITE_URL=https://your-site.com
AUTHOR_EMAIL=你的邮箱

Q: 如何自定义评论样式？

css

/* Waline 自定义样式 */
.waline-container {
  --waline-theme-color: var(--vp-c-brand-1);
  --waline-active-color: var(--vp-c-brand-2);
  --waline-font-size: 0.95rem;
}

/* Twikoo 自定义样式 */
.twikoo-container .tk-content {
  font-size: 0.95rem;
  line-height: 1.6;
}

下一步

学习站点统计了解访问数据分析
学习部署与发布部署评论后端服务
学习自定义组件开发更多交互组件

评论系统集成指南 ​

方案对比 ​

方案选择建议 ​

Giscus 配置 ​

前置条件 ​

启用 Discussions ​

自动配置 ​

创建 VitePress 组件 ​

注册为全局组件 ​

在布局中使用 ​

Waline 配置 ​

部署方案 ​

方案一：Vercel + LeanCloud（推荐） ​

方案二：独立数据库 ​

VitePress 集成 ​

安装依赖 ​

管理后台 ​

Twikoo 配置 ​

部署方案 ​

方案一：腾讯云开发（免费） ​

方案二：Vercel 部署 ​

VitePress 集成 ​

安装依赖 ​

进阶配置 ​

评论通知 ​

反垃圾策略 ​

仅特定页面显示评论 ​

迁移指南 ​

从 Valine 迁移到 Waline ​

从 Disqus 迁移 ​

常见问题 ​

Q: Giscus 评论不显示？ ​

Q: Waline 邮件发送失败？ ​

Q: 如何自定义评论样式？ ​

下一步 ​

贡献者

评论系统集成指南

方案对比

方案选择建议

Giscus 配置

前置条件

启用 Discussions

自动配置

创建 VitePress 组件

注册为全局组件

在布局中使用

Waline 配置

部署方案

方案一：Vercel + LeanCloud（推荐）

方案二：独立数据库

VitePress 集成

安装依赖

管理后台

Twikoo 配置

部署方案

方案一：腾讯云开发（免费）

方案二：Vercel 部署

VitePress 集成

安装依赖

进阶配置

评论通知

反垃圾策略

仅特定页面显示评论

迁移指南

从 Valine 迁移到 Waline

从 Disqus 迁移

常见问题

Q: Giscus 评论不显示？

Q: Waline 邮件发送失败？

Q: 如何自定义评论样式？

下一步