疑難排解

如果您在使用 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

在生成大型部落格時記憶體不足 · 問題 #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 或 front-matter 停用 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 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.dev.org.tw/docs/troubleshooting.html
Template render error: (unknown path)

可能原因

  • 您的檔案中存在一些無法識別的文字，例如不可見的零寬度字元。

  • 標籤外掛的使用不正確或受限。

    • 包含內容的區塊式標籤外掛未使用 {% endplugin_name %} 包住
    # Incorrect
    {% codeblock %}
    fn()
    {% codeblock %}

    # Incorrect
    {% codeblock %}
    fn()

    # Correct
    {% codeblock %}
    fn()
    {% endcodeblock %}
    • 標籤外掛中包含類似 Nunjucks 的語法，例如 [`