# Hexo Shoka 主题 Waline 评论系统升级报告

# 项目概述

本报告详细记录了如何将 Waline v2 评论系统集成到 Hexo Shoka 主题中。原主题仅支持 MiniValine 评论系统，现已成功扩展支持 Waline 和 Valine，并实现动态切换功能。

升级日期: 2026 年 2 月
Waline 版本: v2 (使用 UMD 格式)
主题: Hexo Shoka
服务器地址: https://waline.vull.top

# 技术决策

# 为什么选择 Waline v2 而非 v3？

在集成过程中，我们最初尝试使用 Waline v3，但遇到了模块兼容性问题：

• 问题: Waline v3 使用 ES Module 格式，与 Shoka 主题的 UMD 加载器不兼容
• 解决方案：降级到 Waline v2，该版本提供完整的 UMD 支持
• CDN 路径: npm/@waline/client@v2/dist/waline.js

# 架构设计

采用条件加载策略，根据配置文件动态选择评论系统：

if (CONFIG.waline && CONFIG.waline.enable) {

  // 加载 Waline

} else {

  // 加载 Valine (默认)

}

# 修改文件清单

共修改 6 个文件，新增约 97 行代码：

# 1. themes/shoka/_config.yml (配置文件)

修改内容:

• 添加 Waline 配置块
• 配置 Waline CDN 资源路径

关键配置:

# Waline 评论系统

waline:

  enable: true

  serverURL: https://waline.vull.top

  locale:

    placeholder: 请文明评论呀

  commentCount: false

  pageview: false

  lang: zh-CN

  search: false

  reaction: false

  imageUploader: false

  requiredMeta:

    - nick

vendors:

  css:

    waline: npm/@waline/client@v2/dist/waline.css

  js:

    waline: npm/@waline/client@v2/dist/waline.js

配置说明:

• enable : 启用 / 禁用 Waline (设为 false 则回退到 Valine)
• serverURL : Waline 服务器地址
• locale.placeholder : 评论框占位符文本
• lang : 界面语言 (zh-CN/en-US)
• search : 表情包搜索功能
• reaction : 文章反应功能
• imageUploader : 图片上传功能
• requiredMeta : 必填字段 (nick/mail/link)

# 2. themes/shoka/scripts/generaters/script.js (后端配置生成)

修改内容:

• 扩展 CONFIG 对象，添加 Waline 配置
• 添加 Waline 资源路径到 js 和 css 对象

代码变更:

var siteConfig = {

  //... 其他配置

  js: {

    valine: theme.vendors.js.valine,

    waline: theme.vendors.js.waline,  // 新增

    // ...

  },

  css: {

    valine: theme.css + "/comment.css",

    waline: theme.vendors.css.waline,  // 新增

    // ...

  },

  valine: theme.valine,

  waline: theme.waline,  // 新增

};

作用：将 _config.yml 中的 Waline 配置传递到前端 JavaScript

# 3. themes/shoka/layout/_partials/layout.njk (模板文件)

修改内容:

• 在 LOCAL 对象中添加 waline 标志
• 实现条件渲染逻辑

代码变更:

<!--swig2-->

<!--swig3-->

LOCAL.waline = <!--swig0-->,

<!--swig4-->

LOCAL.valine = <!--swig1-->,

<!--swig5-->

<!--swig6-->

作用：根据主题配置决定传递 waline 还是 valine 标志到前端

# 4. themes/shoka/source/js/_app/pjax.js (核心初始化逻辑)

修改内容:

• 实现 Waline 初始化逻辑
• 添加错误处理和调试日志
• 保持与 Valine 的兼容性

完整代码:

