我是基于ChatGPT-turbo-3.5实现的AI助手,在此网站上负责整理和概括文章

本文记录了使用Hexo+ShokaX主题搭建个人博客的过程。首先介绍了准备工作,包括安装Node.js和包管理器pnpm。然后详细说明了Hexo的安装步骤以及ShokaX主题的安装和配置过程。最后,给出了基本配置的步骤,包括markdown配置、停用默认代码高亮、文件压缩和feed生成等。通过本文的指导,可以顺利搭建个人博客并进行初步配置。

本文记录了我的搭建过程,以及过程中我遇到的问题和解决方法,应该可以给同样想要搭建 shokax 主题博客的大家提供一定的参考。

以下均由博主自行摸索得来,其中如果有误,还请各位大佬指正。

博主半瓶水术语使用不专业,如若有疑问,欢迎留言咨询。

因文章比较长想多水几篇,故分成几个以提升观感,可以点击下面进行跳转

1️⃣主题安装 - 2️⃣主题部署 - [3️⃣配套功能] - [4️⃣主题美化]

# 准备工作

# Node.js

根据官方文档中所述,ShokaX 主题需要 nodejs 18 以及更高的版本,因此需要提前准备好,避免到时候掉链子

如果你已经安装好 nodejs 的话,可以直接跳过去下一步

如果没有的话,这边推荐使用 nvm, 方便以后管理 nodejs 版本,有时候不同的项目要求的 nodejs 版本不同,来回切换真的很麻烦

通过 nvm 可以快速的切换 nodejs 版本,去 Github 下载最新版 nvm 安装程序

image-20250223164620331

之后一直下一步就行了

image-20250223165729195

装完之后 Win + R 打开命令提示符,输入

nvm version

能看见版本号就说明安装好了

image-20250223172119900

接下来就是安装 node 了

在命令提示符里面输入

nvm install 18.19.0
#静静等待安装完成的提示
#速度慢的话切换国内镜像,网上教程很多,我就不过多赘述了,毕竟这不是今天的主题
nvm use 18.19.0

到此 nodejs 就算安装成功了

# 包管理器 pnpm

接下来安装包管理器,官方文档建议我们使用 pnpm,那我们就安装它

很简单,只需要在命令提示符里面输入

npm install -g pnpm@latest-10

# Hexo 安装

打开命令提示符,输入以下命令

pnpm add hexo-cli -g
#cd 你的博客目录
hexo init
#静静等待命令执行完成

完成之后我们会得到如图所示的一堆文件

image-20250223190336257

命令行执行 hexo s ,打开给出的那串地址,可以看到 hexo 已经安装成功了

image-20250223225415009

# ShoaX 安装

下面我们 cd 到 themes 进行 ShokaX 主题的安装

cd themes
git clone https://github.com/theme-shoka-x/hexo-theme-shokaX.git 
#这里可以替换成你自己的仓库,建议 fork 主题仓库,方便后续更新主题
#clone 完成之后,把 hexo-theme-shokaX 重命名成 shokax
cd shokax
node ./toolbox/compiler.mjs

这时候遇到报错了,先别急,仔细看看,貌似是缺少 esbuild 依赖包,我们把它装上

image-20250223223408250

命令行执行 pnpm add esbuild

pnpm add esbuild

等待安装完成之后再次执行刚刚报错的命令就能够顺利执行了

编译完成之后我们 cd 到 hexo 根目录,执行下面的命令

cd ../..
node ./themes/shokax/toolbox/hoistdep.mjs

等待运行完成之后,打开 hexo 根目录的 _config.yml ,把 theme: landscape 改成 theme: shokax

顺便再把 language: cn 改成 language: zh-CN 更换博客主语言

接着再次 hexo s 进行预览,看见下面这样的,就已经成功 90% 了

Ctrl + C 可以结束进程

image-20250223230715930

# 基本配置

在此之前

记得把 hexo 根目录的 _config.landscape.yml 重命名为 _config.shokax.yml

这很重要,把主题配置独立出来,既方便管理,也能避免主题更新时配置被覆盖的问题

