hexo 踩坑记录 · dropsong's

upd 29/7/2026: 注意，本文章针对 hexo，这不是现在博客采用的框架。

live2d和aplayer

有时加载会很慢或者无法加载，这可能只是live2d和aplayer自身的问题。尤其是aplayer，偶尔会有几天在任何设备上都无法加载（我只遇到过一次）。

注意如果要使用网易的服务，要写成data-server="netease"，我这里因为不知道网易的英文名试了半天 -_-# ，不得不吐槽一下网易的这个英文名真的随便啊。

Upd：最后还是决定不使用 aplayer 了，VIP 音乐只能放 30 秒，而且访客也根本不会在意某个博客下面的音乐列表，至少我是这样。

Gitalk加载失败

Gitalk配置完成之后，仍有可能无法加载。这是因为其部分服务在墙外，需要翻墙访问文章页面以创建issue。之后即使不翻墙也可正常显示。

MathJax渲染失败

Hexo默认使用 hexo-renderer-marked 引擎渲染网页，该引擎会把一些特殊的 markdown 符号转换为相应的 html 标签，会产生语义冲突。

解决方案：更换Hexo的markdown渲染引擎。

npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-kramed --save

接下来到博客根目录下，找到node_modules\kramed\lib\rules\inline.js，把第11行的escape变量的值做相应的修改：

