搭建Hexo博客网站教程

Everett Rain2024-12-112025-04-30

本博客开始编写的日期为 2024/12/11
由于 Hexo 需要的部分 BASH 中的插件时效性强，不保证能解决你遇到的全部问题，如果你阅读的时间距离此文发布时间过长，请谨慎参考文章内容

读者必看

本博客为一篇答疑文章，主要包括关于 CSDN 作者 Cat Bayi 相当完善的教程中部分问题的解决方法，方便使用 Cat Bayi 教程的部分疑问的解决和备忘。

在开始阅读这篇文章前，请先确保你已经阅读完成下面的主要教程。该教程已经对不同系统下如何搭建 Hexo 博客进行了非常清晰且易懂的讲解，其中的主要问题和未涉及到的要点也已经在本文中进行了阐述。

点击下面的主要教程链接即可进入 Cat Bayi 的搭建教程。如果你遇到了本页面未涉及的疑问且无法解决，可以在本文下方的评论区进行提问，该博客会不定期更新并解决所提问题。

主要教程链接

Hexo教程，看这一篇就够了- How to系列

作者：Cat Bayi

常见问题

npm 下载失败，需要更换下载源

什么是镜像源？

镜像源是软件包管理工具用来下载和安装软件包的服务器地址。由于网络原因，直接使用官方源可能会导致速度慢或连接失败的问题。国内镜像源可以提供更快的访问速度和更稳定的连接。

设置方法

设置 npm 使用国内镜像源可以通过命令行进行，以下是设置淘宝镜像源的步骤：

1	npm config set registry https://registry.npmmirror.com/

设置完成后，可以通过以下命令验证是否成功切换到指定的镜像源：

1	npm get registry

如果输出的地址是刚刚设置的国内镜像源地址（这里是 https://registry.npmmirror.com/ ），则表示设置成功。

关于镜像源的选择
此处的淘宝镜像源只是举例，截至本稿发布该源仍然可用，但镜像源可能因为各种原因停止工作或不再维护，需要灵活更换
比如本人最初寻找到的教程提供的淘宝源为 https://registry.npm.taobao.org ，但该源已经基本停止使用

上传到 Pages 后主题不显示

原因：主题仓库和博客仓库嵌套

在使用 github 和 hexo 主题搭建个人博客过程中，我们使用 hexo 初始化的文件夹需要交给 github 进行代码托管，同时主题 themes 中的主题也是我们在github上面下载下来的，因此我们自己的仓库中，又嵌套了一个别人的仓库，这样的话，在 github 上面提交代码是不被允许的。

我们可以在博客文件夹下找到 themes 文件夹下我们下载的主题，这里我下载的主题是 butterfly，点开该主题的文件夹，查看文件夹中的隐藏的项目，我们看到该文件夹中出现一个 .git 文件夹，将该文件夹删除，这样该文件夹就不再是一个 git 本地仓库，主题中的配置文件我们也可以放到博客文件夹下，方便随时更新。

hexo 主题更新以后，我们又可以重新从 github 上面下载下来，再将里面的 .git 文件夹删除就行了。这样做，我们自己更新博客的代码就可以交给github给我们托管了。

删除后直接提交会报错 ERROR Deployer not found: git

需要在 BASH 中输入以下命令重新生成依赖项

1	npm install --save hexo-deployer-git

使用 Hexo 的提交命令时出错

报错 ssh: connect to host github.com port 22: Connection refused

详细报错代码：

ssh: connect to host github.com port 22: Connection refused
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

解决办法：

如果你使用了 Steam++ / Watt Toolkit 加速 Steam 或 GitHub，关闭加速后再次尝试即可

报错 detected dubious ownership in repository at ...

详细报错代码：

fatal: detected dubious ownership in repository at '...'
'...' is owned by:
        Administrator (管理员名称)
but the current user is:
        xxx (当前账户名称)
To add an exception for this directory, call:

解决办法：

退出并重新以管理员身份运行你的代码编辑器（推荐）
在 Git Bash 中输入：（这会让此电脑上的所有用户都能向你的仓库提交命令，不推荐）

1	git config --global --add safe.directory "*"

修改后的博客内容可以在本地查看，但上传后未显示修改内容

解决办法：

在浏览器中按下 F12 进入开发者模式，在 网络 选项卡中勾选 禁用缓存
按下 Ctrl + F5 进行强制刷新，或者在按下 F12 后右键刷新按钮选择 清空缓存并进行硬刷新
自行配置你的网站的缓存策略

punycode模块废弃警告

错误代码

在 nodejs v21.0.0 以上会出现如下提示

1 2	(node:83047) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created)

暂时无法解决，如果不影响效果可以暂时忽略 ( 我很菜 ) 💔