0%

Hexo 使用总结 & 常见问题


前言

Hexo 是一个非常简洁的静态博客框架,可以快速的搭建生成自己的博客,但是在使用中总会遇到各种各样奇怪的错误,在这里我整理一下我所遇到的错误和一些使用技巧等等,也欢迎各位读者对使用技巧和使用问题进行补充。如果有什么问题也可以随时在下方提问。

注意:

  1. _config.yml 文件在项目下有两个,一个在博客根目录下,一个在主题目录下。我在文中会用 站点配置文件主题配置文件 区分。
  2. 本博客使用的是 NexT 主题,某些设置可能与主题有关。

不渲染 md 或者 html

我们知道,在 source 文件夹下的所有 md 文件或者 html 文件都会被渲染,有时候我们不想这些文件被渲染怎么办?比如很多时候我们想要写一个 README.md 或者一些自定义的页面。比如百度或者谷歌在验证站长权限的时候,通常都会要求在主目录下添加一个 html 文件。

不渲染 html 文件

在不想被渲染的 html 文件最上面添加如下代码

1
2
3
---
layout: false
---

不渲染 md 文件

使用上面的办法虽然不会渲染 md 文件,但是还是将 md 文件转化成了 html 文件,如果想保留原 md 文件后缀要怎么做呢?这就需要在 站点配置文件 _config.yml 中配置,找到 skip_render 参数,开始匹配的位置是基于你的 source_dir 的,一般来说,是你的 source 文件夹下。下面我分别列举几种常见的情况进行说明:

  1. skip_render: test/* 单个文件夹下全部文件
  2. skip_render: test/*.md 单个文件夹下指定类型文件
  3. skip_render: test/** 单个文件夹下全部文件以及子目录
  4. 多个文件夹以及各种复杂情况:
    _config.yml
    1
    2
    3
    skip_render:
    - `test1/*.html`
    - `test2/**`

首页文章显示查看原文按钮

我们常常想在首页只显示文章的概述,而不是文章的全部,用一个 阅读全文 的字样代替,要怎么做呢?如下图:

在文章中只要写成如下格式即可:

1
2
3
4
5
这是摘要

<!-- more -->

这是全文

需要注意的是,点击 阅读全文 之后,文章会自动定位到 <!-- more --> 所在位置,想要修改成从头阅读需要修改 主题配置文件 _config.yml

_config.yml
1
2
# Automatically scroll page to section which is under <!-- more --> mark.
scroll_to_more: false // NexT v7版本已经不支持

配置 SSH 公钥免部署输入密码

_config.yml
1
2
3
4
5
6
7
8
9
10
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
type: git
repo:
github: git@github.com:cylong1016/cylong1016.github.io.git # Github SSH
# github: https://github.com/cylong1016/cylong1016.github.io.git # Github HTTPS
coding: git@git.coding.net:cylong1016/cylong1016.git # Coding SSH
# coding: https://git.coding.net/cylong1016/cylong1016.git # Coding HTTPS
branch: master

上面的代码是 站点配置文件 _config.yml 中的配置,分别是部署到 Github 和 Coding 上的两种方式,使用 HTTPS 方式的话每次部署都需要输入用户名和密码,很麻烦。

所以我选择使用 SSH 的方式,此方式是本机与远程仓库建立对接,这样部署的时候就不需要输入用户名和密码了。但是需要以下的配置:

  1. 打开终端或者 Git Bash,依次输入:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    mkdir ~/.ssh    # 如果之前没有这个文件夹就创建此文件夹
    cd ~/.ssh # 进入到 .ssh 文件夹中

    ssh-keygen -t rsa -C "youremail@example.com" # 生成密钥
    # 接着会提示输入 file 和 passphrase,直接回车就行。
    # 接着会看到下面的输出:
    Your identification has been saved in /home/cylong/.ssh/id_rsa.
    Your public key has been saved in /home/cylong/.ssh/id_rsa.pub.
    The key fingerprint is:
    fd:56:db:23:db:bf:df:54:0a:6a:43:51:13:34:22:b6 youremail@example.com

    # 接着输入
    ssh-add ~/.ssh/id_rsa
  2. 打开 https://github.com/settings/ssh(Github),点击 New SSH key,复制 id_rsa.pub 中的所有内容到 Key 框中,在 Title 框中输入方便自己记忆的名字(比如我的是 Personal Ubuntu)。https://coding.net/user/account/setting/keys(Coding)也一样,但是需要注意的是注册邮箱要一样,否则要两个 SSH。
  3. 输入 ssh -T git@github.comssh -T git@git.coding.net 测试是否配置成功。

参考:使用 Github SSH Key 以免去 Hexo 部署时输入密码 | Xuanwo’s Blog

使用 Fort Awesome 图标

我们知道,在我们写博客的时候,博客文件,或者自己自定义的页面,比如关于页面,都是 md 文件。最后会转化成 Html 文件。但是所支持的标签还是没有 Html 的全面,不过我们可以直接在 md 文件中写 Html 标签,比如:

1
<del>你什么都没有看见</del>

当然,你可以直接使用 Fort Awesome 图标,下面是我在 关于 页面写的代码:

1
2
<span class="fa fa-envelope"></span> 邮箱:chenyunlong1016@gmail.com
<span class="fab fa-weixin"></span> 微信:cylong1016

Ubuntu 下使用 Hexo

辗转反侧,还是忍不住使用 Ubuntu 系统。而且基本所有的人都和我说以后的开发都要使用 Linux 系统。所以最近准备使用 Ubuntu 练手,当然,博客也要在 Ubuntu 上更新了。由于我的博客已经在 Windows 系统下搭建好了,教程参考 Hexo + Git 搭建免费的个人博客 | 笑话人生 (虽然是 Windows 下的教程,但是其他平台步骤都是一样的)。Hexo 源码放在 GitHub | HexoBlog 上。所以直接 clone 下来就好。下面就说说我在 Ubuntu 系统下遇到的问题。

  1. 在执行 npm 命令时出现以下错误:

    1
    2
    3
    4
    sh: 1: node: not found
    npm WARN This failure might be due to the use of legacy binary "node"
    npm WARN For further explanations, please read
    /usr/share/doc/nodejs/README.Debian

    解决办法,执行以下命令:

    1
    sudo apt-get install nodejs-legacy

    详情请参考:

    Cannot install packages using node package manager in Ubuntu | Stack Overflow
    What are the differences between node.js and node | Stack Overflow
    Cannot install hexo in Ubuntu 14.04 #580 | hexojs/hexo

  2. 执行 hexo 命令时出现以下错误:

    1
    FATAL Cannot find module '/home/cylong/Github/HexoBlog/node_modules/hexo-deployer-git'

    原因是没有 hexo-deployer-git module。执行以下命令安装:

    1
    npm install hexo-deployer-git
  3. 可以正常执行 hexo 命令,但是会出现下面的警告:

    1
    2
    3
    4
    Native thread-sleep not available.
    This will result in much slower performance, but it will still work.
    You should re-install spawn-sync or upgrade to the lastest version of node if possible.
    Check /usr/local/lib/node_modules/hexo-cli/node_modules/hexo-util/node_modules/cross-spawn/node_modules/spawn-sync/error.log for more details

    解决办法如上警告所说,升级 node.js。

    1
    2
    3
    sudo npm cache clean -f
    sudo npm install -g n
    sudo n stable

    详情请参考:How do I update Node.js | Stack Overflow

  4. 执行 hexo g 无法部署到 Github 上,出现如下错误:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    Permission denied (publickey).
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights
    and the repository exists.
    FATAL Something's wrong. Maybe you can find the solution here: https://hexo.io/docs/troubleshooting.html
    Error: Permission denied (publickey).
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights
    and the repository exists.

    解决办法,请参考:配置 SSH 公钥免去部署的时候输入密码

NexT 添加版权声明

  1. 修改 主题配置文件 _config.yml,开启版权声明:
    _config.yml
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # Creative Commons 4.0 International License.
    # See: https://creativecommons.org/share-your-work/licensing-types-examples
    # Available values of license: by | by-nc | by-nc-nd | by-nc-sa | by-nd | by-sa | zero
    # You can set a language value if you prefer a translated version of CC license, e.g. deed.zh
    # CC licenses are available in 39 languages, you can find the specific and correct abbreviation you need on https://creativecommons.org
    creative_commons:
    license: by-nc-sa
    sidebar: true
    post: true
    language:
  2. 默认的配置只有 本文作者本文链接版权声明 三个字段,于是我又新增了 本文标题 字段,首先修改 NexT 主题下的 \layout\_partials\post\post-copyright.swig 文件,添加 本文标题 字段,并将作者信息增加跳转链接:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    {%- set ccIcon = '<i class="fab fa-fw fa-creative-commons"></i>' %}
    {%- set ccText = theme.creative_commons.license | upper %}

    <div>
    <ul class="post-copyright">
    <li class="post-copyright-title">
    <strong>{{ __('post.copyright.title') + __('symbol.colon') }}</strong>
    {{ next_url(page.permalink, page.title, {title: page.title}) }}
    </li>
    <li class="post-copyright-author">
    <strong>{{ __('post.copyright.author') + __('symbol.colon') }} </strong>
    {{ next_url("/about/", page.author or author, {title: page.author or author}) }}
    </li>
    <li class="post-copyright-link">
    <strong>{{ __('post.copyright.link') + __('symbol.colon') }}</strong>
    {{ next_url(page.permalink, page.permalink, {title: page.title}) }}
    </li>
    <li class="post-copyright-license">
    <strong>{{ __('post.copyright.license_title') + __('symbol.colon') }} </strong>
    {{- __('post.copyright.license_content', next_url(ccURL, ccIcon + ccText)) }}
    </li>
    </ul>
    </div>
  3. 再修改 \languages\zh-CN.yml 中的版权声明文案配置:
    1
    2
    3
    4
    5
    6
    copyright:
    title: 本文标题
    author: 本文作者
    link: 本文链接
    license_title: 版权声明
    license_content: "本博客所有文章除特别声明外,均采用 %s 许可协议。转载请注明出处 <span class=\"far fa-laugh-beam\"></span>"
  4. 效果如下:
  5. BY-NC-SA 参考:CC BY-NC-SA 4.0 DEED | 署名-非商业性使用-相同方式共享 4.0 国际
  6. 参考:版权信息 | Hexo-NexT

NexT 添加字数统计和阅读时长

  1. 安装 npm 包
1
npm install hexo-symbols-count-time
  1. 修改 站点配置文件 _config.yml
1
2
3
4
5
6
7
8
9
symbols_count_time:
symbols: true # 文章字数统计
time: true # 文章阅读时长
total_symbols: true # 站点总字数统计
total_time: true # 站点总阅读时长
exclude_codeblock: false # 排除代码字数统计
awl: 4 # 平均字长(字中的字符数)
wpm: 275 # 每分钟阅读字数
suffix: "mins."
  1. 修改 NexT 主题的 _config.yml 文件(Next 主题已经支持此插件,仅个性化修改即可)
1
2
3
4
5
6
# Post wordcount display settings
# Dependencies: https://github.com/theme-next/hexo-symbols-count-time
symbols_count_time:
separated_meta: true
item_text_post: true
item_text_total: false
  1. 参考:

    theme-next/hexo-symbols-count-time
    Hexo 博客 NexT 主题下添加字数统计和阅读时长 | CSDN 博客

添加 RSS 订阅

  1. 安装 Feed 插件

    1
    npm install hexo-generator-feed --save
  2. 站点配置文件 _config.yml 中添加如下代码:

    _config.yml
    1
    2
    3
    4
    5
    feed:
    type: atom
    path: atom.xml
    limit: 20
    hub:
  • type - 订阅类型 (atom 或 rss2)
  • path - 路径 (默认: atom.xml 或 rss2.xml)
  • limit - 最多显示文章数量 (0 或 false 展示所有文章)
  • hub - PubSubHubbub hubs 的 URL (PubSubHubbub 是一个“开放的、服务器对服务器、基于Web-hook的发布/订阅协议,是 Atom 和 RSS 的扩展”。不使用就留空)

添加打赏功能

NexT 主题支持打赏功能,简单配置即可

  1. 获取支付宝和微信的收款二维码,放在 source/images 目录下
  2. 修改 NexT 主题的 _config.yml 文件
    _config.yml
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    # Reward (Donate)
    # Front-matter variable (unsupport animation).
    reward_settings:
    # If true, reward will be displayed in every article by default.
    enable: true
    animation: false
    comment: <span class="fa fa-donate"></span> 分享精彩,留下足迹

    reward:
    alipay: /images/alipay.jpg
    wechatpay: /images/wechatpay.jpg
    #paypal: /images/paypal.png
    #bitcoin: /images/bitcoin.png
  3. 重新部署后在文章最下面就会有打赏按钮,赞赏是一种美德,有余力而为之,期待为优质内容付费

添加网站底部字数统计

  1. 安装 hexo-wordcount 插件

    1
    npm install hexo-wordcount --save
  2. /themes/next/layout/_partials/footer.swig 中最后加上:

    1
    2
    3
    4
    <div class="theme-info">
    <div class="powered-by"></div>
    <span class="post-count">博客共{{ totalcount(site) }}字</span>
    </div>
  3. 参考:hexo-wordcount

部署到 Github 后修改未更新

有时候当你 hexo d --g 部署到 Github 的时候,发现有些地方并没有更新,比如你的主题样式。这时候就建议你输入 hexo clean 清除下 public 文件夹下的文件,然后再部署(部署的时候实际上是直接拷贝 public 下的文件的)。另外多说一句,hexo d --g 是以下两个命令的缩写:

1
2
3
hexo g  # 生成本地 public 静态文件
hexo d # 部署到 Github 上
# 也可以缩写成:hexo g --d

LF will be replaced

Windows 提交命令的时候出现 warning: LF will be replaced by CRLF in xxx 的警告。输入以下命令即可:

1
git config --global core.autocrlf false

Windows 禁止运行脚本

Windows PowerShell 执行命令的时候出现如下错误:

1
2
3
4
5
6
7
PS D:\Github\HexoBlog> hexo v
hexo : 无法加载文件 C:\Users\win\AppData\Roaming\npm\hexo.ps1,因为在此系统上禁止运行脚本。有关详细信息,请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
所在位置 行:1 字符: 1
+ hexo v
+ ~~~~
+ CategoryInfo : SecurityError: (:) [],PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess

启动 Windows PowerShell 时,执行策略很可能是 Restricted(默认设置)。

Restricted 执行策略不允许任何脚本运行。
AllSignedRemoteSigned 执行策略可防止 Windows PowerShell 运行没有数字签名的脚本。

查看当前执行策略,打开 PowerShell 输入以下命令:

1
2
PS D:\Github\HexoBlog> get-executionpolicy
Restricted

以管理员身份打开 Windows PowerShell 输入以下命令并输入 Y 即可解决:

1
2
3
4
5
6
7
PS C:\WINDOWS\system32> set-executionpolicy remotesigned
执行策略更改
执行策略可帮助你防止执行不信任的脚本。更改执行策略可能会产生安全风险,如 https:/go.microsoft.com/fwlink/?LinkID=135170
中的 about_Execution_Policies 帮助主题所述。是否要更改执行策略?
[Y] 是(Y) [A] 全是(A) [N] 否(N) [L] 全否(L) [S] 暂停(S) [?] 帮助 (默认值为“N”): Y
PS C:\WINDOWS\system32> get-executionpolicy
RemoteSigned

参考:PowerShell:因为在此系统上禁止运行脚本,解决方法 | syxdevcode 博客

更新 tag 大小写后访问 404

强迫症的我想修改标签大小写,结果修改完成后发现访问标签链接报 404 错误,查阅资料发现其实是由于 Windows 平台上的 Git,默认设置了大小写不敏感导致的。修改博客根目录的 .deploy_git/.git/config 文件即可解决:

1
ignorecase = false

参考:

Hexo 改变 tag 因为大小写问题而 404 的解决方法 | 张洪Heo
Hexo 更新 tag 的大小写后标签页出现错误 | Yika`s Blog
BUG 反馈:大写开头的标签出现 404 #818 | hexojs/hexo

感谢

Hexo 常见问题解决方案 | Xuanwo’s Blog
Hexo 搭建个人博客系列:进阶设置篇 | 个人日记
生生之境 提出的各种【高智商 (●’◡’●)】问题

参考资料

Hexo + Git 搭建免费的个人博客 | 笑话人生
Hexo 中文文档(包含:文档、API、插件、主题)
NexT 使用文档(包含:开始使用、主题配置、第三方服务、内建标签、常见问题)
Feed generator for Hexo
hexo-wordcount


分享精彩,留下足迹

欢迎关注我的其它发布渠道