一次 Waline 评论区不显示的排查记录

这篇文章记录一次 Waline 评论系统在我博客上「评论不显示」的完整排查过程,包含现象、错误信息、尝试过的方案以及最终的解决办法,算是一份踩坑备忘。

1. 现象回顾

  • 页面上提交评论后,当场能看到自己的评论。
  • 一刷新页面,评论区只剩输入框和「评论」两个字,历史评论全部消失。
  • 浏览器控制台里持续报错:
1
WalineComment.vue:194 Spread syntax requires ...iterable[Symbol.iterator] to be a function

看上去像是 Waline 内部的 Vue 组件在用展开语法 ...xxx 展开了一个不是可迭代对象的东西。

2. 基础配置检查

2.1 Hexo 与 Fluid 主题

先确认 Hexo 侧是不是我自己关掉了评论:

  • _config.fluid.yml 中启用评论:
1
2
3
4
post:
comments:
enable: true
type: waline
  • 生成后的文章 HTML 里,确实能看到:
1
2
3
4
<div id="waline"></div>
<script>
// Waline 初始化脚本
</script>

说明 Hexo 和主题基本配置没问题,问题不在「评论组件没挂上」。

2.2 Waline 前端版本

Fluid 主题里预设了 Waline 的静态资源前缀:

1
2
static_prefix:
waline: https://registry.npmmirror.com/@waline/client/2.15.8/files/dist/

这意味着页面默认会加载 @waline/client@2.15.8 的前端脚本和样式。

我也在浏览器 Network 面板里确认过,确实拉的是 v2.15.8 的 waline.js 和 waline.css。

3. 服务端与数据检查

前端报错,但不能确定是前端 bug 还是后端响应不对,所以先看服务端和数据层是否正常。

3.1 Waline 版本与接口

从评论接口响应头里可以看到:

1
x-waline-version: 1.33.0

说明服务端是 Waline 1.x,但处于正常工作状态。

同时在 Vercel 日志中可以看到多次:

  • POST /api/comment(提交评论)
  • GET /api/comment(加载评论)

状态码都是 200。

3.2 管理后台与数据库

打开 Waline 管理后台:

1
https://comment.shaoyanzhe.site/ui
  • 在「管理评论」里能看到之前的所有评论。
  • 大部分评论状态都是 approved。

说明数据库里的评论数据是存在的、也通过审核了。

3.3 直接查看 API 返回

在浏览器 Network 面板里抓取:

1
GET https://comment.shaoyanzhe.site/api/comment?path=/2025/12/08/我的第一篇博客/&pageSize=10&page=1&lang=zh-CN&sortBy=insertedAt_desc

响应内容大致如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"errno": 0,
"errmsg": "",
"data": {
"page": 1,
"totalPages": 1,
"pageSize": 10,
"count": 9,
"data": [
{ "nick": "邵岩哲", "status": "approved", "comment": "<p>...</p>" },
{ "nick": "豆包", "status": "approved", "comment": "<p>博主好帅</p>" },
{ "nick": "Pilgrimage Shao", "status": "approved", "comment": "<p>...</p>" }
// 省略其他若干
]
}
}

也就是说:

  • errno: 0,没有业务错误。
  • count: 9,一共 9 条评论。
  • 每条评论都是 status: "approved"。

结论:服务端接口是好的,数据也正常返回到了前端。

4. 初步判断:前端内部渲染错误

综合前面的信息:

  • 配置没关评论;
  • 服务端版本正常、数据库有数据、接口返回 200 且带 9 条评论;
  • 前端控制台报的是 Waline 内部组件 WalineComment.vue 的展开语法错误。

比较合理的判断是:

服务端「给了」数据,但是 Waline 前端在解析 / 渲染时,把一个错误的数据结构做了 ... 展开,结果抛异常,导致后续 UI 不渲染。

也就是典型的 Waline 前端 bug 或服务端 / 客户端版本组合问题,而不是简单的路径配置错误。

5. 和 AI 一起的几轮试错

接下来就是我和大模型一起折腾的几轮调试,这里按时间线总结一下。

5.1 尝试统一到 Waline v2 客户端

起初怀疑是「前端 v3 + 服务端 v1.33.0」导致的兼容问题,于是先试了一版:

  1. 把 static_prefix.waline 强制成 v2:

    1
    2
    static_prefix:
    waline: https://registry.npmmirror.com/@waline/client/2.15.8/files/dist/
  2. 在主题的 waline.ejs 里显式指定 v2 的多个 CDN 作为 fallback。

这一步主要是排除「前端无意中拉到 v3」的情况。
确认真的是 v2 客户端以后,WalineComment.vue:194 的错误依然存在,说明问题不只是「v3 对旧服务端不兼容」那么简单。

5.2 尝试降级到 v1 客户端(失败)

后来一度尝试让前端也降到 v1,和服务端 1.33.0 对齐:

  • 把 static_prefix.waline 指到了 v1;
  • waline.ejs 里手写 v1 的 CDN 地址。

结果发现 v1 的文件结构和现在主题期望的不完全一样,很多路径 404,直接触发我自己写的「Waline script load failed」日志,评论区连组件都挂不上,这条路线就放弃了。

5.3 升级 Waline 服务端到最新 1.x