const siteRefresh = function (reload) {

  //... 其他代码

  // 支持 Waline 和 Valine

  if (CONFIG.waline && CONFIG.waline.enable) {

    vendorCss('waline');

    vendorJs('waline', function() {

      var options = Object.assign({}, CONFIG.waline);

      options = Object.assign(options, LOCAL.waline||{});

      // Waline v2 使用 Waline.init ()

      if (typeof Waline !== 'undefined') {

        try {

          Waline.init({

            el: '#comments',

            serverURL: options.serverURL,

            path: LOCAL.path,

            lang: options.lang || 'zh-CN',

            locale: options.locale,

            emoji: options.emoji,

            meta: options.meta || ['nick', 'mail', 'link'],

            requiredMeta: options.requiredMeta || [],

            pageSize: options.pageSize || 10,

            wordLimit: options.wordLimit,

            login: options.login || 'enable',

            pageview: options.pageview || false,

            comment: options.commentCount || false,

            search: options.search !== undefined ? options.search : false,

            reaction: options.reaction !== undefined ? options.reaction : false,

            imageUploader: options.imageUploader !== undefined ? options.imageUploader : false

          });

          console.log('Waline 初始化成功');

        } catch (e) {

          console.error('Waline 初始化失败:', e);

        }

      } else {

        console.error('Waline 未加载');

      }

      setTimeout(function(){

        positionInit(1);

        postFancybox('.wl-content');

      }, 1000);

    }, window.Waline);

  } else {

    // Valine 初始化逻辑 (保持不变)

    vendorJs('valine', function() {

      var options = Object.assign({}, CONFIG.valine);

      options = Object.assign(options, LOCAL.valine||{});

      options.el = '#comments';

      options.pathname = LOCAL.path;

      options.pjax = pjax;

      options.lazyload = lazyload;

      new MiniValine(options);

      setTimeout(function(){

        positionInit(1);

        postFancybox('.v');

      }, 1000);

    }, window.MiniValine);

  }

  //... 其他代码

}

关键技术点:

1. 配置合并：使用 Object.assign() 合并全局配置和页面级配置
2. API 调用: Waline v2 使用 Waline.init() 而非 new Waline()
3. 错误处理：添加 try-catch 和类型检查
4. 延迟初始化：使用 setTimeout 确保 DOM 完全加载
5. Fancybox 集成：为 Waline 评论内容 ( .wl-content ) 启用图片灯箱

# 5. themes/shoka/source/js/_app/page.js (评论加载逻辑)

修改内容:

• 修改 loadComments() 函数支持动态评论系统检测
• 使用 IntersectionObserver 实现懒加载

代码变更:

const loadComments = function () {

  var element = $('#comments');

  if (!element) {

    goToComment.display("none")

    return;

  } else {

    goToComment.display("")

  }

  // 支持 Waline 和 Valine

  var commentType = CONFIG.waline && CONFIG.waline.enable ? 'waline' : 'valine';

  if (!window.IntersectionObserver) {

    vendorCss(commentType);

  } else {

    var io = new IntersectionObserver(function(entries, observer) {

      var entry = entries[0];

      vendorCss(commentType);

      if (entry.isIntersecting || entry.intersectionRatio > 0) {

        transition($('#comments'), 'bounceUpIn');

        observer.disconnect();

      }

    });

    io.observe(element);

  }

}

优化点:

• 动态检测评论系统类型
• 仅在评论区进入视口时加载 CSS
• 降级支持不支持 IntersectionObserver 的浏览器

# 6. themes/shoka/source/css/comment.styl (样式文件)

修改内容:

• 添加 Waline 特定样式

新增代码:

// Waline 样式支持

.wl-container

  margin-top: 2rem

.wl-content

  word-break: break-word

.wl-editor

  border-radius: 4px

.wl-panel

  border-radius: 4px

样式说明:

• .wl-container : 评论容器顶部间距
• .wl-content : 评论内容自动换行
• .wl-editor : 编辑器圆角
• .wl-panel : 面板圆角

# 功能特性

# ✅ 已实现功能

1. 双评论系统支持

   • Waline v2
   • MiniValine (Valine 变体)
   • 通过配置文件一键切换

2. 完整配置传递

   • 后端配置 → 前端 CONFIG 对象
   • 页面级配置覆盖全局配置

3. 懒加载优化

   • CSS 资源按需加载
   • 使用 IntersectionObserver 监听视口

4. 错误处理

   • 初始化失败捕获
   • 控制台调试日志

5. 向后兼容

   • 保留原有 Valine 配置
   • 无缝切换不影响现有功能

