一次 Waline 评论区不显示的排查记录
这篇文章记录一次 Waline 评论系统在我博客上「评论不显示」的完整排查过程,包含现象、错误信息、尝试过的方案以及最终的解决办法,算是一份踩坑备忘。
1. 现象回顾
- 页面上提交评论后,当场能看到自己的评论。
- 一刷新页面,评论区只剩输入框和「评论」两个字,历史评论全部消失。
- 浏览器控制台里持续报错:
1 | |
看上去像是 Waline 内部的 Vue 组件在用展开语法 ...xxx 展开了一个不是可迭代对象的东西。
2. 基础配置检查
2.1 Hexo 与 Fluid 主题
先确认 Hexo 侧是不是我自己关掉了评论:
_config.fluid.yml中启用评论:
1 | |
- 生成后的文章 HTML 里,确实能看到:
1 | |
说明 Hexo 和主题基本配置没问题,问题不在「评论组件没挂上」。
2.2 Waline 前端版本
Fluid 主题里预设了 Waline 的静态资源前缀:
1 | |
这意味着页面默认会加载 @waline/client@2.15.8 的前端脚本和样式。
我也在浏览器 Network 面板里确认过,确实拉的是 v2.15.8 的 waline.js 和 waline.css。
3. 服务端与数据检查
前端报错,但不能确定是前端 bug 还是后端响应不对,所以先看服务端和数据层是否正常。
3.1 Waline 版本与接口
从评论接口响应头里可以看到:
1 | |
说明服务端是 Waline 1.x,但处于正常工作状态。
同时在 Vercel 日志中可以看到多次:
POST /api/comment(提交评论)GET /api/comment(加载评论)
状态码都是 200。
3.2 管理后台与数据库
打开 Waline 管理后台:
1 | |
- 在「管理评论」里能看到之前的所有评论。
- 大部分评论状态都是
approved。
说明数据库里的评论数据是存在的、也通过审核了。
3.3 直接查看 API 返回
在浏览器 Network 面板里抓取:
1 | |
响应内容大致如下:
1 | |
也就是说:
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」导致的兼容问题,于是先试了一版:
把
static_prefix.waline强制成 v2:1
2static_prefix:
waline: https://registry.npmmirror.com/@waline/client/2.15.8/files/dist/在主题的
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:
在 Waline 的 Vercel 项目的
package.json中:1
2
3
4
5{
"dependencies": {
"@waline/vercel": "latest"
}
}在 Vercel 里清空缓存并重新部署,让依赖真正升级。
部署完成后重新访问评论接口,响应头里的版本变成:
1
x-waline-version: 1.39.3
说明服务端已经升级到了较新的 1.x。
但遗憾的是,升级后前端的 WalineComment.vue:194 错误依然存在,说明问题不是简单的旧版本 bug。
5.4 完全切换到 Waline v3 客户端
参考官方文档,Waline v3 推荐的使用方式是 ESM 动态导入:
1 | |
于是我和 AI 一起把 Fluid 主题内置的 Waline 集成逻辑整体重写成 v3 风格:
static_prefix.waline改成 v3:1
2static_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 | |
这条错误非常关键,它说明:
Waline v3 客户端会在内部自动拼接
/api/comment;而我在 Hexo 侧配置的
serverURL是:1
2waline:
serverURL: 'https://comment.shaoyanzhe.site/api'
两者叠加后,真正请求的地址就变成了:
1 | |
而 Waline 服务端实际提供的路径是 /api/comment,多了一个 /api,自然 404。
5.6 关键修复:去掉多余的 /api
最终的关键修复只有一行配置:
1 | |
也就是让 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. 经验总结
这次踩坑主要有两个教训:
不要在
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。前后端版本要么一起升级,要么按官方推荐组合来用
- 旧的 1.x 服务端搭配 2.x 客户端,在某些场景下会触发内部数据结构不匹配的问题;
- 比较稳妥的做法是:服务端跟随
@waline/vercel最新 1.x,客户端用官方文档推荐的 v3 ESM 用法。
另外,大模型在这个过程中帮了不少忙:
- 帮我逐步排除了「配置关掉」、「接口没通」、「数据丢失」这些干扰项;
- 给出了几种版本搭配的思路(前端 v1/v2/v3 和服务端 1.x 的不同组合);
- 最后协助我把 Fluid 主题内置的 Waline 集成重写成 v3 ESM 风格。
如果你也遇到了「Waline 评论提交后一刷新就不见了」或者前端报 WalineComment.vue 相关的 spread 语法错误,可以从以下几个点开始排查:
- 先确认接口
/api/comment是否 200,且errno: 0、data.count正常; - 检查
serverURL是否多写了/api; - 查看响应头里的
x-waline-version,确认服务端版本; - 根据版本选择合适的客户端接入方式(推荐 v3 ESM)。
希望这篇记录能帮你少踩几个坑。***