Hexo博客NexT主题从v5.x.x更新到v6.x.x的记录及总结

发表于 | 分类于
本文字数： 11k | 阅读时长 ≈ 19 分钟

当这个村庄局限我的一生时，小小的地球正在局限着整个人类。

——刘亮程《一个人的村庄》

简介

  • 因为nexT主题从v5.1.x更新到v6.0.x后，主仓库已从 iissnan 名下迁移至 theme-next 组织。所以就导致每次在终端生成、部署博客的时候，会有主题迁移的信息。虽然没什么实质的影响，但是每次看到后总会有些影响心情。

    1
    2
    3
    4
    5
    6
    7
    WARN  ===============================================================
    WARN  ========================= ATTENTION! ==========================
    WARN  ===============================================================
    WARN   NexT repository is moving here: https://github.com/theme-next
    WARN  ===============================================================
    WARN   It's rebase to v6.0.0 and future maintenance will resume there
    WARN  ===============================================================

  • 所以趁着今天的空余时间，就把博客主题直接更新到最新版本了。因为更新会牵扯到一些自定义的文件及样式配置，所以就需要格外小心谨慎，更新中遇到的问题及相关解决方案记录于此，留作遇到相同问题的小伙伴参考。

  • 更新前：Hexo v3.7.1 vs NexT.Muse v5.1.4
  • 更新后：Hexo v3.7.1 vs NexT.Muse v6.4.1（截止更新时是最新版本）

正文

更新准备 & 安装

  • 更新前，请参考官方的升级指导从 NexT v5.1.x 更新，强烈建议按照官方推荐的升级方式，即使出错，也可以回退到之前可用的版本。
  • 关于新主题的下载及目录，官方指导文档已经很清楚了，也很简单，这里就不在赘述。

站点配置文件

  • 站点配置文件_config.yml位于博客站点的根目录下。
  • 下载完新的主题后，建议将主题目录下的_config.yml文件备份一份，便于修改出错恢复。
  • 分别打开原next目录和新版本next-reloaded目录下的_config.yml文件，进行对比更改。

    修改语言配置文件

  • 新版本语言配置文件命名发生变化，所以需要修改站点配置文件：

    • 搜索language:字段，将后面的zh-Hans 改为 zh-CN 。

      1
      2
      - language: zh-Hans
      + language: zh-CN

修改加载主题

  • 我们需要让站点加载新的主题，所以需要修改主题加载目录：
    • 搜索theme:字段，将后面的next 修改为 next-reloaded
1
2
- theme: next
+ theme: next-reloaded

主题配置文件

  • 主题配置文件_config.yml位于对应主题目录下。

    关键字

  • 主题配置文件首先添加博客的关键字，如果你旧版本有的话就直接拷贝过来：
1
2
# Set default keywords (Use a comma to separate)
keywords: "iOS, C, Object-C, Swift, Python"

站点创建时间

  • 站点创建时间，如果不指定，默认是当前时间，如2018，根据需要修改：
    • 如需修改，只需要移除since:前面的#号即可。
1
2
3
4
  footer:
# Specify the date when the site was setup.
# If not defined, current year will be used.
#since: 2015

站点菜单

  • 菜单及图标配置，可以从旧版本直接拷贝替换：
1
2
3
4
5
6
7
8
9
10
menu:
  home: / || home
  categories: /categories/ || th
  archives: /archives/ || archive
  about: /about/ || user
  tags: /tags/ || tags
  #schedule: /schedule/ || calendar
  #sitemap: /sitemap.xml || sitemap
  #commonweal: /404/ || heartbeat
  commonweal: /404.html || heartbeat #公益404

社交

  • 社交分享一样，可以直接拷贝原有的：
1
2
3
social:
  GitHub: https://github.com/SevenCho || github
  E-Mail: mailto:243166621@qq.com || envelope

分页

  • 关于文章分页，我是选择将自动分页关闭，采用手动分页的方式，手动分页的话可以更好的控制显示的摘要，v6.x 默认已经关闭，如果你想打开的话，如下：
    • 手动分页只需要在需要分页的地方添加<!-- more -->即可。
