故障排除

如果你在使用 Hexo 时遇到问题，以下是一些常见问题的解决方案列表。如果此页面无法帮助你解决问题，请尝试搜索 GitHub 或我们的 Google 群组。

¥In case you’re experiencing problems with using Hexo, here is a list of solutions to some frequently encountered issues. If this page doesn’t help you solve your problem, try doing a search on GitHub or our Google Group.

YAML 解析错误

¥YAML Parsing Error

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

如果字符串包含冒号，则用引号将其括起来。

¥Wrap the string with quotations if it contains colons.

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

确保你使用的是软制表符并在冒号后添加一个空格。

¥Make sure you are using soft tabs and add a space after colons.

你可以查看 YAML 规范 了解更多信息。

¥You can see YAML Spec for more info.

EMFILE 错误

¥EMFILE Error

Error: EMFILE, too many open files

虽然 Node.js 具有非阻塞 I/O，但同步 I/O 的最大数量仍受系统限制。尝试生成大量文件时，你可能会遇到 EMFILE 错误。你可以尝试运行以下命令来增加允许的同步 I/O 操作数。

¥Though Node.js has non-blocking I/O, the maximum number of synchronous I/O is still limited by the system. You may come across an EMFILE error when trying to generate a large number of files. You can try to run the following command to increase the number of allowed synchronous I/O operations.

$ ulimit -n 10000

错误：无法修改限制

¥Error: cannot modify limit

如果你遇到以下错误：

¥If you encounter the following error:

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

这意味着一些系统范围的配置阻止 ulimit 增加到一定限制。

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

覆盖限制：

¥To override the limit:

1. 将以下行添加到 “/etc/security/limits.conf”：

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

* - nofile 10000

# '*' applies to all users and '-' set both soft and hard limits

• 在某些情况下，上述设置可能不适用，请确保 “/etc/pam.d/login” 和 “/etc/pam.d/lightdm” 有以下行。（如果这些文件不存在，请忽略此步骤）

  ¥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. 如果你使用的是 systemd-based 发行版，systemd 可能会覆盖 “limits.conf”。要在 systemd 中设置限制，请在 “/etc/systemd/system.conf” 和 “/etc/systemd/user.conf” 中添加以下行：

   ¥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

进程内存不足

¥Process Out of Memory

当你在生成过程中遇到此错误时：

¥When you encounter this error during generation:

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - process out of memory

通过更改 hexo-cli 的第一行（which hexo 查找文件）来增加 Node.js 堆内存大小。

¥Increase Node.js heap memory size by changing the first line of hexo-cli (which hexo to look for the file).

#!/usr/bin/env node --max_old_space_size=8192

生成大型博客时内存不足 · 问题 #1735 · hexojs/hexo

¥Out of memory while generating a huge blog · Issue #1735 · hexojs/hexo

Git 部署问题

¥Git Deployment Problems

RPC 失败

¥RPC failed

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

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

确保你的计算机上正确安装了 设置 git，或者尝试改用 HTTPS 存储库 URL。

¥Make sure you have set up git on your computer properly or try to use HTTPS repository URL instead.

错误：ENOENT:没有这样的文件或目录

¥Error: ENOENT: no such file or directory

如果你收到类似 Error: ENOENT: no such file or directory 的错误，则可能是由于你的标签、类别或文件名中混合了大小写字母。Git 无法自动合并此更改，因此它会破坏自动分支。

¥If you get an error like Error: ENOENT: no such file or directory it’s probably due to mixing uppercase and lowercase letters in your tags, categories, or filenames. Git cannot automatically merge this change, so it breaks the automatic branching.

修复此问题，请尝试

¥To fix this, try

1. 检查每个标签和类别的大小写，并确保它们相同。

   ¥Check every tag’s and category’s case and make sure they are the same.

2. 提交

   ¥Commit

3. 清理并构建：./node_modules/.bin/hexo clean && ./node_modules/.bin/hexo generate

   ¥Clean and build: ./node_modules/.bin/hexo clean && ./node_modules/.bin/hexo generate

4. 手动将公共文件夹复制到你的桌面

   ¥Manually copy the public folder to your desktop

5. 在本地将分支从主分支切换到部署分支

   ¥Switch branch from your master branch to your deployment branch locally

6. 将桌面上的公共文件夹的内容复制到部署分支

   ¥Copy the contents of the public folder from your desktop into the deployment branch

7. 提交。你应该看到出现任何可以手动解决的合并冲突。

   ¥Commit. You should see any merge conflicts appear that you can manually resolve.

8. 切换回主分支并正常部署：./node_modules/.bin/hexo deploy

   ¥Switch back to your master branch and deploy normally: ./node_modules/.bin/hexo deploy

服务器问题

¥Server Problems

Error: listen EADDRINUSE

你可能同时启动了两个 Hexo 服务器，或者可能有另一个应用使用相同的端口。尝试修改 port 设置或使用 -p 标志启动 Hexo 服务器。

¥You may have started two Hexo servers at the same time or there might be another application using the same port. Try to modify the port setting or start the Hexo server with the -p flag.

