从 Shoka 迁移

前言

本教程提供给需要从 Shoka 迁移到 Hexo 驱动的 ShokaX 0.5.x 的用户

ShokaX 对于 Shoka 进行了大量修改（包括核心技术栈在内），并且使用了基于 esbuild 的构建系统，因此：

• 如果你的编程能力比较差且使用了大量非自己编写的魔改，你要做好这些魔改无法迁移到 ShokaX 的准备
• ShokaX 可能需要和主流 Hexo 主题不同的安装、配置和运行等内容
• 你应当按照一个半现代的 ESM Typescript 项目来理解 ShokaX，而非传统 Hexo 主题

核心技术栈修改

相较于 Shoka，我们修改了以下核心技术栈：

• Nunjucks 修改为 Pug
• JavaScript ES5 升级到 TypeScript ES2022
• 基于 esbuild 而非文本拼接进行构建
• 引入了 Vue 框架，支持使用预构建的 Vue 3 SFC
• 使用 Aether 渲染器代替了原先的渲染器

这意味着：

• 一切对于生成模板的修改均无法直接迁移到 ShokaX，需进行 Njk -> Pug 转写
• 部分依赖旧特性运行的代码可能无效
• 可以使用import导入代码而无需使用 CDN + UMD
• 可以直接导入 Vue 组件库（需要自行使用 Vite 预构建为 init 函数形式，可见 ShokaX-UIKit）
• 不再官方支持 Mermaid 和 Graphviz 两个功能
• 使用 Shiki 代码高亮替代了原先的 Prism.js

主要调整

主要配置调整

大部分配置都无法直接沿用 Shoka，建议参照 yml 文件注释和配置文档进行修改，这里提供几个关键修改内容：

• images配置修改为assets，同时不再支持使用远程 CDN 作为statics基准路径
• 不再支持 Valine/MiniValine 作为评论系统
• vendors配置被完全修改，务必删除来自 Shoka 的 Vendors 配置
• 精选分类不再自动生成，需要设置cateCards配置

评论系统

ShokaX 出于：

• 对隐私和安全的保护，不再支持 Valine
• 不使用 EOL 包的原因，不再支持 MiniValine

因此，你必须迁移到 Waline 或者 Twikoo 才能继续使用评论系统，我们建议使用 Waline，因为其对于现代化特性响应更积极，代码更加健壮，也和原来的 Valine 更加适配

服务端侧迁移方法见从 Valine 迁移 客户端侧你需要按照 Waline 的教程重新配置评论系统，可见 主题配置文件中waline部分

模块化与分包机制

ShokaX 基于 esbuild 实现了一套半现代化构建系统，因此，我们支持了模块化引入和 tree-shaking 功能：

# ShokaX 模块化分包引入设置
# 请关闭所有不使用的模块以优化主题 js 体积和性能
modules:
  debug: false # 启用调试模式
  player: true # 启用音乐播放器
  fireworks: true # 启用鼠标点击烟花特效
  visibilityListener: true # 启用可见度监听器
  tabs: true # 启用选项卡扩展支持，如需开启 summary 功能请一并开启
  quiz: true # 启用文章内问题扩展支持
  # 使用 Cloudflare Rocket 或其他优化功能时需开启下列补丁，否则主题无法渲染
  cloudflarePatch: false

此处注释已经足够清楚，故不再赘述

首页封面图

因为有关图床失效，ShokaX 不再支持通过新浪方式加载图片，你需要添加站内或者CDN的图片，站内用以/开头的绝对路径，CDN或图床图片必须以https开头

安装和升级

建站时间较短的站点

对于建站时间较短，且几乎没有魔改的站点，我们建议按照全新安装方式，使用即食罐头安装，并手动迁移文章部分

可见使用 ShokaX 即食罐头

建站时间较长的站点

对于建站时间较长的站点且具有大量魔改的站点，我们提供两种迁移方式建议：

基于 Git 的方式迁移安装

见使用 git 安装 ShokaX

我们高度建议 Fork 一个 ShokaX 仓库，并将魔改后的 ShokaX 同步到你 Fork 的仓库中，这样在后续 ShokaX 更新时，你能够迅速地迁移到新版本

由于 ShokaX 采用 Pug 作为底层模板，很多魔改很可能需要单独适配，当你的站点本身魔改很多，且涉及底层修改时，可见下一种方法

渐进式迁移

整体上而言，ShokaX开发经历如下四个阶段：

Shoka -> ShokaX 0.0.x/0.1.x/0.2.x -> ShokaX 0.3.x/0.4.x -> ShokaX 0.5.x -WIP-> ShokaX UIKit Series(ShokaX 0.6或0.7)

1. 0.0.x-0.2.x阶段：此阶段内 ShokaX 修改仅涉及模板，未涉及其他部分，迁移较简单
2. 0.3.x-0.4.x阶段：此阶段引入了基于 esbuild的构建系统并对 JS 进行了大规模重构和 ESM 化
3. 0.5.x 阶段：此阶段移除了 Pjax 和很多旧 API，很多依赖跨页SPA体验的魔改需要重构（如全局持久化）
4. UIKit 系列（开发中）：指基于 ShokaX-UIKit 开发的多平台 ShokaX 主题，基于 Vue 进行了整体重构

我们建议对于修改较多的站点采用渐进式迁移，即先迁移到低版本，再逐步向高版本迁移