PrimeEdge 主题教程

评论系统

配置评论系统（Waline On EdgeOne / Twikoo）

评论系统 #

PrimeEdge 通过 params.comments.provider 选择评论系统，目前支持 waline 和 twikoo。当前项目默认使用 Waline On EdgeOne，评论服务地址配置在 params.waline.serverURL。

选择评论系统 #

[params.comments]
  provider = "waline"  # 可选: "waline" 或 "twikoo"

provider 只负责选择加载哪个评论组件；具体组件是否启用，还要看对应的 enable 字段。

Waline On EdgeOne #

Waline On EdgeOne 是配套的评论后端，基于 Hono + EdgeOne Pages Functions + EdgeOne KV 构建，兼容 @waline/client v3 和 Waline Admin。

博客端配置 #

[params.comments]
  provider = "waline"

[params.waline]
  enable = true
  serverURL = "https://wl.example.com"
  version = "3.15.2"
  # lang = "zh-CN"
  # dark = "auto"
  # reaction = false
  # pageview = false
  geetestCaptchaId = ""
参数必填说明
enable是是否启用 Waline 评论组件
serverURL是Waline On EdgeOne 服务地址，不要以 /api 结尾
version否@waline/client 版本，当前默认 3.15.2
lang否Waline 前端语言
dark否深色模式适配，常用 auto
reaction否是否开启文章表情反应
pageview否是否开启浏览量统计
geetestCaptchaId否极验 4.0 的 Captcha ID，只放公开 ID

主题会加载配置版本的 @waline/client，并使用当前页面路径作为评论路径。评论数会从 serverURL + /api/comment?type=count&path=当前路径 获取。

Waline 服务端部署 #

部署 Waline On EdgeOne 时：

配置项值
KV 绑定名WALINE_KV
必填环境变量JWT_SECRET
建议环境变量SECURE_DOMAINS
管理后台/ui
EdgeOne 设置页/ui/worker-setting

SECURE_DOMAINS 用于额外配置允许跨域调用评论 API 的来源域名，多个域名用英文逗号分隔。后台 site_url 也会自动加入允许列表。例如：

example.com,www.example.com

第一次注册的账号会成为管理员。管理员登录后，可在 /ui/worker-setting 配置站点名称、站点地址、博主邮箱、评论审核、IP 限流、邮件通知、PushPlus、图片上传和极验验证。

极验验证 #

Waline On EdgeOne 支持极验行为验证 4.0。启用时需要同时配置前端公开 ID 和后端密钥：

  1. 在 Waline 管理员设置页保存 geetest_captcha_id 和 geetest_captcha_key。
  2. 在博客 config.toml 的 params.waline.geetestCaptchaId 填写相同的 Captcha ID。
  3. 保存服务端设置后，重新部署包含该 Captcha ID 的博客配置。

博客前端只保存 Captcha ID。Captcha Key 只保存在 Waline 服务端 KV 中，用于后端签名校验。前端会提交 lot_number、captcha_output、pass_token、gen_time 四个验证字段；任一字段缺失、SDK 加载失败或服务端校验超时都会阻止评论提交。

评论策略和通知 #

Waline On EdgeOne 后台支持这些常用策略：

设置项说明
匿名评论默认状态approved 直接通过，或 waiting 待审核
登录用户评论默认状态登录用户可单独设置默认审核状态
IP 评论频率限制ipqps，默认 60 秒，设置为 0 可关闭
邮件通知支持 SMTP、Resend、SendGrid
PushPlus新评论或回复后推送到微信
图片上传登录用户可上传图片，支持 KV、七牛云、又拍云

邮件通知优先读取后台设置页保存到 KV 的配置；旧式环境变量仍可作为后备。

图片上传 #

博客 Waline 组件内置 imageUploader，只有登录用户才能上传评论图片。服务端支持：

存储类型说明
KV默认方式，图片存入 WALINE_KV，返回 /api/image/{key}
七牛云在设置页填写 Access Key、Secret Key、Bucket、访问域名
又拍云在设置页填写操作员、密码、Bucket、访问域名

单张评论图片最大 5MB，支持 JPG、PNG、GIF、WebP、AVIF。

PrimeEdge Admin 中管理评论 #

PrimeEdge Admin 左侧菜单中的「评论管理」和「评论设置」不是调用 Waline 服务的 HTTP API，而是直接读写 WALINE_KV。因此如果要在 Admin 后台管理评论，需要给 Admin 项目额外绑定评论服务同一个 KV 命名空间：

Admin 项目绑定名用途
ADMIN_KV后台自身设置和缓存
WALINE_KVWaline 评论数据和评论设置

未绑定 WALINE_KV 时，博客内容管理仍可正常使用，只是评论管理相关接口会提示 WALINE_KV 未绑定。

Twikoo 配置 #

如果需要使用 Twikoo，可以切换 provider：

[params.comments]
  provider = "twikoo"

[params.twikoo]
  enable = true
  envId = "https://your-twikoo-url.com"
  version = "1.7.3"
  # region = "ap-shanghai"
  # lang = "zh-CN"
参数必填说明
enable是是否启用 Twikoo
envId是Twikoo 环境 ID 或服务端 URL
version否Twikoo CDN 版本
region否腾讯云云开发区域
lang否界面语言

评论显示位置 #

评论组件会出现在文章、笔记、好物详情、文档详情、普通页面和留言板页面。首页、列表页、归档页不会显示评论。

当前主题模板没有按单篇 Front Matter 的 comments: false 做统一判断；如果需要关闭单篇评论，可以在模板层增加判断，或临时切换全局 provider / enable。

故障排查 #

评论加载失败

  1. 检查 params.comments.provider 是否与实际服务一致。
  2. 检查 params.waline.enable 或 params.twikoo.enable 是否为 true。
  3. 检查 serverURL 是否能访问，且没有写成 /api 地址。
  4. 检查 Waline 项目的 SECURE_DOMAINS 是否包含博客域名。
  5. 打开浏览器控制台查看 CORS、网络请求或 JS 错误。

提交评论提示需要人机验证

Waline 后台启用了极验验证，但博客前端未配置 geetestCaptchaId，或配置的 Captcha ID 与服务端不一致。

Admin 后台不能管理评论

给 PrimeEdge Admin 项目绑定评论服务同一个 KV，绑定名为 WALINE_KV，然后重新部署 Admin 项目。

下一步 #

评论

0%