既然客户端版本不好降,那就把服务端升级到 Waline 官方最新的 1.x:

  1. 在 Waline 的 Vercel 项目的 package.json 中:

    1
    2
    3
    4
    5
    {
    "dependencies": {
    "@waline/vercel": "latest"
    }
    }
  2. 在 Vercel 里清空缓存并重新部署,让依赖真正升级。

  3. 部署完成后重新访问评论接口,响应头里的版本变成:

    1
    x-waline-version: 1.39.3

说明服务端已经升级到了较新的 1.x。

但遗憾的是,升级后前端的 WalineComment.vue:194 错误依然存在,说明问题不是简单的旧版本 bug。

5.4 完全切换到 Waline v3 客户端

参考官方文档,Waline v3 推荐的使用方式是 ESM 动态导入:

1
2
3
4
5
6
7
8
9
<link rel="stylesheet" href="https://unpkg.com/@waline/client@v3/dist/waline.css" />
<script type="module">
import { init } from 'https://unpkg.com/@waline/client@v3/dist/waline.js';

init({
el: '#waline',
serverURL: 'https://comment.example.com',
});
</script>

于是我和 AI 一起把 Fluid 主题内置的 Waline 集成逻辑整体重写成 v3 风格:

  • static_prefix.waline 改成 v3:

    1
    2
    static_prefix:
    waline: https://unpkg.com/@waline/client@v3/dist/
  • waline.ejs 中:

    • 用 Fluid.utils.createCssLink 加载 v3 的 waline.css;
    • 用原生 import('https://unpkg.com/@waline/client@v3/dist/waline.js') 动态加载 JS 模块;
    • 从模块中抽出 init 方法,按 v3 的方式调用;
    • 将 _config.fluid.yml 里的 serverURL/path/lang/emoji 等配置作为参数传给 init;
    • 保留主题原有的图片灯箱、图床等增强逻辑。

这一轮之后,前端的「扩展不可迭代对象」那条错误消失了,说明 v3 客户端本身是健康的。

5.5 发现 /api/api/comment 的 404

然而评论区依旧没有历史评论,只是这次控制台错误变成了:

1
2
GET https://comment.shaoyanzhe.site/api/api/comment?... 404 (Not Found)
Get comment data failed with 404: url `/api/api/comment` not found.

这条错误非常关键,它说明:

  • Waline v3 客户端会在内部自动拼接 /api/comment;

  • 而我在 Hexo 侧配置的 serverURL 是:

    1
    2
    waline:
    serverURL: 'https://comment.shaoyanzhe.site/api'

两者叠加后,真正请求的地址就变成了:

1
https://comment.shaoyanzhe.site/api/api/comment

而 Waline 服务端实际提供的路径是 /api/comment,多了一个 /api,自然 404。

5.6 关键修复:去掉多余的 /api

最终的关键修复只有一行配置:

1
2
waline:
serverURL: 'https://comment.shaoyanzhe.site'

也就是让 serverURL 只写域名,不包含 /api 前缀,剩下的路径完全交给 Waline 客户端自己去拼。

修改 Hexo 配置后重新构建、部署,浏览器里可以看到:

  • 请求地址变成了:

    1
    https://comment.shaoyanzhe.site/api/comment?path=...&pageSize=10&page=1&lang=zh-CN&sortBy=insertedAt_desc
  • 状态码 200,响应仍然是那 9 条评论;

  • 评论区成功渲染出所有历史评论;

  • 控制台无报错。

至此,这个问题终于闭环。

6. 经验总结

这次踩坑主要有两个教训:

  1. 不要在 serverURL 里带上 /api
    Waline v2/v3 客户端会自己在内部拼接 /api/comment、/api/recent 等路径,serverURL 应该只写到服务端根地址即可,例如:

    1
    serverURL: 'https://comment.example.com'

    如果写成 https://comment.example.com/api,就会变成 /api/api/comment,直接 404。

  2. 前后端版本要么一起升级,要么按官方推荐组合来用

    • 旧的 1.x 服务端搭配 2.x 客户端,在某些场景下会触发内部数据结构不匹配的问题;
    • 比较稳妥的做法是:服务端跟随 @waline/vercel 最新 1.x,客户端用官方文档推荐的 v3 ESM 用法。

另外,大模型在这个过程中帮了不少忙:

  • 帮我逐步排除了「配置关掉」、「接口没通」、「数据丢失」这些干扰项;
  • 给出了几种版本搭配的思路(前端 v1/v2/v3 和服务端 1.x 的不同组合);
  • 最后协助我把 Fluid 主题内置的 Waline 集成重写成 v3 ESM 风格。

如果你也遇到了「Waline 评论提交后一刷新就不见了」或者前端报 WalineComment.vue 相关的 spread 语法错误,可以从以下几个点开始排查:

  1. 先确认接口 /api/comment 是否 200,且 errno: 0、data.count 正常;
  2. 检查 serverURL 是否多写了 /api;
  3. 查看响应头里的 x-waline-version,确认服务端版本;
  4. 根据版本选择合适的客户端接入方式(推荐 v3 ESM)。

希望这篇记录能帮你少踩几个坑。***


一次 Waline 评论区不显示的排查记录
https://shaoyanzhe.site/2026/03/22/waline-comment-debug/
作者
邵岩哲
发布于
2026年3月22日
许可协议