$ hexo server -p 5000

插件安装问题

¥Plugin Installation Problems

npm ERR! node-waf configure build

尝试安装用 C、C++ 或其他非 JavaScript 语言编写的插件时可能会发生此错误。确保你的计算机上安装了正确的编译器。

¥This error may occur when trying to install a plugin written in C, C++ or other non-JavaScript languages. Make sure you have installed the right compiler on your computer.

DTrace 错误（Mac OS X）

¥Error with 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 安装可能有问题，请使用以下命令：

¥DTrace install may have issue, use this:

$ npm install hexo --no-optional

参见 #1326

¥See #1326

在 Jade 或 Swig 上迭代数据模型

¥Iterate Data Model on Jade or Swig

Hexo 使用 [仓库][Warehouse] 作为其数据模型。它不是数组，因此你可能必须将对象转换为可迭代对象。

¥Hexo uses [Warehouse] for its data model. It’s not an array so you may have to transform objects into iterables.

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

数据未更新

¥Data Not Updated

某些数据无法更新，或者新生成的文件与上一版本的文件相同。清除缓存并重试。

¥Some data cannot be updated, or the newly generated files are identical to those of the last version. Clean the cache and try again.

$ hexo clean

未执行任何命令

¥No command is executed

当你无法使用除 help、init 和 version 之外的任何命令，并且不断获取 hexo help 的内容时，这可能是由于 package.json 中缺少 hexo 造成的：

¥When you can’t get any command except help, init and version to work and you keep getting content of hexo help, it could be caused by a missing hexo in package.json:

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

转义内容

¥Escape Contents

Hexo 使用 [Nunjucks][Nunjucks] 渲染帖子（旧版本中使用 [Swig][Swig]，其语法相似）。用 {{ }} 或 {% %} 封装的内容将被解析并可能导致问题。你可以通过使用 raw 标签插件、单个反引号 {{ }} 或三个反引号封装它来跳过解析。或者，可以通过渲染器的选项（如果支持）API 手册 或 front-matter 禁用 Nunjucks 标签。

¥Hexo uses [Nunjucks] to render posts ([Swig] was used in the older version, which shares a similar syntax). Content wrapped with {{ }} or {% %} will get parsed and may cause problems. You can skip the parsing by wrapping it with the raw tag plugin, a single backtick `{{ }}` or a 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）

¥ENOSPC Error (Linux)

有时运行命令 $ hexo server 时会返回错误：

¥Sometimes when running the command $ hexo server it returns an error:

Error: watch ENOSPC ...

可以通过运行 $ npm dedupe 来修复，如果这没有帮助，请在 Linux 控制台中尝试以下内容：

¥It can be fixed by running $ npm dedupe or, if that doesn’t help, try the following in the Linux console:

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

这将增加你可以监视的文件数量的限制。

¥This will increase the limit for the number of files you can watch.

EMPERM 错误（适用于 Linux 的 Windows 子系统）

¥EMPERM Error (Windows Subsystem for Linux)

在 BashOnWindows 环境中运行 $ hexo server 时，它会返回以下错误：

¥When running $ hexo server in a BashOnWindows environment, it returns the following error:

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

不幸的是，WSL 目前不支持文件系统监视程序。因此，hexo 服务器的实时更新功能目前不可用。你仍然可以从 WSL 环境运行服务器，方法是先生成文件，然后将其作为静态服务器运行：

¥Unfortunately, WSL does not currently support filesystem watchers. Therefore, the live updating feature of hexo’s server is currently unavailable. You can still run the server from a WSL environment by first generating the files and then running it as a static server:

$ hexo generate
$ hexo server -s

这是 已知的 BashOnWindows 问题，2016 年 8 月 15 日，Windows 团队表示他们将对其进行研究。你可以获取进度更新并鼓励他们在 问题的 UserVoice 建议页面 上优先考虑它。

¥This is a known BashOnWindows issue, and on 15 Aug 2016, the Windows team said they would work on it. You can get progress updates and encourage them to prioritize it on the issue’s UserVoice suggestion page.

模板渲染错误

¥Template render error

有时运行命令 $ hexo generate 时会返回错误：

¥Sometimes when running the command $ hexo generate it returns an error:

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

可能的原因：

¥Possible cause:

• 你的文件中有一些无法识别的单词，例如不可见的零宽度字符。

  ¥There are some unrecognizable words in your file, e.g. invisible zero width characters.

• 标签插件 的使用或限制不正确。

  ¥Incorrect use or limitation of tag plugin.

  • 带有内容的块样式标签插件不包含在 {% endplugin_name %} 中

    ¥Block-style tag plugin with content is not enclosed with {% endplugin_name %}

  # Incorrect
  {% codeblock %}
  fn()
  {% codeblock %}
  
  # Incorrect
  {% codeblock %}
  fn()
  
  # Correct
  {% codeblock %}
  fn()
  {% endcodeblock %}

  • 在标签插件中使用类似 Nunjucks 的语法，例如 [`