Hexo踩坑

发表于 更新于 分类于 ， 阅读次数： 本文字数： 3.8k 阅读时长 ≈ 7 分钟

一. 在 Hexo 博客中无法渲染数学公式，通常是因为 Hexo 默认不支持 LaTeX 公式渲染。你需要安装插件并配置 Hexo 以支持数学公式。以下是解决方案：

方法 1：使用 hexo-renderer-markdown-it 和 markdown-it-katex

  1. 卸载默认的 Markdown 渲染器
    Hexo 默认使用 hexo-renderer-marked，它不支持 LaTeX 公式。你需要先卸载它：

    1
    npm uninstall hexo-renderer-marked --save

  2. 安装 hexo-renderer-markdown-it
    这是一个更强大的 Markdown 渲染器，支持插件扩展：

    1
    npm install hexo-renderer-markdown-it --save

  3. 安装 markdown-it-katex 插件
    这个插件用于支持 LaTeX 公式渲染：

    1
    npm install markdown-it-katex --save

  4. 配置 _config.yml
    在 Hexo 的配置文件 _config.yml 中添加以下内容：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    markdown:
      render:
        html: true
        xhtmlOut: false
        breaks: true
        linkify: true
        typographer: true
        quotes: '“”‘’'
      plugins:
        - markdown-it-katex

  5. 引入 KaTeX 的 CSS
    在你的主题文件（例如 themes/your-theme/layout/_partial/head.ejs）中，添加以下代码以引入 KaTeX 的 CSS 文件：

    1
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css">

  6. 重启 Hexo 服务器
    重新启动 Hexo 服务器，查看公式是否正常渲染：

    1
    hexo clean && hexo server

方法 2：使用 hexo-renderer-pandoc（推荐）

如果你需要更强大的数学公式支持（如复杂的 LaTeX 公式），可以使用 hexo-renderer-pandoc。

  1. 卸载默认的 Markdown 渲染器
    卸载 Hexo 默认的渲染器：

    1
    npm uninstall hexo-renderer-marked --save

  2. 安装 hexo-renderer-pandoc
    安装 Pandoc 渲染器：

    1
    npm install hexo-renderer-pandoc --save

  3. 安装 Pandoc
    你需要在本机安装 Pandoc。根据你的操作系统选择安装方式：

    • Windows: 下载并安装 Pandoc。
    • macOS: 使用 Homebrew 安装：
      1
      brew install pandoc
    • Linux: 使用包管理器安装，例如：
      1
      sudo apt-get install pandoc

  4. 配置 _config.yml
    在 Hexo 的配置文件 _config.yml 中添加以下内容：

    1
    2
    3
    4
    5
    6
    7
    8
    markdown:
      render:
        html: true
        xhtmlOut: false
        breaks: true
        linkify: true
        typographer: true
        quotes: '“”‘’'

  5. 重启 Hexo 服务器
    重新启动 Hexo 服务器：

    1
    hexo clean && hexo server

方法 3：使用 hexo-filter-mathjax（简单但性能较差）

如果你不想折腾，可以使用 hexo-filter-mathjax，这是一个简单的插件，但性能较差。

  1. 安装插件
    安装 hexo-filter-mathjax：

    1
    npm install hexo-filter-mathjax --save

  2. 配置 _config.yml
    在 Hexo 的配置文件 _config.yml 中添加以下内容：

    1
    2
    mathjax:
      enable: true

  3. 重启 Hexo 服务器
    重新启动 Hexo 服务器：

    1
    hexo clean && hexo server

测试公式

在你的博客文章中，使用以下语法测试公式：

  • 行内公式：$E = mc^2$
    效果：E=mc2E = mc^2

  • 块级公式：$$E = mc^2$$
    效果：

    E=mc2E = mc^2

总结

  • 如果你需要简单的公式支持，推荐使用 方法 1（hexo-renderer-markdown-it + markdown-it-katex）。
  • 如果你需要更强大的公式支持，推荐使用 方法 2（hexo-renderer-pandoc）。
  • 如果你不想折腾，可以使用 方法 3（hexo-filter-mathjax），但性能较差。

