Hexo常见问题解决方案

Hexo常见问题解决方案

介绍

Hexo是一个非常好用的静态博客生成器,但是由于很多方面的原因,导致在使用过程中经常出现错误。这些错误中,有些是因为自己的设置不当,导致程序报错;有些是因为版本更迭,导致原有的设置失效;而有些,则是Hexo程序本身的BUG。本文旨在尽可能的解决前两类问题,缓解Hexo项目大量重复issues的现象。当然,我个人的力量是有限的,因此也希望使用Hexo的大家也能一起行动起来,通过提交PR发布issues或者在下方评论区评论等形式参与到本文档的编辑中来。同时,也希望有能力的人可以将本文档翻译成英文,以帮助到更多的人。浏览时,使用Ctrl+F搜索关键词。

本文欢迎转载,但是恳请保留贡献者信息,谢谢。

 


常见错误

{ [Error: Cannot find module './build/Release/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }
{ [Error: Cannot find module './build/default/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }
{ [Error: Cannot find module './build/Debug/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }

Try to install with --no-optional option.

$ npm install hexo --no-optional

本地浏览没问题,Deploy报错

Git环境配置错误

问题描述:
Windows系统出现报错信息如下

1
2
3
4
5
6
7
8
9
10
11
12
13
[info] Start deploying: git
[info] Setting up Git deployment...
[error] Error: spawn ENOENT
Error: spawn ENOENT
    at errnoException (child_process.js:1000:11)
    at Process.ChildProcess._handle.onexit (child_process.js:791:34)

events.js:72
        throw er; // Unhandled 'error' event
              ^
Error: spawn ENOENT
    at errnoException (child_process.js:1000:11)
    at Process.ChildProcess._handle.onexit (child_process.js:791:34)

解决方案:

  1. 检查Git的相关配置,将git所在目录添加到系统path中去。
  2. 使用Github For Windows的朋友,将git添加至path之后,使用git shell.lnk启动Hexo。在lnk文件的属性界面中目标项中添加C:\Users\xuanw_000\AppData\Local\GitHub\GitHub.appref-ms --open-shell /k "C:\Program Files\nodejs\nodevars.bat"。其中C:\Users\xuanw_000\AppData\Local\GitHub\GitHub.appref-ms --open-shell /k是原来的文本,"C:\Program Files\nodejs\nodevars.bat"是新增的,用于在shell中添加nodejs运行环境。不会配置可以点击这里下载。

Deploy设置错误

问题描述:
输入hexo deploy后,出现错误信息:

1
'github' does not appear to be a git repository

解决方案:

  1. 检查_config.yml中deploy设置。参见http://hexo.io/docs/deployment.html
  2. 删除.deploy_git文件夹并且执行hexo clean后,重新hexo deploy

Deploy之后,页面长时间404

问题描述:
直接上图了,不要哭= =
Github 404 孩子不哭
解决方案:

检查Github Pages类型

个人主页
也就是库的名称为yourname.github.io的主页,页面文件应当在master分支下,文件结构可以参考我的主页,也就是应当以HTML文件为主,是没有Markdown文件的。
项目主页
也就是库名不是yourname.github.io的主页,页面文件应当在gh-pages分支下,文件结构与个人主页基本一致,同样没有Markdown文件。

检查Github验证邮件

曾经出现过所有操作都没有问题但就是404的状况,新创建的用户最好都去看看是不是验证邮件没有通过。

注意库的名字

现在大多改成.io结尾域名了,但是不确定是不是真的跟这个有关,最好改成.io

自有域名二级目录无法访问

问题描述
参见issue820

问题分析
问题出在CNAME跳转,下面附上我的分析,如果不感兴趣可以直接翻到解决方案。

如果没有CNAME跳转,访问yourname.github.io/repo会自动地去访问gh-pages分支下的静态文件。
但是一旦进行了CNAME跳转,访问yourname.github.io/repo就会自动跳转为yoursite.com/repo,显然在你的博客目录下是没有这个文件夹的,所以自然而然的会出现访问404错误。

解决方案
增加一个新的DNS记录
修改自己域名的DNS记录,增加一条记录(A记录或者CNAME都可以,指向github),内容是repo.yoursite.com,访问时通过repo.yoursite.com来访问。
将这个库移动到博客目录下
按照上述的分析,把这个库的repo移动至博客目录下即可。注意修改html以免被hexo再次渲染,还有如果是直接复制或者clone,注意删除隐藏的.git文件夹。

Hexo命令失效

问题描述:
输入命令后出现如下信息:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
localhost:~ apple$ hexo new "title"
Usage: hexo

Commands:
help Get help on a command
init Create a new Hexo folder
migrate Migrate your site from other system to Hexo
version Display version information

Global Options:
--debug Display all verbose messages in the terminal
--safe Disable all plugins and scripts

For more help, you can use hexo help [command] for the detailed information
or you can check the docs: http://zespia.tw/hexo/docs/

解决方案:

  1. 检查_config.yml中的内容,特别注意:后面需要有一个空格。
  2. 检查`package.json’中的内容,注意添加hexo信息用来标识这是一个hexo目录:
    1
    2
    3
    4
    5
    {
      "hexo": {
        "version": ""
      }
    }
  3. 如果还是有问题,可以更新hexo之后,在新的文件夹中重新进行hexo init

Hexo所有命令报错

问题描述:
参见Issues
报错信息如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[error] { name: 'HexoError',
  reason: 'end of the stream or a document separator is expected',
  mark: 
   { name: null,
     buffer: '# Hexo Configuration\n## Docs: http://hexo.io/docs/configuration.html\n## Source: https://github.com/tommy351/hexo/\n\n# Site\ntitle: 2hu\nsubtitle:\ndescription: 2hu\nauthor: @2hu10n92hen9\nemail:\nlanguage:\n\n# URL\n## If your site is put in a subdirectory, set url as \'http://yoursite.com/child\' and root as \'/child/\'\nurl: http://2hu.me\nroot: /\npermalink: :year/:month/:day/:title/\ntag_dir: tags\narchive_dir: archives\ncategory_dir: categories\ncode_dir: downloads/code\n\n# Directory\nsource_dir: source\npublic_dir: public\n\n# Writing\nnew_post_name: :year-:month-:day-:title.md # File name of new posts\ndefault_layout: post\nauto_spacing: false # Add spaces between asian characters and western characters\ntitlecase: false # Transform title into titlecase\nexternal_link: true # Open external links in new tab\nmax_open_file: 100\nmulti_thread: true\nfilename_case: 0\nrender_drafts: false\npost_asset_folder: false\nhighlight:\n  enable: true\n  line_number: true\n  tab_replace:\n\n# Category & Tag\ndefault_category: uncategorized\ncategory_map:\ntag_map:\n\n# Archives\n## 2: Enable pagination\n## 1: Disable pagination\n## 0: Fully Disable\narchive: 2\ncategory: 2\ntag: 2\n\n# Server\n## Hexo uses Connect as a server\n## You can customize the logger format as defined in\n## http://www.senchalabs.org/connect/logger.html\nport: 4000\nserver_ip: 0.0.0.0\nlogger: false\nlogger_format:\n\n# Date / Time format\n## Hexo uses Moment.js to parse and display date\n## You can customize the date format as defined in\n## http://momentjs.com/docs/#/displaying/format/\ndate_format: MMM D YYYY\ntime_format: H:mm:ss\n\n# Pagination\n## Set per_page to 0 to disable pagination\nper_page: 10\npagination_dir: page\n\n# Disqus\ndisqus_shortname: 2hu\n\n# Extensions\n## Plugins: https://github.com/tommy351/hexo/wiki/Plugins\n## Themes: https://github.com/tommy351/hexo/wiki/Themes\ntheme: strict\nexclude_generator:\n\n# Deployment\n## Docs: http://hexo.io/docs/deployment.html\ndeploy:\n  type: github\n  repository: https://github.com/zhulongzheng/zhulongzheng.github.io.git\n  branch: master\n\u0000',
     position: 168,
     line: 8,
     column: 8 },
  message: 'Config file load failed',
  domain: 
   { domain: null,
     _events: { error: [Function] },
     _maxListeners: 10,
     members: [ [Object] ] },
  domainThrown: true,
  stack: undefined }

解决方案:
仔细检查_config.yml文件中所有冒号后面的空格,格式很严格,必须是只有一个半角。不管是多了还是少了都会报错,这是yml解释器所定义的语法。如果不确定的话,将输入法调整到英文模式,删除所有冒号后面的空格重新输入,不要使用Tab。

更新至2.8.X版本后,构建失败

问题描述:
输入hexo g后,报错如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[error] { name: 'HexoError',
  reason: 'incomplete explicit mapping pair; a key node is missed',
  mark:
   { name: null,
     buffer: 'categories: Categories\nsearch: Search\ntags: Tags\ntagcloud: Tag Cloud\ntweets: Tweets\nprev: Prev\nnext:
 Next\ncomment: Comments\narchive_a: Archives\narchive_b: Archives: %s\npage: Page %d\nrecent_posts: Recent Posts\ndescr
iption: Description\nread_more: Read More\n\u0000',
     position: 163,
     line: 9,
     column: 19 },
  message: 'Process failed: languages/default.yml',
  domain:
   { domain: null,
     _events: { error: [Function] },
     _maxListeners: 10,
     members: [ [Object] ] },
  domainThrown: true,
  stack: undefined }

解决方案:
主题目录下所有yml文件中所有有空格的字段都用双引号括起来,尤其注意languages下面的yml文件。
就像这样
感谢@dukewan提供的截图

修改主题文件之后,网页不更新

问题描述:
在修改主题文件之后,页面的文件依然没有更新。
解决方案:
hexo clean并且删除.deploy文件夹之后,hexo d -g。为了强制浏览器更新资源文件,可以采用’Ctrl+F5’来刷新。

页面没有渲染(partial转义失败)

问题描述:
参见Issues
看不到渲染后的页面,只能看到类似如下信息:

1
2
3
4
5
6
<%- partial('_partial/head') %>
<%- partial('_partial/header', null, {cache: !config.relative_link}) %>
<%- body %>
<% if (theme.sidebar && theme.sidebar !== 'bottom'){ %> <%- partial('_partial/sidebar', null,     {cache: !config.relative_link}) %> <% } %>
<%- partial('_partial/footer', null, {cache: !config.relative_link}) %>
<%- partial('_partial/mobile-nav', null, {cache: !config.relative_link}) %> <%- partial('_partial/after-footer') %>

解决方案:
在博客所在目录下执行’npm install’用以安装插件。
感谢@tommy351提供的解决方案

更新至3.0.0版本后,文件渲染时卡死

问题描述:
参见Issues
表现为文件不多,但是渲染非常缓慢,超过半个小时。
问题分析:
问题出在’Highlight.js在判断语言类型时,会因为这个符号导致卡死。 **解决方案:** 在使用代码块时,明确使用类型,或者全部使用plain`类型,如下:

1
something

升级至Hexo 3.0版本后,deploy报错

问题描述:
参见Issues
升级之后,本来可以deploy的设置出现报错,内容为:

1
ERROR Deployer not found: github

问题分析:
Hexo3.0与以往版本最大的改变在于,更多的模块都从主程序中剥离了出来,其中就包括deploy的相关模块。
解决方案:
首先需要安装对应的deploy模块,目前Hexo支持以下服务器的一键部署:

1
2
3
4
git
heroku
rsync
openshift

安装命令为:

1
npm install hexo-deployer-git //将git替换为别的名字就可以安装对应模块

然后对_config.yml做如下设置:

1
2
3
4
5
deploy:
  type: git   //非git请参考官方文档中的设置
  repo: <repository url>
  branch: [branch]
  message: [message]

目前多Git部署存在BUG,等待修复中。


常见问题

如何在不同电脑(系统)上使用Hexo

将自己的Blog文件夹使用Git来管理,需要注意一下几点。

  1. 如果主题是通过git管理的,需要将主题文件夹下的.git文件夹删除,才能同步Blog文件夹(.git文件夹是隐藏的,需要显示隐藏文件才能删除,Linux下需要rm -rf命令才能删除,Mac没用过,不清楚)。
  2. 按照Blog目录下自带的.gitignore文件,node_modules文件夹是不会同步的,所以同步之后需要自己再次进行npm install,但是注意,不要进行hexo init了,否则_config.yml全都白弄了。

然后看一下同步之后的目录结构:
https://github.com/Xuanwo/xuanwo.github.io/tree/blog

在主目录下添加README.md文件或者html文件

Hexo3.0以下使用

感谢@TimNew提供的思路
额,不知道是不是有人跟我一样有一个库没有README.md文件就浑身不舒服的强迫症= =
正如大家所知道的,在source文件夹下的所有md文件都会被hexo渲染成html文件,导致README.md文件不能好好的放在里面了,即使是添加了layout: false依然没有用。

不过现在有一个另外的好办法,那就是利用主题的source目录,也就是themes/themes-name/source。因为这个文件夹里面的所有文件都会被复制到网站的根目录中去,也就是说,如果在里面放上README,就可以正常的存在于网站的主目录了。

同样的,对于一些需要在网站下添加html文件的需求也可以这样来达成。比如百度或者谷歌在验证站长权限的时候,通常都会要求在主目录下添加一个html文件。同样的,只要把这个文件放在themes/themes-name/source就可以搞定了。

Hexo3.0以上支持

使用_config.yml下的skip_render参数。
比如说现在source下有两个文件夹,一个是_post,一个是haha,里面各有一个名为hello-world.md的文档,然后我的skip_render参数为:
skip_render: haha/*.md
那么,hexo g之后的结果为:

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
INFO  Files loaded in 503 ms
INFO  Generated: js/script.js
INFO  Generated: fancybox/jquery.fancybox.pack.js
INFO  Generated: fancybox/jquery.fancybox.js
INFO  Generated: fancybox/jquery.fancybox.css
INFO  Generated: fancybox/helpers/jquery.fancybox-thumbs.js
INFO  Generated: fancybox/helpers/jquery.fancybox-thumbs.css
INFO  Generated: fancybox/helpers/jquery.fancybox-media.js
INFO  Generated: fancybox/helpers/jquery.fancybox-buttons.js
INFO  Generated: fancybox/helpers/jquery.fancybox-buttons.css
INFO  Generated: fancybox/helpers/fancybox_buttons.png
INFO  Generated: fancybox/fancybox_sprite@2x.png
INFO  Generated: fancybox/fancybox_sprite.png
INFO  Generated: fancybox/fancybox_overlay.png
INFO  Generated: fancybox/fancybox_loading@2x.gif
INFO  Generated: fancybox/fancybox_loading.gif
INFO  Generated: fancybox/blank.gif
INFO  Generated: css/style.css
INFO  Generated: css/images/banner.jpg
INFO  Generated: css/fonts/fontawesome-webfont.woff
INFO  Generated: css/fonts/fontawesome-webfont.ttf
INFO  Generated: css/fonts/fontawesome-webfont.svg
INFO  Generated: css/fonts/fontawesome-webfont.eot
INFO  Generated: css/fonts/FontAwesome.otf
INFO  Generated: haha/hello-world.md    //看这里!看这里!
INFO  Generated: 2015/03/26/hello-world/index.html
INFO  Generated: archives/index.html
INFO  Generated: archives/2015/index.html
INFO  Generated: archives/2015/03/index.html
INFO  Generated: index.html
INFO  29 files generatd in 1.28 s

也就是说,skip_render参数的使用需要注意两点:

  • 此处的位置是相对于你的source_dir的位置,一般来说,就是以source为根的位置
  • 这里的文件匹配是基于正则的,大致上可以参考这个),也就是说*.html可以忽略所有html文档,hello-wordl.md的话,就能忽略掉名字为hello-wordl.md的文件。

Hexo版本回退

有时候更新之后发现新版本的Hexo不能按照预期的方式工作,这时候就需要使用版本回退功能。
打开命令行,输入npm install -g hexo@版本号就可以回退到没有出现问题的版本上来。
这个命令适用于所有Node.js模块

少数情况下会出现Node.js版本问题,可以使用nvm install 版本号来安装报错信息中需要的版本。
推荐使用nvm来管理Node.js版本

如何为站点添加社会化评论

使用Disque

Hexo默认支持Disque,打开_config.yml,在disqus_shortname:后面输入自己的Disque账号。保存,重新渲染,清除缓存之后就能看到自己的评论窗口。

使用Duoshuo

部分主题添加了对多说的支持,只要输入Duoshuo账号,就可以看到效果了。如果主题不支持的话,就需要自己添加。需要对自己的主题结构有一定的了解,不是每一个主题都会有一样的文件,找不到同样的文件也正常,但是都会存在相同功能的区块,自己去定位即可。如果没把握的话,最后做好备份。

after_footer.ejs模块中输入如下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- 多说公共JS代码 start (一个网页只需插入一次) -->
<script type="text/javascript">
var duoshuoQuery = {short_name:"yourshortname"};
    (function() {
        var ds = document.createElement('script');
        ds.type = 'text/javascript';ds.async = true;
        ds.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//static.duoshuo.com/embed.js';
        ds.charset = 'UTF-8';
        (document.getElementsByTagName('head')[0] 
         || document.getElementsByTagName('body')[0]).appendChild(ds);
    })();
    </script>
<!-- 多说公共JS代码 end -->

article.ejs模块中输入如下代码:

1
2
3
<% if (page.comments){ %>
        <div class="ds-thread" data-thread-key="<%- page.path %>" data-title=<%- page.title %> data-url=<%- page.permalink %>>
<% } %>

如何避免在Deploy时输入密码

使用Github客户端

安装好Github客户端之后,使用Github客户端内置的Git Shell进行hexo的部署操作。

自行生成SSH key

使用Github客户端可以免去输入密码操作的原因就是客户端在本地生成了一个SSH key并且添加到了Github网站中。不喜欢使用Github客户端的童鞋可以参考下面的流程自行生成SSH key。
使用Github SSH Key以免去Hexo部署时输入密码

贡献者

更新日志

  • 2014年08月14日 完成大体框架,内容慢慢填充。
  • 2014年08月23日 补充404问题,以及如何在不同电脑(系统)上使用Hexo。
  • 2014年09月06日 新增自有域名二级目录无法访问,在主目录下添加md文件。
  • 2014年09月09日 新增Hexo版本回退,Hexo所有命令报错。
  • 2014年09月23日 新增Partial没有转义
  • 2014年09月24日 新增添加社会化评论
  • 2015年02月06日 新增本地添加SSH key,修复部分笔误
  • 2015年02月07日 SSH key生成独立成篇
  • 2015年04月01日 添加了部分Hexo3.0带来的问题,新增了skip_render参数设置。
  • 2015年04月03日 添加了Hexo3.0中deploy设置。

23 Responses so far.

  1. quest Bars says:
    I savor, result in I found just what I was having a look for.
    You have ended my four day lengthy hunt! God Bless you man. Have a nice day.

    Bye

  2. quest bars says:
    I am really delighted to glance at this webpage posts which contains plenty of helpful
    facts, thanks for providing such information.
  3. 何锦涛 says:
    你好:

    我在hexo s这一步打开我的博客 使用功能都没有问题 ,但是hexo g 和hexo d 以后 ,点击分类 主页 标签等按钮都会打不开页面,显示页面被重置。我是在mac上搭建的 ,不知道问题出在哪里,请指教

  4. shacai says:
    页面404
    博主你说 文件结构可以参考我的主页,也就是应当以HTML文件为主,是没有Markdown文件的
    可是我 hexo d部署之后 不是以html为主 这要怎么办 index.html在.develop_git下
    本地显示一切都正常 不知道为什么一直部署失败
    github一直给我发邮件
    The page build completed successfully, but returned the following warning:

    You are attempting to use a Jekyll theme, “yilia”, which is not supported by GitHub Pages. Please visit https://pages.github.com/themes/ for a list of supported themes. If you are using the “theme” configuration variable for something other than a Jekyll theme, we recommend you rename this variable throughout your site. For more information, see https://help.github.com/articles/adding-a-jekyll-theme-to-your-github-pages-site/.

    For information on troubleshooting Jekyll see:

    https://help.github.com/articles/troubleshooting-jekyll-builds

    If you have any questions you can contact us by replying to this email.
    我明明是 hexo主题 不知道为什么一直不支持

  5. 草原 says:
    你好,这是我要发布的.md文件:
    title: objective-C复合语句
    date: 2017-04-24
    tags: -start

    “`
    [self.view addSubView: ({
    ]()]() UIView *view = [\[UIView alloc]() initWithFrame:(CGRect){CGPointZero, 100.0f, 100.0f}];
    view.backgroundColor = [UIColor blueColor]();
    view.layer.maskToBounds = YES;
    view.layer.cornerRadius = 4.0f;
    view;
    })];
    “`

    我们经常看到类似于上面的代码,view的创建及属性设置都在”({})”里面完成,最后一句代码就是我们要添加的子view.这种写法沿用了GNU C的一个特性,即复合语句(compound statement)。在”({})”代码块中,我们可以放置多个语句,这些语句可以是循环、分支、变量声明、函数调用等。而复合语句的最后一句是一个表达式,其作为整个复合语句的最终值。
    复合语句能让我们的代码变得更优雅,特别是创建并添加一堆子View时。
    参考链接:http://southpeak.github.io/2016/08/31/ios-techset-7/

    ****************这是报的错,麻烦楼主帮我看看,提交不上去,老是说缺少分隔标记,不知道哪里缺空格**********************:ERROR Process failed: _posts/first.md
    YAMLException: end of the stream or a document separator is expected at line 5, column 1:
    “`
    ^

  6. 曾忠 says:
    你好,我在用hexo更新文章之后,所有的文章都只显示ip/posts/undefined/的这篇文章了,请问有解决方法吗?谢谢
  7. I like the valuable info you provide in your articles.
    I’ll bookmark your blog and check again here regularly.
    I am quite certain I’ll learn many new stuff right here!
    Good luck for the next!
  8. Hey would you mind sharing which blog platform you’re using?
    I’m going to start my own blog soon but I’m having a hard time
    making a decision between BlogEngine/Wordpress/B2evolution and Drupal.
    The reason I ask is because your design and style seems different
    then most blogs and I’m looking for something unique.
    P.S My apologies for being off-topic but I had to ask!
  9. What’s up, I log on to your blog like every week.
    Your humoristic style is awesome, keep up the good work!
  10. If some one desires to be updated with hottest technologies therefore he must be pay a visit this website and be up to date
    daily.
  11. Thanks for sharing your thoughts on i love cats t shirt roblox.
    Regards
  12. That is very attention-grabbing, You’re an overly professional blogger.

    I have joined your rss feed and look forward to searching for
    extra of your great post. Additionally, I have shared
    your site in my social networks

LEAVE A COMMENT