Hexo 常见问题解决方案

Hexo 常见问题
Hexo
文章字数:   2.8k
阅读时长:   11 分

介绍

Hexo 是一个非常好用的静态博客生成器，但是由于很多方面的原因，导致在使用过程中经常出现错误。这些错误中，有些是因为自己的设置不当，导致程序报错；有些是因为版本更迭，导致原有的设置失效；而有些，则是 Hexo 程序本身的 BUG。

常见错误

1. 本地浏览没问题，Deploy 报错

Git 环境配置错误

  • 问题描述：
    Windows 系统下执行 hexo deploy 出现报错信息如下：

    [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 的相关配置，确保已将 Git 的安装目录（通常是 bin 目录）添加到了系统的 PATH 环境变量中去。

Deploy 设置错误

  • 问题描述：
    输入 hexo deploy 后，出现错误信息：

    'github' does not appear to be a git repository

  • 解决方案：

    1. 检查 _config.yml 文件中 deploy 部分的设置是否正确。可以参考 Hexo 官方文档 进行配置。
    2. 尝试删除项目根目录下的 .deploy_git 文件夹。
    3. 执行 hexo clean 清理缓存。
    4. 重新执行 hexo deploy。

2. Deploy 之后，页面长时间 404

  • 问题描述：
    部署到 GitHub Pages 之后，访问博客地址一直显示 404 页面。

  • 解决方案：

    1. 检查 Github Pages 类型和分支

      • 个人主页： 如果你的仓库名称是 yourname.github.io，那么你的网站文件必须推送到 master 分支。
      • 项目主页： 如果你的仓库是其他名称，那么网站文件必须推送到 gh-pages 分支。
        请注意，无论是哪种类型，推送到对应分支的都应该是 Hexo 生成的静态 HTML 文件，而不是 Markdown 源文件。

    2. 检查 Github 验证邮件
      如果你是新注册的 GitHub 用户，请检查你的注册邮箱是否收到了验证邮件，并完成了验证。未验证的账户可能导致 GitHub Pages 功能不正常。

    3. 注意库的名字
      虽然现在不强制，但建议个人主页的仓库名遵循 yourname.github.io 的格式。

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

  • 问题描述：
    将自有域名通过 CNAME 解析到 yourname.github.io 后，该仓库下的其他项目主页（例如 yourname.github.io/repo）通过 yoursite.com/repo 访问时出现 404。

  • 问题分析：
    问题出在 CNAME 跳转上。当你访问 yourname.github.io/repo 时，GitHub 会自动为你提供 gh-pages 分支的内容。但一旦设置了 CNAME，访问 yoursite.com/repo 时，DNS 解析会指向你的博客根目录，而你的博客目录下并没有一个名为 repo 的文件夹，因此自然会 404。

  • 解决方案：

    1. 增加一个新的 DNS 记录
      为你的项目单独设置一个二级域名。修改自己域名的 DNS 记录，增加一条 CNAME 记录，将 repo.yoursite.com 指向 yourname.github.io。之后，在项目仓库的 gh-pages 分支下也添加一个 CNAME 文件，内容为 repo.yoursite.com。

    2. 将这个库移动到博客目录下
      将另一个项目 repo 的静态文件直接移动到你博客站点的 source 文件夹下。注意，如果直接 clone，需要删除其隐藏的 .git 文件夹，以免造成 git 冲突。

4. Hexo 命令失效

  • 问题描述：
    输入 hexo new "title" 等命令后，只返回帮助信息，命令并未执行。

    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/

  • 解决方案：

    1. 检查 _config.yml 文件内容是否有语法错误，特别注意 冒号 : 后面必须有一个半角空格。
    2. 检查根目录下的 package.json 文件，确保其中包含 hexo 字段，用来标识这是一个 Hexo 目录： 
      {
  "hexo": {
    "version": ""
  }
}
    3. 如果问题依旧，可以尝试更新 hexo-cli，并在一个新的文件夹中重新执行 hexo init。

5. Hexo 所有命令报错

  • 问题描述：
    执行任何 hexo 命令都出现类似下面的报错，提示 Config file load failed。

    [error] { name: 'HexoError',
  reason: 'end of the stream or a document separator is expected',
  ...
  message: 'Config file load failed',
  ... 
}

  • 解决方案：
    这几乎可以肯定是 _config.yml 文件的 YAML 语法错误。YAML 格式对缩进和空格有严格要求。

    • 仔细检查 _config.yml 文件中所有 冒号 : 后面是否都跟了一个半角空格。
    • 不要使用 Tab 键进行缩进，应使用空格。
    • 如果不确定，建议将输入法切换到英文模式，手动删除所有冒号后面的空格并重新输入。

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

  • 问题描述：
    输入 hexo g 后，报错 incomplete explicit mapping pair。

    [error] { name: 'HexoError',
  reason: 'incomplete explicit mapping pair; a key node is missed',
  ...
  message: 'Process failed: languages/default.yml',
  ...
}

  • 解决方案：
    这个问题通常是由于主题语言文件中的 YAML 语法不规范引起的。将主题目录（themes/your-theme/）下的 languages 文件夹里的 .yml 文件中，所有包含空格的字段值用 双引号 括起来。例如：

    # 错误示例
tagcloud: Tag Cloud

# 正确示例
tagcloud: "Tag Cloud"

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

  • 问题描述：
    修改了主题的 .ejs 或 .css 文件后，重新生成部署，但网页上看不到任何变化。

  • 解决方案：

    1. 执行 hexo clean 清理缓存。
    2. 为了保险起见，可以手动删除根目录下的 .deploy_git 文件夹。
    3. 重新生成并部署：hexo g -d。
    4. 最后，使用 Ctrl+F5 (或 Cmd+Shift+R) 强制刷新浏览器缓存，载入最新的资源文件。

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

  • 问题描述：
    生成的页面是原始的 EJS 代码，没有被渲染成 HTML。

    <%- partial('_partial/head') %>
<%- partial('_partial/header', null, {cache: !config.relative_link}) %>
<%- body %>

  • 解决方案：
    这通常意味着 Hexo 的渲染插件没有正确安装。在你的博客根目录下执行 npm install 来安装 package.json 中声明的所有依赖。

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

  • 问题描述：
    升级到 Hexo 3.0 后，执行 hexo g 过程非常缓慢，甚至卡死，即使文章数量不多。

  • 问题分析：
    问题可能出在 Highlight.js 在代码块语言判断上。当代码块的语言标识中包含 - 符号时，可能会导致其解析引擎卡死。

  • 解决方案：
    在使用代码块时，明确指定一个有效的语言类型，或者全部使用 plain 类型来避免高亮解析。

    ```plain
something here
```

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

  • 问题描述：
    升级到 Hexo 3.0 后，执行 hexo deploy 报错：

    ERROR Deployer not found: github

  • 问题分析：
    Hexo 3.0 将许多核心模块（包括部署器）从主程序中分离了出来，需要单独安装。

  • 解决方案：

    1. 安装对应的 deployer 插件。如果你使用 Git 部署，就安装 hexo-deployer-git。

      npm install hexo-deployer-git --save

    2. 然后，修改 _config.yml 文件中的 deploy 设置，确保 type 类型正确：

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

11. Mac OS 安装 Hexo 出错

  • 问题描述：
    在 Mac OS 上安装 Hexo 时，命令行返回 DTraceProviderBindings 相关的错误。

    { [Error: Cannot find module './build/Release/DTraceProviderBindings'] code: 'MODULE_NOT_FOUND' }

  • 解决方案：
    这是 dtrace-provider 这个可选依赖包的问题，在安装时跳过它即可。

    npm install hexo --no-optional

常见问题

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

使用 Git 来管理你的整个博客文件夹，可以非常方便地实现多设备同步。

  1. 管理主题： 如果你的主题也是一个 Git 仓库，请将其作为 git submodule 来管理，或者直接删除主题文件夹下的 .git 目录，否则父仓库无法跟踪主题的变动。
  2. 同步和安装： 将整个博客文件夹（除了 node_modules）推送到一个 Git 仓库（如 GitHub）。在另一台电脑上 clone 下来后，需要重新执行 npm install 来安装所有依赖。**注意不要执行 hexo init**，否则会覆盖你的 _config.yml 等配置文件。

2. 如何在主目录下添加 README.md 或其他 HTML 文件？

有时候我们需要在网站根目录放置一些非 Hexo 生成的文件，比如 README.md 或者网站所有权验证文件。

  • Hexo 3.0 以下：
    将需要保留的原始文件放置在当前使用主题的 source 目录下（例如 themes/your-theme/source/）。该目录下的所有文件会被直接复制到网站的根目录，而不会被 Hexo 渲染。

  • Hexo 3.0 以上：
    推荐使用 _config.yml 文件中的 skip_render 参数。这个参数可以让你指定哪些文件或文件夹不需要被渲染。

    # _config.yml

# 跳过 source/test 文件夹下的所有文件
skip_render: 'test/**'

# 跳过多个文件夹或文件
skip_render:
  - 'test/**'
  - 'demo.html'
  - 'another_folder/*.md'

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

使用 Disqus

Hexo 默认支持 Disqus。只需打开 _config.yml 文件，在 disqus_shortname: 后面填上你的 Disqus shortname 即可。

# _config.yml
disqus_shortname: your_shortname

使用多说 (Duoshuo)

注意： 多说服务已经下线，此方法已失效，仅作示例参考。

如果你的主题原生支持多说，直接在主题配置文件中填写你的多说账号即可。如果不支持，需要手动添加代码。

  1. 在主题的 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')
         || document.getElementsByTagName('body')).appendChild(ds);
    })();
    </script>
<!-- 多说公共JS代码 end -->
  2. 在文章模板 article.ejs (或类似) 文件中，添加评论框容器： 
    <% if (page.comments){ %>
    <div class="ds-thread" data-thread-key="<%- page.path %>" data-title="<%- page.title %>" data-url="<%- page.permalink %>"></div>
<% } %>

4. 如何避免在 Deploy 时每次都输入密码？

  • 使用 SSH 协议： 将部署仓库的 URL 从 HTTPS 格式 (https://github.com/...) 修改为 SSH 格式 ([email protected]:...)。
  • 生成并配置 SSH Key： 如果你还没有配置过 SSH Key，请参考GitHub官方教程生成一个新的 SSH 密钥，并将其公钥添加到你的 GitHub 账户中。

5. 如何同时部署到多个 Git 仓库？

hexo-deployer-git 插件支持同时部署到多个仓库。修改 _config.yml 如下：

# _config.yml
deploy:
  type: git
  repo:
    github: https://github.com/user/repo.git,master
    gitee: https://gitee.com/user/repo.git,master

请注意 YAML 格式，每个冒号 : 后面必须有空格。

Hexo 常见问题
  目录