Mahiro-Blog 新手教程（五）：评论系统接入（Giscus / Waline）

评论系统是博客互动的核心功能之一。Mahiro-Blog 已经预留了 Giscus 和 Waline 两套接入能力，你只需要改配置即可启用。

1. 先看配置入口

核心配置在 mahiro.config.yaml：

• comments.enable：是否启用评论
• comments.type：giscus / waline / none
• comments.giscus：Giscus 参数
• comments.waline：Waline 参数

页面渲染层会根据这个 type 自动选择组件。

2. 接入 Giscus（最省心）

适合：你已使用 GitHub，并希望低运维。

配置示例：

comments:
  enable: true
  type: giscus
  giscus:
    repo: yourname/yourrepo
    repoId: R_kgDOxxxxx
    category: General
    categoryId: DIC_kwDOxxxxx
    mapping: pathname
    lang: zh-CN
    inputPosition: top
    reactionsEnabled: '1'
    emitMetadata: '0'
    loading: lazy

你需要去 giscus.app 生成上述参数（尤其是 repoId 与 categoryId）。

3. 接入 Waline（更自由）

适合：你有自部署后端需求，希望评论能力更可控。

配置示例：

comments:
  enable: true
  type: waline
  waline:
    serverURL: https://your-waline-server
    lang: zh-CN
    emoji:
      - https://unpkg.com/@waline/emojis@1.1.0/weibo
    meta:
      - nick
      - mail
      - link
    requiredMeta: []
    reaction: false
    pageview: false

建议先跑最小配置，确认能加载后再加高级选项。

4. 切换评论系统的正确姿势

只改一处：comments.type

• 从 giscus 切到 waline
• 或从 waline 切回 giscus

其余配置保留，不影响未来回切。

5. 常见问题排查

5.1 页面不显示评论区

按顺序查：

1. comments.enable 是否为 true
2. comments.type 是否拼写正确
3. 对应平台参数是否完整

5.2 Giscus 显示但无法发言

通常是仓库 Discussions 权限或分类配置错误，重点检查：

• 仓库是否开启 Discussions
• repoId / categoryId 是否匹配

5.3 Waline 接口报错

优先检查：

• serverURL 是否可访问
• 后端是否正常运行
• 跨域/证书配置是否正确

6. 新手建议

• 没有强烈自部署需求：优先 Giscus
• 有评论数据自治需求：再考虑 Waline

先把评论功能跑通，再做皮肤和交互微调。

系列导航

新手专栏目录入口