Hugo 插件 - Waline

Fri, 19 Apr 2024 13:14:24 +0800

前言

近期学校一堆破事。醉了，趁着闲暇之余，寻思着我的博客还没有评论功能，于是便找了一个评论插件 Waline。这个插件是一个轻量级的评论系统，支持多种第三方登录，支持自定义表情包，支持自定义评论框样式。本文将介绍如何在 Hugo 博客中使用 Waline 评论插件。

Waline 是什么

Waline 是一款开源的、带后端的评论系统。和 utterances、giscus 这类基于 GitHub Issues / Discussions 的方案不同，Waline 的评论存在你自己的数据库里，访客不需要 GitHub 账号也能评论。

主要特性：

匿名评论，也支持注册账号和多种第三方登录；
表情包、Markdown、图片上传、代码高亮；
自带评论管理后台，可以审核、修改、删除评论；
支持浏览量统计、评论通知（邮件、Telegram 等）；
服务端可以部署在 Vercel、Netlify、自己的服务器等多种平台，数据库支持 PostgreSQL、MySQL、MongoDB、SQLite 等。

它由两部分组成：

客户端：一段 JS，嵌入到博客页面里，负责显示评论框和评论列表。Stack 主题已经内置了，我们只需要填配置；
服务端：一个 Node.js 应用，负责接收评论、读写数据库、提供管理后台。这部分需要我们自己部署。

部署服务端

下面按 Waline 官方文档推荐的 Vercel + Neon（PostgreSQL） 方案部署，全程在网页上点点点，不需要服务器，免费额度对个人博客足够了。

早期的教程大多是 Vercel + LeanCloud。目前官方文档已经移除了 LeanCloud 方案，新部署请直接用下面的数据库方案。

1. 在 Vercel 上创建项目

打开官方文档快速上手页面，点击 Deploy 按钮跳转到 Vercel；没有登录的话，用 GitHub 账号登录即可。
输入一个你喜欢的项目名称，点击 Create。
Vercel 会基于 Waline 模板在你的 GitHub 下新建一个同名仓库，并开始部署。一两分钟后部署完成，点击 Go to Dashboard 进入控制台。

这时候访问服务端可能会报 500 This Serverless Function has crashed，这是因为还没连数据库，完成下一步就好了。

2. 创建数据库并初始化表结构

在项目控制台点击 Storage → Create Database，在 Marketplace Database Providers 中选择 Neon，点击 Continue。
按提示创建 Neon 账号（Accept and Create），套餐、地区保持默认即可，再给数据库起个名字点击 Create。
在数据库页面点击 Connect → Connect Project，把数据库连接到刚才的 Waline 项目。Vercel 会自动把连接信息以环境变量的形式注入项目。
点击 Open in Neon 跳转到 Neon 控制台，打开左侧的 SQL Editor，把官方仓库里 waline.pgsql 的内容粘贴进去，点击 Run 建表。

3. 重新部署

回到 Vercel，进入 Deployments，选择最新的一次部署，点击右侧的 Redeploy。环境变量只在重新部署后才会生效。

等 STATUS 变成 Ready 后点击 Visit，打开的地址（形如 https://xxx.vercel.app）就是你的服务端地址 serverURL，后面要用。

4.（可选）绑定自己的域名

*.vercel.app 在国内访问不太稳定，建议绑定自己的域名：

在 Vercel 项目中进入 Domains，添加域名，例如 waline.example.com；
到域名服务商处添加一条 CNAME 记录：

Type Name Value

CNAME waline cname.vercel-dns.com
等待解析生效后，https://waline.example.com 就是新的 serverURL。

Type	Name	Value
CNAME	waline	cname.vercel-dns.com

5. 注册管理员

部署完成后，尽快访问 <serverURL>/ui/register 注册账号，第一个注册的用户会成为管理员。之后在 <serverURL>/ui 就能管理评论了。

常用环境变量

在 Vercel 项目的 Settings → Environment Variables 中可以进一步配置服务端，改完记得 Redeploy：

变量	作用
`SITE_NAME`	博客名称，用于评论通知
`SITE_URL`	博客地址，用于评论通知中的链接
`SECURE_DOMAINS`	安全域名，只允许这些域名调用服务端，多个用逗号分隔

邮件通知、Telegram 通知等更多变量见服务端环境变量。

在 Stack 主题中启用 Waline

hugo-theme-stack 已经内置了 Waline 客户端（layouts/_partials/comments/provider/waline.html），会自动引入 Waline 的 JS 和 CSS，我们只需要改配置。

在 config/_default/params.toml（或者 hugo.toml 的 [params] 下）中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[comments]
enabled = true
provider = "waline"

[comments.waline]
serverURL = "https://waline.example.com"
lang = "zh-CN"
emoji = ["https://unpkg.com/@waline/emojis@1.0.1/weibo"]
requiredMeta = ["name", "email"]

[comments.waline.locale]
admin = "博主"
placeholder = "说点什么吧～"

字段说明：

字段	说明
`serverURL`	必填，上一步得到的服务端地址
`lang`	界面语言，例如 `zh-CN`、`en`
`emoji`	表情包预设地址，可以写多个
`requiredMeta`	评论时必填的信息，可选 `name`、`email`、`url`
`pageview`	是否统计浏览量
`locale`	自定义界面文案，例如管理员标签 `admin`、输入框占位文字 `placeholder`

主题是怎么把这些配置传给 Waline 的呢？看一下源码就清楚了：

[comments.waline] 下的每一项都会原样传给 Waline.init()。因为 Hugo 读取配置时会把键名转成小写，主题专门把 serverurl、requiredmeta、wordlimit、pagesize、imageuploader、texrenderer、turnstilekey 这些键改回 Waline 需要的驼峰写法。所以其他客户端选项也可以直接写在这里，例如：

1
2
3
4


[comments.waline]
# ...
wordLimit = 500
pageSize = 10

主题已经设置了 dark = 'html[data-scheme="dark"]'，让评论框跟随博客的明暗模式切换，一般不要在配置里再写 dark，否则会覆盖主题的设置。

保存后执行 hugo server，打开任意一篇文章，滚到底部就能看到评论框了。

单篇文章关闭评论

不想让某篇文章开放评论，在它的 front matter 里写：

1

comments: false

常见问题

评论框不显示

确认 [comments] 中 enabled = true，provider = "waline"；
确认文章 front matter 里没有 comments: false；
打开浏览器控制台，看是否有请求 serverURL 失败的报错。

提示跨域或请求被拒绝

如果配置了 SECURE_DOMAINS，检查它是否包含了你的博客域名；
确认 serverURL 填的是服务端根地址，能在浏览器中直接打开。

改了环境变量不生效

Vercel 的环境变量需要 Redeploy 才会生效。

Vercel on Tuan's Blog