1
2
3
4
auto_excerpt:
-  enable: false
+  enable: true
   length: 150

文章 & 打赏 & 个人头像

  • 如果想修改文章创建、更新时间，搜索post_meta:字段，进行修改即可。
  • 修改打赏二维码，没什么说的，搜索# Reward，拷贝旧版本替换即可。
  • 个人中心的头像信息设置，搜索avatar:
    • 已经不需要自己自定义实现头像圆形样式文件和鼠标悬浮的旋转效果，默认已经集成，启用即可。
1
2
3
4
5
6
7
8
9
10
11
avatar:
  # 在博客的根目录 (source/images)的话: /images/avatar.gif
  # 在站点目录 (source/uploads)的话: /uploads/avatar.gif
  # 也可以直接使用图片链接
  url: /uploads/images/avatar.JPG
  # 设置是否裁剪成圆形
  rounded: true
  # 设置不透明度 0 ~ 1
  opacity: 1
  # 设置鼠标放上去的旋转效果
  rotated: true

代码块

  • 内置了代码块的一些配置，如边框，拷贝按钮等等，不需要我们自己再在样式文件中自定义了， 搜索codeblock:：
1
2
3
4
5
6
7
8
codeblock:
  # 代码块边框圆角半径，不设置默认是1
  border_radius:
  # 添加一个`拷贝`按钮，可以拷贝代码块内容，不需要我们自己去自定义了
  copy_button:
    enable: false
    # 是否显示结果
    show_result: false

版权

  • 设置站点版权信息，可以搜索post_copyright:字段，根据自己需要修改，如我的：
1
2
3
4
post_copyright:
  enable: true
  license: CC BY-NC-SA 3.0
  license_url: https://creativecommons.org/licenses/by-nc-sa/3.0/

