故障排除

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

YAML 解析错误

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

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

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

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

您可以查看 YAML 规范 以获取更多信息。

EMFILE 错误

Error: EMFILE, too many open files

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

$ ulimit -n 10000

错误：无法修改限制

如果您遇到以下错误

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

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

要覆盖限制

  1. 在“/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”包含以下行。（如果这些文件不存在，请忽略此步骤）
session required pam_limits.so
  1. 如果您使用的是 基于 systemd 的 发行版，systemd 可能会覆盖“limits.conf”。 为了在 systemd 中设置限制，在“/etc/systemd/system.conf”和“/etc/systemd/user.conf”中添加以下行
DefaultLimitNOFILE=10000
  1. 重启

进程内存不足

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

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - process out of memory

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

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

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

Git 部署问题

RPC 失败

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

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

确保您已在计算机上正确 设置 Git，或者尝试使用 HTTPS 仓库 URL。

错误：ENOENT：没有此文件或目录

如果您遇到 Error: ENOENT: no such file or directory 之类的错误，这可能是因为您在标签、类别或文件名中混合使用了大写和小写字母。 Git 无法自动合并此更改，因此会中断自动分支。

要解决此问题，请尝试

  1. 检查每个标签和类别的字母大小写，确保它们一致。
  2. 提交
  3. 清理并构建：./node_modules/.bin/hexo clean && ./node_modules/.bin/hexo generate
  4. 手动将 public 文件夹复制到您的桌面
  5. 在本地从您的 master 分支切换到您的部署分支
  6. 将 public 文件夹的内容从您的桌面复制到部署分支
  7. 提交。 您应该会看到任何可以手动解决的合并冲突出现。
  8. 切换回您的 master 分支并正常部署：./node_modules/.bin/hexo deploy

服务器问题

Error: listen EADDRINUSE

您可能同时启动了两个 Hexo 服务器，或者可能存在其他应用程序使用相同的端口。 尝试修改 port 设置或使用 -p 标记启动 Hexo 服务器。

$ 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

未执行命令

当您无法获得除 help、init 和 version 之外的任何命令工作，并且您一直收到 hexo help 的内容时，这可能是由于 package.json 中缺少 hexo 造成的。

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

转义内容

Hexo 使用 [Nunjucks] 来渲染帖子（[Swig] 在旧版本中使用，它具有类似的语法）。 用 {{ }} 或 {% %} 括起来的内容将被解析，可能会导致问题。 您可以通过使用 raw 标签插件、单个反引号 `{{ }}` 或三个反引号来跳过解析。
或者，可以通过渲染器的选项（如果支持）、API 或 前置信息 来禁用 Nunjucks 标签。

{% 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 错误 (Windows Subsystem for Linux)

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

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

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

$ hexo generate
$ hexo server -s

这是一个 已知的 BashOnWindows 问题，在 2016 年 8 月 15 日，Windows 团队表示他们将对此进行修复。 您可以在 该问题的 UserVoice 建议页面 上获取进度更新并鼓励他们优先处理此问题。

模板渲染错误

有时，在运行命令 $ hexo generate 时，它会返回错误

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

可能原因

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

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

    • 带有内容的块级标签插件未用 {% endplugin_name %} 括起来
    # Incorrect
    {% codeblock %}
    fn()
    {% codeblock %}

    # Incorrect
    {% codeblock %}
    fn()

    # Correct
    {% codeblock %}
    fn()
    {% endcodeblock %}
    • 在标签插件中使用类似 Nunjucks 的语法，例如 [`