在搭建 Hexo 博客时，添加评论功能不仅能与读者互动，还能提高用户的参与度。Gitalk 是一个基于 GitHub Issues 的评论系统，它简单易用，适合技术类博客。本文将教你如何在 Hexo 中配置 Gitalk 评论系统。

准备工作

在开始配置之前，请确保已完成以下事项：

  1. Hexo 博客环境：确保 Hexo 博客已经搭建完成。
  2. GitHub 仓库：创建一个 GitHub 仓库（如 blog-comments），用于存储评论。
  3. GitHub OAuth 应用：
    • 登录 GitHub，进入 GitHub Developer Settings。
    • 点击 New OAuth App 创建一个新的应用，填写以下内容：
      • Application name: Gitalk for Hexo
      • Homepage URL: 你的博客地址，如 https://yourblog.com
      • Authorization callback URL: 同样填写你的博客地址。
    • 点击 Register Application，记录生成的 Client ID 和 Client Secret。

安装 Gitalk 插件

进入你的 Hexo 博客项目目录，安装 Gitalk 所需的依赖：

1
npm install hexo-helper-live2d gitalk --save

配置 Gitalk

在主题配置文件中添加 Gitalk 配置

如果你使用的是 Butterfly 主题，编辑主题配置文件 _config.butterfly.yml，添加如下配置：

1
2
3
4
5
6
7
8
gitalk:
  enable: true
  clientID: '你的 GitHub 客户端 ID'
  clientSecret: '你的 GitHub 客户端密钥'
  repo: 'blog-comments'
  owner: '你的 GitHub 用户名'
  admin: ['你的 GitHub 用户名']
  distractionFreeMode: false

调用评论模板

确保主题模板中正确加载了 Gitalk。如果没有，可在 layout/_partials/comments.ejs 文件中添加如下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<% if (theme.gitalk.enable) { %>
  <link rel="stylesheet" href="https://unpkg.com/gitalk/dist/gitalk.css">
  <script src="https://unpkg.com/gitalk/dist/gitalk.min.js"></script>
  <div id="gitalk-container"></div>
  <script>
    const gitalk = new Gitalk({
      clientID: '<%= theme.gitalk.clientID %>',
      clientSecret: '<%= theme.gitalk.clientSecret %>',
      repo: '<%= theme.gitalk.repo %>',
      owner: '<%= theme.gitalk.owner %>',
      admin: <%= JSON.stringify(theme.gitalk.admin) %>,
      id: location.pathname,
      distractionFreeMode: <%= theme.gitalk.distractionFreeMode %>
    });
    gitalk.render('gitalk-container');
  </script>
<% } %>

测试评论功能

本地测试

运行以下命令生成博客并启动本地服务器：

1
2
3
hexo clean
hexo generate
hexo server

在浏览器中访问 http://localhost:4000，进入文章页面，检查评论框是否正常加载。

部署到线上

本地测试完成后，运行以下命令将博客部署到线上：

1
hexo deploy

访问你的博客网址，验证评论系统是否正常工作。

常见问题与解决方法

登录时提示 OAuth 错误

  • 检查 GitHub 应用的 Authorization callback URL 是否填写正确。
  • 确保线上博客的域名与回调地址一致。

评论框加载失败

  • 检查浏览器控制台报错信息：
    • 如果是 401 Unauthorized，可能是 Client ID 或 Client Secret 配置错误。
    • 如果是网络错误，检查是否正确引用了 Gitalk 的 CSS 和 JS 文件。

无法同步评论到 Issues

  • 确保评论仓库是公开的，或者你的 GitHub 账号对其有写入权限。

个性化配置

自定义评论 ID

默认情况下，Gitalk 使用文章的路径作为评论 ID。如果你希望自定义 ID，可以修改配置：

1
id: window.location.pathname

自定义样式

通过 CSS 文件自定义评论框的样式：

1
2
3
4
5
6
#gitalk-container {
  margin-top: 20px;
}
.gitalk-header {
  background-color: #f5f5f5;
}

配置完成后，Gitalk 就能为你的 Hexo 博客带来强大的评论功能。如果你遇到问题或有其他需求，欢迎留言讨论！