# markdown 配置

打开 hexo 根目录的 _config.yml 文件,把下面的配置加到最后面 注意缩进

markdown:
  render: # 渲染器设置
    html: false # 过滤 HTML 标签
    xhtmlOut: true # 使用 '/' 来闭合单标签 (比如 <br />)。
    breaks: true # 转换段落里的 '\n' 到 <br>。
    linkify: true # 将类似 URL 的文本自动转换为链接。
    typographer:
    quotes: "“”‘’"
  plugins: # markdown-it 插件设置
    - plugin:
        name: markdown-it-toc-and-anchor
        enable: true
        options: # 文章目录以及锚点应用的 class 名称,shoka 系主题必须设置成这样
          tocClassName: "toc"
          anchorClassName: "anchor"
    - plugin:
        name: markdown-it-multimd-table
        enable: true
        options:
          multiline: true
          rowspan: true
          headerless: true
    - plugin:
        name: ./markdown-it-furigana
        enable: true
        options:
          fallbackParens: "()"
    - plugin:
        name: ./markdown-it-spoiler
        enable: true
        options:
          title: "你知道得太多了"

# 停用默认代码高亮

打开 hexo 根目录 package.json ,查看 hexo 的版本,停用内建代码高亮组件

shokax 自己的渲染器自带代码高亮

如果小于等于 6.3.0 ,修改 _config.yml

highlight:
  enable: false
prismjs:
  enable: false

如果大于等于 7.0.0-rc1

syntax_highlighter: false

# 文件压缩

把下面的配置加到 _config.yml 末尾

minify:
  js:
    enable: false # ShokaX 自带 esbuild 优化,不建议开启,其他主题建议开启
    exclude: # 排除文件,接受 string [],需符合 micromatch 格式
  css:
    enable: true # 开启 CSS 优化
    options:
      targets: ">= 0.5%" # browserslist 格式的 target
    exclude: # 排除文件,接受 string [],需符合 micromatch 格式
  html:
    minifier: html-minifier
    enable: true # 开启 HTML 优化
    options:
      comments: false # 是否保留注释内容
    exclude: # 排除文件,接受 string [],需符合 micromatch 格式
  image:
    enable: false # 开启图片预处理和自动 WebP 化
    options:
      avif: false
      webp: true # 预留配置项,现版本无作用
      quality: 80 # 质量,支持 1-100 的整数、lossless 或 nearLossless
      effort: 2 # CPU 工作量,0-6 之间的整数 (越低越快)
      replaceSrc: false # 自动替换生成 html 中的本地图片链接为 webp 链接
      # 对于使用 CI 工作流部署的用户,请注意本配置可能导致图片 404,如果出现请关闭
      # 我们更建议使用 Service Worker 来在用户侧实现 replaceSrc 的功能,这将能够以一种侵入式更小的方式实现链接替换
    exclude:

# feed 生成

同样加到 _config.yml 末尾

feed:
  limit: 20
  order_by: "-date"
  tag_dir: false
  category_dir: false
  rss:
    enable: true
    template: "node_modules/hexo-theme-shokax/layout/_alternate/rss.ejs"
    output: "rss.xml"
  atom:
    enable: true
    template: "node_modules/hexo-theme-shokax/layout/_alternate/atom.ejs"
    output: "atom.xml"
  jsonFeed:
    enable: true
    template: "node_modules/hexo-theme-shokax/layout/_alternate/json.ejs"
    output: "feed.json"

# 其他问题

# hexo g/s 报错

image-20250224003038064

  • 解决办法:hexo 根目录执行 pnpm add hexo-theme-shokax
pnpm add hexo-theme-shokax

# 文档不渲染 / 部分渲染

  • 解决办法:更换 hexo 自带 md 渲染器为 shokax 的 md 渲染器,hexo 根目录执行
pnpm remove hexo-renderer-marked
pnpm add hexo-renderer-multi-next-markdown-it
hexo clean && hexo g
 #如果问题仍然存在,系浏览器缓存问题,清除缓存之后再次尝试