Hexo常出现的配置问题

发表于 |

在配置Hexo的时候常常会出现一些问题，比如hexo d无法部署，tags不自动生成，评论不正常显示等问题，本文给出了一些解决方案

Hexo

Hexo（Hail EXO，好吧这个我瞎编的）是基于nodejs的静态博客构建工具。由于Ruby的蜜汁信仰问题（而且windows下Ruby有点坑），我弃Jekyll投Hexo。
配置方法烂大街，这里不提了，可以去https://blog.lmintlcx.com/post/blog-with-hexo.html 这里看看。这次主要说一些可能遇到的问题。

常见错误

git问题

  1. 常见错误1

    1
    2
    event.js:72
        throw er;// Unhandled 'error' event

  2. 常见错误2

    1
    Error: fatal : Not a git repository (or any of the parent directories): .git

    解决方法：检查自己的.git文件夹是否在.deploy_git下，否则重新git init

  3. git push出现问题
    此类错误主要是

    1
    2
    3
    Failed to connect to github.com port 443: Timed out
    OpenSSL SSL_read: Connection was aborted, errno 10053
    Error: send-pack: unexpected disconnect while reading sideband packe

    解决方案考虑几点

    1
    2
    3
    4
    git config --global http.postBuffer 524288000
    git config --global http.sslVerify false
    // v2ray的sock5的端口+1是http端口
    git config --global http.proxy http://127.0.0.1:10802

    还需要git remote -v看一下是不是没有设置remote，没有的话得remote add下。

tags问题

         http://www.calvinneo.com/tags/ 不能正常显示tag

  1. 检查是否安装了必须的包
    可以使用npm ls --depth 0来查看依赖。

    1
    2
    3
    4
    npm install hexo-generate-index --save
    npm install hexo-generate-tags --save
    npm install hexo-generate-category --save
    npm install hexo-generate-archive --save

  2. 检查是否配置了tags页面
    检查/.deploy_git/tags下是否有index.html，这个是不会自动生成的，在命令行输入：

    1
    hexo new page tags

    该命令/source/tags/目录下新建了index.md。打开文件，键入或修改： 

    1
    type: "tags"

  3. npm故障
    可能会出现如下故障:
    TypeError: Cannot read property ‘latest’ of undefined hexo

    这可能是因为已经安装了以上npm包，所以不需要重复安装了。建议在hexo init后直接npm install即可。

生成的所有index.html为空

参看文章，如果NodeJS为14版本及以上，则需要降级为13版本及以下，或者升级hexo。后者我试了下，貌似没作用。

Something’s wrong 报错

下面的报错是因为某个代码块没有被注明语言。

1
2
3
4
5
FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/docs/troubleshooting.html
TypeError: Cannot set property 'lastIndex' of undefined
    at highlight (C:\DiskF\Codes\web\node_modules\highlight.js\lib\highlight.js:511:35)
    at C:\DiskF\Codes\web\node_modules\highlight.js\lib\highlight.js:561:21
    at Array.forEach (<anonymous>)

可以全局搜索 XXX\n.*XXX 来检查有问题的地方。其中 X 代表一个反引号。

如果确定没有，则可以 hexo clean 下。

NexT主题问题

使用多说

NexT主题使用多说插件有一些小注意点，比如说有些文章“喜欢”之后的分享转进来的链接是yoursite.com这个域下面的。打开duoshuo_shortname.duoshuo.com发现这些文章的地址也是yoursite.com。这个有三点原因：

  1. 检查site和theme的两个_config.yml中，是否url字段配置成自己的域名。
  2. 一旦同名文章添加进多说，其地址不会再次更改，因此要将多说中的文章先手动删除一下。
  3. 还有一种原因是文章的标题变动了，对于这种情况可以先hexo clean，再重新生成并部署。注意这时多说后台会生成一个新的文章，旧的文章并没有被替换。

设置网站的favicon

值得一提的是有一个方便的设置favicon的方法：

  1. 将所需图片如favicon.jpg复制到source下
  2. 在网站的_config.yml下输入
    1
    avatar: /favicon.jpg

sitemap网站地图

1
2
npm install hexo-generator-sitemap --save
npm install hexo-generator-baidu-sitemap --save

可能产生错误：

  1. duplicated mapping key at … path: baidusitemap.xml

    这是yaml的语法问题，比较简单的方法是直接去掉两个path中间的一个，每次只生成google或baidu的sitemap。当然你也可以把path缩进一下，这样就可以了。

Hexo s 命令不能在本地调试

首先检查是否安装了hexo-server。
其次不要在config里面显式用plugins指定插件。

vendors文件夹无法访问

vendors里面主要是脚本等东西，缺少之后网页无法显示。