用户小图标

  • 修改站点底部用户小图标，现在已经内置该功能，还可以设置动画，搜索icon:启动即可：
    • 图标以fontawesomem命名，更多图标在这里
    • 如果使用heart图标建议使用红色(#ff0000)。
    • 如下是我显示的心形图标及颜色和启用动画。
1
2
3
4
icon:
  name: heart # user
  animated: true
  color: "#ff0000"

配置站点文字

  • 自带的主题默认会根据设备查询是否安装了对应的常用字体：如苹果的苹方字体，微软的雅黑字体。
  • 我们可以自定义网站地址，参考官方文档，我们可以直接在主题配置文件中，搜索font:即可以修改全局字体，标题字体、文章字体、logo字体、代码块字体等等。
    • 如果我们设置的字体在用户设备上没有安装，会回退到主题的默认字体设置上。
    • 这里每种类别只可以设置一种自定义的字体。
  • 如果还需要精细控制每一处的字体，可以通过浏览器的调试功能，抓取到对应的标签在自定义样式文件中设置。

配置插件

  • 升级后大部分插件也有变动，如果你有用到下面的插件的话，可以参考。

文章统计

  • 旧版本是使用post_wordcount统计文章的字数，阅读时长等等，新版本该插件废弃，并且内置了symbols_count_time作为替换。
  • 参考这里进行安装及配置。

本地搜索

  • 本地搜索内置进主题，依赖启用hexo-generator-searchdb插件。
  • 参考这里进行安装及配置。

图片预览

  • 图片预览已经内置了新的预览配置， 只需要安装启动依赖插件theme-next-fancybox3即可。
  • 参考这里进行安装及配置。

顶部加载进度条

  • 站点的顶部加载进度条也已经内置，只需要安装启动依赖插件theme-next-pace即可。
  • 参考这里进行安装及配置。

配置文件

网站logo图标

  • 配置网站的logo图标，请在/Blog/themes/next-reloaded/source/images目录中替换如下图标：
    • favicon-32x32-next.png
    • favicon-16x16-next.png
    • logo.svg

文字关联标签图标

  • 文章的默认标签图标是一个#号，不是很喜欢，我们可以修改为自己喜欢的图标，如拟物的标签图标：
    • 打开 /Blog/themes/next-reloaded/layout/_macro/目录下的post.swig 文件。
    • 搜索 rel="tag"># , 将 # 换成 <i class="fa fa-tag"></i>。

自定义配置

  • 旧版本的一些自定义的配置文件，可以直接拷贝到新的主题对应位置下：
    • /Blog/themes/next-reloaded/source/css/_custom/目录下的custom.styl文件。
    • /Blog/themes/next-reloaded/source/css/_variables/目录下的custom.styl文件。
    • /Blog/themes/next-reloaded/layout/_custom/目录下的custom.swig文件。

引用样式修改

  • 如果需要修改blockquote引用样式：
    • 可以在/Blog/themes/next-reloaded/source/css/_common/scaffolding/目录下的base.styl文件直接修改。
    • 推荐在/Blog/themes/next-reloaded/source/css/_custom/目录下的custom.styl文件中自定义样式即可。

分割线样式

  • 修改文章分割线样式，参考/Blog/themes/next-reloaded/source/css/_common/components/post/目录下的post-eof.styl文件。

网站版权

  • 站点的版权配置文件，直接拷贝旧主题对应目录文件到对应目录即可：
    • /Blog/themes/next-reloaded/layout/_macro/目录下的my-copyright.swig文件。

文章版权

  • 直接拷贝旧主题对应目录文件到新的主题目录即可：
    • /Blog/themes/next-reloaded/source/css/_common/components/post/目录下my-post-copyright.styl文件。

高亮样式

  • 配置主题的一些高亮显示样式，可以配合自定义的样式文件一起使用：
    • /Blog/themes/next-reloaded/source/css/_common/components/highlight/目录下的highlight.styl文件。

头像边框及旋转 （旧版本）

  • 旧版本的头像样式及鼠标悬浮旋转在这里添加（新版本已经内置，可以不用管）
    • /Blog/themes/next-reloaded/source/css/_common/components/sidebar/目录下的sidebar-author.styl文件。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
.site-author-image {
  display: block;
  margin: 0 auto;
  padding: $site-author-image-padding;
  max-width: $site-author-image-width;
  height: $site-author-image-height;
  border: $site-author-image-border-width solid $site-author-image-border-color;

  // 修改头像边框
  border-radius: 50%;
  -webkit-border-radius: 50%;
  -moz-border-radius: 50%;

  // 设置旋转
  transition: 1.5s all;
}

// 可旋转的圆形头像,`hover`动作
.site-author-image:hover {
-webkit-transform: rotate(360deg);
-moz-transform: rotate(360deg);
-ms-transform: rotate(360deg);
-transform: rotate(360deg);
}

.site-author-name {
  margin: $site-author-name-margin;
  text-align: $site-author-name-align;
  color: $site-author-name-color;
  font-weight: $site-author-name-weight;
}

.site-description {
  margin-top: $site-description-margin-top;
  text-align: $site-description-align;
  font-size: $site-description-font-size;
  color: $site-description-color;
}

代码块拷贝按钮 （旧版本）

  • 旧版本代码块复制按钮在这里添加（新版本已经内置，只需启用即可，可以不用管）
    • /Blog/themes/next/source/js/src/目录下新建custom.js文件。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
//此函数用于创建复制按钮
function createCopyBtns() {
    var $codeArea = $("figure table");
    //查看页面是否具有代码区域，没有代码块则不创建 复制按钮
    if ($codeArea.length > 0) {
        //复制成功后将要干的事情
        function changeToSuccess(item) {
             $imgOK = $("#copyBtn").find("#imgSuccess");
                if ($imgOK.css("display") == "none") {
                    $imgOK.css({
                        opacity: 0,
                        display: "block"
                    });
                    $imgOK.animate({
                        opacity: 1
                    }, 1000);
                    setTimeout(function() {
                        $imgOK.animate({
                            opacity: 0
                        }, 2000);
                    }, 2000);
                    setTimeout(function() {
                        $imgOK.css("display", "none");
                    }, 4000);
                };
        };
        //创建 全局复制按钮，仅有一组。包含：复制按钮，复制成功响应按钮
        //值得注意的是：1.按钮默认隐藏，2.位置使用绝对位置 position: absolute; (position: fixed 也可以，需要修改代码)
        $(".post-body").before('<div id="copyBtn" style="opacity: 0; position: absolute;top:0px;display: none;line-height: 1; font-size:1.5em"><span id="imgCopy" ><i class="fa fa-paste fa-fw"></i></span><span id="imgSuccess" style="display: none;"><i class="fa fa-check-circle fa-fw" aria-hidden="true"></i></span>');
        //创建 复制 插件，绑定单机时间到 指定元素，支持JQuery
        var clipboard = new Clipboard('#copyBtn', {
            target: function() {
                //返回需要复制的元素内容
                return document.querySelector("[copyFlag]");
            },
            isSupported: function() {
                //支持复制内容
                return document.querySelector("[copyFlag]");
            }
        });
        //复制成功事件绑定
        clipboard.on('success',
            function(e) {
                //清除内容被选择状态
                e.clearSelection();
                changeToSuccess(e);
            });
        //复制失败绑定事件
        clipboard.on('error',
            function(e) {
                console.error('Action:', e.action);
                console.error('Trigger:', e.trigger);
            });
        //鼠标 在复制按钮上滑动和离开后渐变显示/隐藏效果
        $("#copyBtn").hover(
            function() {
                $(this).stop();
                $(this).css("opacity", 1);
            },
            function() {
                $(this).animate({
                    opacity: 0
                }, 2000);
            }
        );
    }
}
//感应鼠标是否在代码区
$("figure").hover(
    function() {
        //-------鼠标活动在代码块内
        //移除之前含有复制标志代码块的 copyFlag
        $("[copyFlag]").removeAttr("copyFlag");
        //在新的（当前鼠标所在代码区）代码块插入标志：copyFlag
        $(this).find(".code").attr("copyFlag", 1);
        //获取复制按钮
        $copyBtn = $("#copyBtn");
        if ($copyBtn.lenght != 0) {
            //获取到按钮的前提下进行一下操作
            //停止按钮动画效果
            //设置为 显示状态
            //修改 复制按钮 位置到 当前代码块开始部位
            //设置代码块 左侧位置
            $copyBtn.stop();
            $copyBtn.css("opacity", 0.8);
            $copyBtn.css("display", "block");
            $copyBtn.css("top", parseInt($copyBtn.css("top")) + $(this).offset().top - $copyBtn.offset().top + 3);
            $copyBtn.css("left", -$copyBtn.width() - 3);
        }
    },
    function() {
        //-------鼠标离开代码块
        //设置复制按钮可见度 2秒内到 0
        $("#copyBtn").animate({
            opacity: 0
        }, 2000);
    }
);
//页面载入完成后，创建复制按钮
$(document).ready(function() {
  createCopyBtns();
});

总结

  • 总体来说，整个更新升级的过程还是没有太多的坑的，我在第一次修改的时候，一口气把整个主题配置文件都修改完了，最后发现运行不起来，然后就是恢复后重新一处一处修改。如果不是很清楚功能，建议每修改一处就运行一次，稳步推进。
  • 如果是主题文件修改后无法运行，建议先在这里校验下文件有无语法错误，尤其是我们不太注意的空格有时就是罪魁祸首。
  • 我遇到直接清空本地的生成文件然后重新生成，在本地预览是完好的，但是部署到外网就网站格式全部没有了。最后我将原next主题目录更改名称为next-v5（名字随便，便于区分即可），然后将新版本next-reloaded主题目录名字修改为next，在博客根目录修改加载主题为next，然后没有问题了。如果有遇到同样问题的小伙伴可以这样尝试下。
要不要鼓励一下😘