//  escape: /^\\([\\`*{}\[\]()#$+\-.!_>])/,
  escape: /^\\([`*\[\]()#$+\-.!_>])/

同时把第20行的em变量也要做相应的修改:

//  em: /^\b_((?:__|[\s\S])+?)_\b|^\*((?:\*\*|[\s\S])+?)\*(?!\*)/,
  em: /^\*((?:\*\*|[\s\S])+?)\*(?!\*)/

重新启动hexo即可。

问题（未解决）： 在 Hexo 中使用 MathJax 渲染数学公式时，行内公式可能会遇到左撇被渲染成右撇的问题。这是因为 MathJax 默认使用美国数学协会（American Mathematical Society，简称 AMS）的数学符号字体，而该字体中的左撇和右撇是相反的。

代码缩进混乱

这是tab缩进的问题。

找到站点配置文件中tab_replace，设置tab_replace: ' '（4个空格）即可。

嵌入音频和视频的方法

嵌入音频的例子（网易云等可生成外链的网站）：

<html>
<center>
<head>
	<meta charset="utf-8">
	<title></title>
</head>
<body>
	<iframe frameborder="no" border="0" marginwidth="0" marginheight="0" width=330 height=86 src="https://music.163.com/outchain/player?type=2&id=2045807071&auto=0&height=66"></iframe>
</body>
</center>
</html>

嵌入音频的例子（其他）：

<center>
<audio controls="controls" loop="loop">
	<source src="https://例子" type="audio/mp3"></source>
</audio>
</center>

嵌入视频的例子（bilibili）：

<div style="position: relative; width: 100%; height: 0; padding-bottom: 75%;">
    <iframe src="https://player.bilibili.com/player.html?bvid=BV1po4y157Sz&page=1&autoplay=0" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" style="position:absolute; height: 100%; width: 100%;"> </iframe>
</div>

嵌入视频的例子（youtube）：

<div style="position: relative; width: 100%; height: 0; padding-bottom: 75%;">
    <iframe src="https://www.youtube-nocookie.com/embed/7Hk3bW0yT2s?si=clISeZjsqLiaNs6I" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" style="position:absolute; height: 100%; width: 100%;"> </iframe>
</div>

外链音乐播放器手机端无法显示

暂未解决。

参考文献角标

前：

<a href="#bib1" id="bib1ref"><sup>[1]</sup></a>

后：

<a id="bib1" href="#bib1ref"><sup>[1]</sup></a> 这是一个示例，你可以修改此处文字

这是一个华丽丽的示例^[1]。

hexo pdf

参考： https://github.com/superalsrk/hexo-pdf

用法示例：

{% pdf https://drive.google.com/file/d/此处填入共享链接对应部分/preview %}

内嵌 PPT

使用 Microsoft 的 OneDrive 服务。

在 OneDrive 中上传你需要展示的 PPT ，然后选中文件，找到</>生成内嵌代码。

默认的代码在大小上有点问题，你可能需要修改为：

<iframe
  id="ppt"
  width="100%"
  onload="autoChange()"
  src="填入你获得的链接"
  frameborder="0"
></iframe>

<script>
  function autoChange() {
    let ifm = document.getElementById("ppt");
    ifm.height = (ifm.clientWidth / 16) * 9 + 24;
  }
  window.onresize = autoChange;
</script>

注意：如果你需要内嵌多个 PPT ，则应修改相应的id和函数名。

遮挡、外挂标签等

{% psw 示例 %}

外挂标签，请参考：Hexo+butterfly主题的外挂标签

此为 hexo 特有，如未来有换主题的打算，应减少使用。

iframe 嵌入网页

<iframe frameBorder="0" width="100%" height="100%" style="min-width: 300px; min-height:500px" src="网址" ></iframe>

这个尺寸适合我的博客，大小可以调整。

博客迁移

主体工作很简单，直接将博客根目录、NODEJS 复制到一块U盘/硬盘上，粘贴到新电脑即可。此外，还须做一些其他工作。

在博客根目录下，搜索文件hexo.cmd所在的目录，将路径配置到环境变量中。

将 NODEJS 所在路径，例如D:\NODEJS配置到环境变量中。

安装 git, Github 配置 SSH keys.

不要忘了将数据备份（例如图片资源）也迁移到新电脑上。

我这里不选择下载新版本的 NODEJS 是考虑到可能会与自己一开始用的版本有所不同，所以直接把旧电脑的 NODEJS 文件夹复制过来。

字体问题

该问题出现于 2026 年。

在过去的几年，Hexo 圈子依赖的很多免费 CDN（比如 jsDelivr 国内节点、各种 elemecdn 等）都经历了关停、被劫持或者降级。这导致了一些问题，于是我们用 CSS 强行绕过它，直接去最稳定的国际 CDN 拿货。

在 ./source/css/custom.css 的最前面添加如下代码：

/* =======================================================
   强行接管 Font Awesome 6 字体下载源，绕过腐烂的 CDN
   ======================================================= */
@font-face {
  font-family: 'Font Awesome 6 Free';
  font-style: normal;
  font-weight: 900;
  font-display: block;
  src: url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/webfonts/fa-solid-900.woff2') format('woff2'),
       url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/webfonts/fa-solid-900.ttf') format('truetype');
}

写码技巧

//            ⠀⠀⠀⠀⠰⢷⢿⠄   
//            ⠀⠀⠀⠀⠀⣼⣷⣄   
//            ⠀⠀⣤⣿⣇⣿⣿⣧⣿⡄ 
//            ⢴⠾⠋⠀⠀⠻⣿⣷⣿⣿⡀
//            ○ ⠀⢀⣿⣿⡿⢿⠈⣿ 
//            ⠀⠀⠀⢠⣿⡿⠁⠀⡊⠀⠙
//            ⠀⠀⠀⢿⣿⠀⠀⠹⣿  
//            ⠀⠀⠀⠀⠹⣷⡀⠀⣿⡄ 
//            ⠀⠀⠀⠀⣀⣼⣿⠀⢈⣧.
//
//     _     _   _    _    _    _     _
//    |_|   | |/ /   | |  | |  |  \  | |
//     _    | ' /    | |  | |  | \ \ | |
//    | |   |   \    | |  | |  | |\ \| |
//    | |   | |\ \   | |__| |  | | \ \ |
//    |_|   |_| \_\   \_____/  |_|  \ _|

^[1] 这是一个示例，你可以修改此处文字