二. Hexo Admin后台新建posts，一直显示loading

从错误信息来看，问题是由于 js-yaml 库的版本升级导致的。在 js-yaml 4.0.0 及以上版本中，yaml.safeLoad 方法已被移除，建议使用 yaml.load 方法代替。Hexo Admin 插件可能还在使用旧的 yaml.safeLoad 方法，因此导致了错误。

以下是解决该问题的步骤：

1. 修改 Hexo Admin 源码

  • 找到 Hexo Admin 插件中使用 yaml.safeLoad 的地方，将其替换为 yaml.load。
  • 根据错误日志，问题出现在 D:\AIGC\my_blog\node_modules\.pnpm\hexo-admin@2.3.0\node_modules\hexo-admin\api.js 文件的第 44 行。
  • 打开该文件，找到类似以下代码：
    1
    const settings = yaml.safeLoad(fs.readFileSync(settingsPath, 'utf8'));
  • 将其修改为：
    1
    const settings = yaml.load(fs.readFileSync(settingsPath, 'utf8'));

2. 降级 js-yaml 版本

  • 如果你不想修改源码，可以尝试将 js-yaml 降级到 3.x 版本，该版本仍然支持 yaml.safeLoad。
  • 运行以下命令：
    1
    npm install js-yaml@3.14.1 --save
  • 然后重新启动 Hexo 服务器。

3. 更新 Hexo Admin 插件

  • 检查是否有新版本的 Hexo Admin 插件，可能已经修复了该问题。
  • 运行以下命令更新插件：
    1
    npm install hexo-admin@latest --save

4. 检查 Hexo 和插件兼容性

  • 确保 Hexo 和 Hexo Admin 插件的版本兼容。
  • 查看 Hexo Admin 的官方文档或 GitHub 仓库，确认支持的 Hexo 版本。

5. 清理缓存并重启

  • 清理 Hexo 缓存并重新生成静态文件：
    1
    2
    hexo clean
    hexo generate
  • 重新启动 Hexo 服务器：
    1
    hexo server

6. 检查 YAML 文件格式

  • 确保 Hexo Admin 使用的 YAML 配置文件格式正确，没有语法错误。
  • 可以使用在线 YAML 校验工具（如 YAML Lint）检查配置文件。

7. 全局替换 yaml.safeLoad

  • 如果你的项目中还有其他地方使用了 yaml.safeLoad，可以全局替换为 yaml.load。
  • 使用代码编辑器的全局搜索功能，查找并替换所有 yaml.safeLoad 为 yaml.load。

8. 提交 Issue 给 Hexo Admin

  • 如果以上方法无效，建议到 Hexo Admin 的 GitHub 仓库提交 Issue，说明你的问题和环境信息（如 Hexo 版本、Node.js 版本等）。
  • Hexo Admin 仓库地址：https://github.com/hexojs/hexo-admin

9. 临时解决方案

  • 如果你急需解决问题，可以暂时锁定 js-yaml 的版本为 3.x，在 package.json 中添加以下内容：
    1
    2
    3
    "resolutions": {
      "js-yaml": "3.14.1"
    }
  • 然后运行 npm install 重新安装依赖。

通过以上方法，你应该能够解决 yaml.safeLoad 被移除的问题。

三. Hexo的next主题markdown列表无法正常渲染的问题

解决方案：

  • 修改custom.css样式

  • 打开 themes/next/source/css/custom.css 添加以下代码修复列表样式：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
     /* 强制覆盖主题样式 */
    .post .post-body ul,
    .post .post-body ol {
      padding-left: 2em !important;
      list-style-type: disc !important;  /* 无序列表样式 */
    }

    /* 有序列表样式 */
    .post .post-body ol {
      list-style-type: decimal !important;
    }

  • 通过主题中的_config.yml自定义样式，加载custom.css文件

    • 打开 themes/next/_config.yml

    • 找到 custom_file_path 部分，确保 style 指向正确路径：

    1
    2
    custom_file_path:
    	style: source/css/custom.css  # 取消注释

  • 清理缓存重新生成：

    1
    hexo clean && hexo g && hexo s