f12看到整个vendors里面的东西都404了。

然后我在一个新建文件夹新建了文件*/test/1.txt*并deploy，发现以下错误：

既然确定了是github抽风了，就将网站搞一份到coding.net，可以使用下面配置：

1
2
3
4
5
deploy:
  type: git
  repository: 
    coding: git@git.coding.net:calvinneo/calvinneo.git,coding-pages
    github: https://github.com/CalvinNeo/calvinneo.github.io.git,master

这边特别注意，里面一定要用空格而不是tab缩进。
然后更新dns，之前因为github不稳定，我常常使用ss代理访问，但是代理的dns不一定立即更新，鉴于目前在国内网站coding.net重新部署了，可以直接访问www.calvinneo.com
2016年11月10日更新：部署到coding之后vendors又被禁了。

真是醉了，后来想起来蒲神给我看了这个issue，从github下了最新版本的next，这个问题解决了，FYI，我原来的版本是5.0.0。值得注意的是蒲神也是next，一次没坏过（无敌了）。
然后在配置新版本的_config.yml的时候发现现在next可以支持MathJax和busuanzi了，之前我还一直手动的。

管理git文件夹

hexo clean

hexo clean语句相当于重新init下git文件夹（这里应该是之前说错了，hexo init是这样的，但是clean只清空缓存，是安全的），所以所有的历史会全部消失，因此需要慎重。如果仅仅是为了清理，可以选择对.git进行rebase等操作

压缩图片

如果git中跟踪大体积的图片会导致git文件夹变得很大，而有的托管网站的容量实际上是有限制的，所以应当将图片压缩，软件Antelope是一个简洁易用的压缩图片工具

icon和avatar

icon和avatar是不一样的，icon是favicon.ico决定的，显示在浏览器标签页的最左边（chrome），avatar是在_config.yml里面指定的，显示在侧边栏。

给Hexo(NexT)加上搜索功能

swiftype是大家都推荐的工具，我用了之后各种资源加载不了，而且他还是一个收费的工具，于是我换成了Local Search
根据https://github.com/iissnan/hexo-theme-next/pull/694上的介绍可以添加配置，还是非常简单的
但是配置完成之后发现并没有弹出搜索窗口，显示的是javascript:;，然而根目录下的search.xml是存在的。后来f12发现是我在站点的配置文件中的swifttype_key字段没有注释掉，于是相当于现在还是使用的swifttype搜索，于是注释掉之后重新hexo g，再hexo s就出现搜索框了

MarkDown

MarkDown表格写法

1
2
3
4
5
6
7
8

<!-- 上面一定要空一行 -->
| 表头1 | 表头2 | 表头3|
<!-- 下面冒号表示对齐方式 -->
|:-|:-:|-:|
<!-- 下面开始内容 -->
|a|b|c|
|d|e|f|

效果是这样的:

表头1 表头2 表头3
aaaa bbb cc
d ee fff

Hexo中md文件转义的问题


这可能是某篇文章有字符未转义，出现解析错误

MarkDown存在的Bug

有些MD格式会出现Bug，例如在列表项里面的表格因为必须没有缩进，所以会破坏列表项的连续性，表格后的列表项会从1开始重新标号。
有的时候一段列表之后的新段会具有和列表项同样的缩进，即使中间插入了若干空行。

Error spawn git ENOENT问题

这个问题发生在我迁移整个hexo到另一台电脑上时。

MarkDown编译问题

很多时候hexo s造成的错误是markdown编译产生的，比如下面这个乱七八糟的错误，就是我在md里面写了一个用代码括号括起来的go数组造成的

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Template render error: (unknown path) [Line 305, Column 300]
  expected variable end
    at Object._prettifyError (F:\Codes\web\node_modules\nunjucks\src\lib.js:36:11)
    at Template.render (F:\Codes\web\node_modules\nunjucks\src\environment.js:524:21)
    at Environment.renderString (F:\Codes\web\node_modules\nunjucks\src\environment.js:362:17)
    at F:\Codes\web\node_modules\hexo\lib\extend\tag.js:66:9
    at Promise._execute (F:\Codes\web\node_modules\bluebird\js\release\debuggability.js:303:9)
    at Promise._resolveFromExecutor (F:\Codes\web\node_modules\bluebird\js\release\promise.js:483:18)
    at new Promise (F:\Codes\web\node_modules\bluebird\js\release\promise.js:79:10)
    at Tag.render (F:\Codes\web\node_modules\hexo\lib\extend\tag.js:64:10)
    at Object.tagFilter [as onRenderEnd] (F:\Codes\web\node_modules\hexo\lib\hexo\post.js:230:16)
    at F:\Codes\web\node_modules\hexo\lib\hexo\render.js:65:19
    at tryCatcher (F:\Codes\web\node_modules\bluebird\js\release\util.js:16:23)
    at Promise._settlePromiseFromHandler (F:\Codes\web\node_modules\bluebird\js\release\promise.js:512:31)
    at Promise._settlePromise (F:\Codes\web\node_modules\bluebird\js\release\promise.js:569:18)
    at Promise._settlePromise0 (F:\Codes\web\node_modules\bluebird\js\release\promise.js:614:10)
    at Promise._settlePromises (F:\Codes\web\node_modules\bluebird\js\release\promise.js:693:18)
    at Async._drainQueue (F:\Codes\web\node_modules\bluebird\js\release\async.js:133:16)
    at Async._drainQueues (F:\Codes\web\node_modules\bluebird\js\release\async.js:143:10)
    at Immediate.Async.drainQueues (F:\Codes\web\node_modules\bluebird\js\release\async.js:17:14)
    at processImmediate (internal/timers.js:439:21)

