问题解答

在使用 Hexo 时,您可能会遇到一些问题,下列的常见问题解答可能会对您有所帮助。如果您在这里找不到解答,可以在 GitHubGoogle Group 上提问。

YAML 解析错误

JS-YAML: incomplete explicit mapping pair; a key node is missed at line 18, column 29:
last_updated: Last updated: %s

如果 YAML 字符串中包含冒号(:)的话,请加上引号。

JS-YAML: bad indentation of a mapping entry at line 18, column 31:
last_updated:"Last updated: %s"

请确认您使用空格进行缩进(Soft tab),并确认冒号后有加上一个空格。

您可参阅 YAML 规范 以取得更多信息。

EMFILE 错误

Error: EMFILE, too many open files

虽然 Node.js 有非阻塞 I/O,同步 I/O 的数量仍被系统所限制,在生成大量静态文件的时候,您可能会碰到 EMFILE 错误,您可以尝试提高同步 I/O 的限制数量来解决此问题。

$ ulimit -n 10000

(这一命令只对Linux系统有效)

Error: cannot modify limit

If you encounter the following error:

$ ulimit -n 10000
ulimit: open files: cannot modify limit: Operation not permitted

It means some system-wide configurations are preventing ulimit to being increased to a certain limit.

To override the limit:

  1. Add the following line to “/etc/security/limits.conf”:

    * - nofile 10000

    # '*' applies to all users and '-' set both soft and hard limits
    • The above setting may not apply in some cases, ensure “/etc/pam.d/login” and “/etc/pam.d/lightdm” have the following line. (Ignore this step if those files do not exist)
    session required pam_limits.so
  2. If you are on a systemd-based distribution, systemd may override “limits.conf”. To set the limit in systemd, add the following line in “/etc/systemd/system.conf” and “/etc/systemd/user.conf”:

    DefaultLimitNOFILE=10000
  3. Reboot

Git 部署问题

RPC failed

error: RPC failed; result=22, HTTP code = 403

fatal: 'username.github.io' does not appear to be a git repository

请确认您已经在电脑上 配置 git,或改用 HTTPS 库(repository)地址。

Error: ENOENT: no such file or directory

如果你遇到了这个错误,有可能是你的文件名、分类或者标签的名字混淆了大写和小写,你可以尝试检查每一个标签和分类的名称,是否大小写一致来修复这一问题。

服务器问题

Error: listen EADDRINUSE

您可能同时开启两个 Hexo 服务器,或者有其他应用程序正在占用相同的端口,请尝试修改 port 参数,或是在启动 Hexo 服务器时加上 -p 选项。

$ hexo server -p 5000

插件安装问题

npm ERR! node-waf configure build

当您尝试安装以 C/C++ 或其他非 JavaScript 语言所编写的插件时,可能会遇到此类问题,请确认您已经在电脑上安装相对应的编译器。

DTrace 错误 (Mac OS X)

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

DTrace 安装可能有错误 , 使用下列命令:

$ npm install hexo --no-optional

参考 #1326

在 Jade 或 Swig 遍历资料

Hexo 使用 Warehouse 存储资料,它不是一般数组所以必须先进行类型转型才能遍历。

{% for post in site.posts.toArray() %}
{% endfor %}

资料没有更新

有时资料可能没有被更新,或是生成的文件与修改前的相同,您可以尝试清除缓存并再执行一次。

$ hexo clean

命令没有执行

如果你除了 hexo helphexo inithexo version 以外不能执行任何命令、并且你的任何命令都只返回了 hexo help 的内容,这可能是由于 package.json 中缺乏 hexo 字段导致的。

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

泄露(Escape)内容

Hexo 使用 Nunjucks 来解析文章(旧版本使用 Swig,两者语法类似),内容若包含 {{ }}{% %} 可能导致解析错误,您可以用 raw 标签包裹,single backtick `{{ }}` 或 triple backtick 来避免潜在问题发生。
Alternatively, Nunjucks tags can be disabled through the renderer’s option (if supported), API or front-matter.

{% raw %}
Hello {{ world }}
{% endraw %}
```
Hello {{ world }}
```

ENOSPC 错误 (Linux)

运行 $ hexo server 命令有时会返回这样的错误:

Error: watch ENOSPC ...

它可以用过运行 $ npm dedupe 来解决,如果不起作用的话,可以尝试在 Linux 终端中运行下列命令:

$ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

这将会提高你能监视的文件数量。

EMPERM Error (Windows Subsystem for Linux)

在执行 hexo server 后返回如下错误:

Error: watch /path/to/hexo/theme/ EMPERM	

这是由于你使用的 WSL 版本不支持监听文件系统改动。 最新版的 WSL 已经解决了这一问题。

您也仍然可以通过先使用 hexo g 生成文件然后将其作为静态服务器运行来从 WSL 环境运行服务器:

$ hexo generate
$ hexo server -s

关于 WSL 的这一 Issue 请前往 https://github.com/Microsoft/BashOnWindows/issues/216 查看。目前这一问题已经得到了解决。

模板渲染错误

有的时候你在执行 hexo generate 时会返回以下错误信息:

FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/docs/troubleshooting.html
Template render error: (unknown path)

这表明你的文件中存在一些不可被识别的字符,比如不可见的零宽度字符。有可能你的新文章存在这个问题,或者你在修改配置文件时导致了这个错误。

检查你的 _config.yml 文件中是否漏掉了列表前的空格。你可以查阅 Wikipedia 中 YAML 相关页面来学习 YAML 语法。

这个是错误的:

plugins:
- hexo-generator-feed
- hexo-generator-sitemap

正确的应该是这样:

plugins:
- hexo-generator-feed
- hexo-generator-sitemap