6. 中文本地化

   • 自定义占位符文本
   • 中文界面语言

# 🔧 可选功能

通过配置文件可启用 / 禁用：

• 评论数统计 ( commentCount )
• 浏览量统计 ( pageview )
• 表情包搜索 ( search )
• 文章反应 ( reaction )
• 图片上传 ( imageUploader )
• 自定义表情包 ( emoji )

# 使用指南

# 启用 Waline

编辑 themes/shoka/_config.yml :

waline:

  enable: true  # 设为 true 启用 Waline

  serverURL: https://your-waline-server.com

# 切换回 Valine

waline:

  enable: false  # 设为 false 禁用 Waline，自动使用 Valine

# 页面级配置

在文章 Front Matter 中覆盖全局配置：

---

title: 我的文章

waline:

  locale:

    placeholder: 这篇文章欢迎评论！

---

# 禁用评论

---

title: 关于页面

comment: false  # 完全禁用评论

---

# 测试验证

# 测试环境

• 浏览器: Chrome, Firefox, Safari
• 设备: Desktop, Mobile
• 测试页面：文章页、首页、归档页

# 测试结果

✅ 功能测试

• Waline 评论框正常显示
• 评论提交成功
• 评论列表正常加载
• 表情包选择器工作正常

✅ 兼容性测试

• Valine 切换正常
• PJAX 页面跳转无异常
• 图片灯箱 (Fancybox) 正常工作

✅ 性能测试

• CSS/JS 懒加载生效
• 首屏加载无阻塞
• 控制台无错误

# 已知问题

⚠️ 服务器端问题 (非前端集成问题)

• Waline 服务器注册时偶现 500 错误
• 建议检查服务器配置和数据库连接

# 技术难点与解决方案

# 难点 1: Waline v3 模块兼容性

问题: Waline v3 使用 ES Module，Shoka 主题使用 UMD 加载器

解决方案:

# 使用 v2 版本

vendors:

  js:

    waline: npm/@waline/client@v2/dist/waline.js

# 难点 2: LOCAL 对象缺失 waline 标志

问题：前端无法判断是否启用 Waline

解决方案：在 layout.njk 中添加条件逻辑

<!--swig7-->

waline: true,

<!--swig8-->

# 难点 3: Waline.init () API 混淆

问题：文档中 v2 和 v3 API 混用

解决方案:

//v2 正确用法

Waline.init({ el: '#comments', ... })

// 错误用法 (v3)

// new Waline({ el: '#comments', ... })

# 代码统计

# 维护建议

# 日常维护

1. 定期更新 Waline 版本

   	vendors:
   	js:
   	waline: npm/@waline/[email protected]/dist/waline.js

2. 监控控制台日志

   • 检查 "Waline 初始化成功" 消息
   • 关注错误日志

3. 备份配置文件

   • _config.yml
   • mcp.json (如使用)

# 升级到 Waline v3 (未来)

当 Shoka 主题支持 ES Module 时：

1. 修改 CDN 路径:

   waline: npm/@waline/client@v3/dist/waline.js

2. 更新初始化代码:

   	import { init } from '@waline/client';
   	init({ el: '#comments', ... });

# 参考资源

• Waline 官方文档: https://waline.js.org/
• Waline v2 API: https://v2.waline.js.org/
• Hexo Shoka 主题: https://github.com/amehime/hexo-theme-shoka
• 项目服务器: https://waline.vull.top

# 总结

本次升级成功将 Waline v2 评论系统集成到 Hexo Shoka 主题中，实现了以下目标：

✅ 功能完整：支持 Waline 所有核心功能
✅ 向后兼容：保留 Valine 支持，可随时切换
✅ 性能优化：懒加载 CSS/JS 资源
✅ 易于维护：配置集中管理，代码结构清晰
✅ 用户友好：中文本地化，自定义占位符

升级影响：最小化侵入，仅修改 6 个文件，无破坏性变更

用户反馈: "评论系统正常使用了" ✅

报告生成日期: 2026 年 2 月 7 日
报告版本: 1.0
维护者: Vullfin