可以选择在 node_modules\hexo\lib\hexo\render.js 里面加个打印，看看是哪个文件的问题

1
2
3
4
5
6
...
  }).then(text => {
    console.log("Handling " + data.path)
    data.text = text;
    ext = data.engine || getExtname(data.path);
    if (!ext || !self.isRenderable(ext)) return text;

然后运行 hexo clean，再 hexo g 即可。

MathJax

使用MathJax

首先要将hexo的_config.yml和next的_config.yml都设置为true。
然后next的_config.yml是默认给出了一个cdn去加载，但是我希望能够从本地加载（家里断网了），并且希望能够在用到的时候（流量有限）再加载这个模块。

  1. 配置本地的MathJax
    根据这篇博文，解压下来居然有50M，真是吐血！
    后来听从博客，放到theme的source目录下面的js里面了。

  2. 配置可选的MathJax加载方式
    根据这篇博文和这篇博文，在/themes/next/layout/_scripts/third-party下面找到了mathjax.swig。swig表示这里是使用的swig模板语言（有的是使用的ejs模板语言）。
    然后改成这样

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    {% if theme.mathjax.enable && page.mathjax %}
      <script type="text/x-mathjax-config">
        MathJax.Hub.Config({
          tex2jax: {
            inlineMath: [ ['$','$'], ["\\(","\\)"]  ],
            processEscapes: true,
            skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
          }
        });
      </script>
      ...
    {% endif %}

注意swig模板语言不能在\{\% if \%\}块里面嵌入\{\% inlcude \%\}

hexo部署本地MathJax

node内存溢出


在配置的时候我一开始是把它放在/source/cdn/mathjax/目录下面的，我以为是这个原因，后来完全去掉这个模块还是不行，生成的db.json有150M炸了。
后来发现还真是因为那个文件＋太大了的原因，导致第一次出现了Template render error: (unknown path)错误，然后因为db.json生成太大了，下面再读取这个db.json的时候内存就直接爆炸了。而我移除模块之后，还要再clean一下，把那个超大的json去掉才行。
后来发现得放在theme/source/js里面。
然后最好还要设置一下hexo的_config.yml里面的skip_render，这个使用来跳过渲染的，否则hexo回自动帮你渲染页面。下面方法来自这里

单个文件夹下全部文件：skip_render: test/*
单个文件夹下指定类型文件：skip_render: test/*.html
单个文件夹下全部文件以及子目录: skip_render: test/**
多个文件夹以及各种复杂情况：

1
2
3
skip_render:
   - test1/*.html
   - test2/**

静态文件过多

在把MathJax放在theme/source/js里面以后在windows下hexo s发现：

1
Error: EMFILE, too many open files

出现以上的错误信息，目前还没有找到解决方法。

Hexo Mathjax转义

部分LaTeX符号需要进行转义输入

LaTeX Hexo+LaTeX
\ \\
\\ \\\\
_ \_
{, } \{, \}
* \*

Latex语法处理的问题

尽管可以通过转义，但很多时候，在涉及到下划线的时候，LaTeX可能仍然处理不正确。
此时，可以借助这一篇博客，进行操作。其实hexo-math可以不安装，即使装了，貌似也有问题。。。
主要是用hexo-renderer-kramed替换hexo-renderer-marked，但这样会导致已有的显示有问题。

我们可以用下面的几篇文章进行检查：

SEO

从这里看到可以在百度/谷歌“认领”自己的站点
注意在验证时需要将一个html文件放到网站根目录下面，但无论是填写skip_render还是

1
2
layout:false
---

都做不到这点，后来发现对于next主题，放到主题的source文件夹下面就可以了。
当然也可以走DNS验证，或者修改主题，在上面加上meta标签。