介绍

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

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

常见错误

本地浏览没问题，Deploy报错

Git环境配置错误

问题描述：

Windows系统出现报错信息如下


[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)

解决方案：

检查Git的相关配置，将git所在目录添加到系统path中去。

Deploy设置错误

问题描述：

输入hexo deploy后，出现错误信息：


'github' does not appear to be a git repository

解决方案：

检查_config.yml中deploy设置。参见http://hexo.io/docs/deployment.html。
删除.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命令失效

问题描述：

输入命令后出现如下信息：


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/

解决方案：

检查_config.yml中的内容，特别注意:后面需要有一个空格。
检查`package.json’中的内容，注意添加hexo信息用来标识这是一个hexo目录：


{
  "hexo": {
    "version": ""
  }
}

如果还是有问题，可以更新hexo之后，在新的文件夹中重新进行hexo init。

Hexo所有命令报错

问题描述：

参见Issues 报错信息如下：


[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后，报错如下：


[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_git文件夹之后，hexo d -g。为了强制浏览器更新资源文件，可以采用’Ctrl+F5’来刷新。

页面没有渲染（partial转义失败）

问题描述：

参见Issues 看不到渲染后的页面，只能看到类似如下信息：


<%- 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类型，如下：


plain
something

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

问题描述：

参见Issues 升级之后，本来可以deploy的设置出现报错，内容为：


ERROR Deployer not found: github

问题分析：

Hexo3.0与以往版本最大的改变在于，更多的模块都从主程序中剥离了出来，其中就包括deploy的相关模块。

解决方案：

首先需要安装对应的deploy模块，目前Hexo支持以下服务器的一键部署：


git
heroku
rsync
openshift

安装命令为：


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

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


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

Mac OS安装Hexo出错

问题描述：

参见Issues 命令行返回ERROR：


{ [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' }

解决方案：

使用命令npm install hexo --no-optional

常见问题

如何在不同电脑（系统）上使用Hexo

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

如果主题是通过git管理的，需要将主题文件夹下的.git文件夹删除或者使用git submodule的形式进行管理，才能同步Blog文件夹。
Blog目录下自带的.gitignore文件，node_modules文件夹是不会同步的，所以同步之后需要自己再次进行npm install，但是注意，不要进行hexo init了，否则_config.yml会被覆盖。

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

使用git submodule来管理主题

Todo

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

Hexo3.0以下使用

感谢@TimNew提供的思路

正如大家所知道的，在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参数。

skip_render使用了minimatch，开始匹配的位置是基于你的source_dir的，一般来说，是你的source文件夹下。下面我分别列举几种常见的情况进行说明：

请注意yml中的文件格式，输入单个数据请注意空格，输入数组请进行缩进

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


skip_render:
    - `test1/*.html`
    - `test2/**`

Hexo版本回退

有时候更新之后发现新版本的Hexo不能按照预期的方式工作，这时候就需要使用版本回退功能。打开命令行，输入npm install -g [email protected]版本号就可以回退到没有出现问题的版本上来。

这个命令适用于所有Node.js模块

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

推荐使用nvm来管理Node.js版本

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

使用Disque

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

使用Duoshuo

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

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


<!-- 多说公共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模块中输入如下代码：


<% 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部署时输入密码

多git部署

参考hexo-deployer-git插件README进行配置：


deploy:
  type: git
  message: [message]
  repo:
    github: <repository url>,[branch]
    gitcafe: <repository url>,[branch]

请注意每一个冒号后面的空格，如果丢失会导致yml文件读取错误。

开启全站https

Todo

贡献者

更新日志

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设置
2015年08月09日添加了多git部署，Mac OS安装出错，更新了skip_render参数设置以及部分文本说明
2015年09月05日添加了开启全站https以及主题管理，修复了代码显示BUG，删除了部分口水话

介绍

常见错误

本地浏览没问题，Deploy报错

Git环境配置错误

Deploy设置错误

Deploy之后，页面长时间404

检查Github Pages类型

检查Github验证邮件

注意库的名字

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

Hexo命令失效

Hexo所有命令报错

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

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

页面没有渲染（partial转义失败）

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

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

Mac OS安装Hexo出错

常见问题

如何在不同电脑（系统）上使用Hexo

使用git submodule来管理主题

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

Hexo3.0以下使用

Hexo3.0以上支持

Hexo版本回退

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

使用Disque

使用Duoshuo

如何避免在Deploy时输入密码

使用Github客户端

自行生成SSH key

多git部署

开启全站https

贡献者

更新日志

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