笑话人生

年华易逝 懂得珍惜

0%

Hexo 使用总结 & 常见问题

发表于 更新于 分类于 Disqus：
本文字数： 10k 阅读时长 ≈ 9 分钟

前言

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.com 和 ssh -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 执行策略不允许任何脚本运行。
AllSigned 和 RemoteSigned 执行策略可防止 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

分享精彩，留下足迹

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

Disqus 评论 LiveRe 评论