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 代表一个反引号。

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标签。