使用hexo搭建博客框架避坑笔记

引言

咲楓注：此次初体验让我感受到了，win的图形化界面及其生态对小白相当友好，但当涉及非图形化界面时，win真的是一坨……\x7e~不可名状之物~~，也不知道Linux会不会好一点。我个人是把环境配了一遍又一遍（心累，也可能是这方面经验比较少吧）。

1. CMD和git-bash的权限问题

当你把文件的移到D盘后，总是会发生一些奇奇怪怪的报错诶~

File Not Found

原因可能是以下几点：
1. 当前身份权限不足。尝试提升至管理员权限，或开放该文件夹的权限（不建议这么做）。
2. 环境变量错误，通俗来讲就是你原来储存的文件访问路径错误。这个一般是自己乱改导致的，改回去或者干脆重新再来就好。
3. 文件不存在。这个概率很小啦，要么是你就在该文件夹的子目录下（那当然找不到了），要么是下载文件到本地时网络有问题，文件存在损坏（这个一般安装时就会报错了）。
Invalid Command

例：Usage: hexo
1. 当前身份权限不足。尝试提升至管理员权限，或开放该文件夹的权限（不建议这么做）。
2. 操作对象错误。检查当前文件夹目录是否正确。
3. 版本和插件适配问题。检查版本是否需要更新，是否缺少支持该命令的插件。
  
  例：hexo d命令就需要先安装自动部署发布工具hexo-deployer-git

2. npm(node.js)与git的版本适配问题

一定要去官网下载最新最稳定的版本！

一定要去官网下载最新最稳定的版本！

一定要去官网下载最新最稳定的版本！

可以运行以下命令检查版本号
1
软件名 -v
千万不要相信自家电脑的应用商店，鬼知道它会给你安装哪个未完善的测试版本。（深恶痛绝）

无法下载安装包

无脑运行npm清理更新三部曲

1
2
3

npm cache clean --force  # 清理缓存
npm update -g npm        # 更新全局的所有依赖
npm update               # 更新当前项目的所有依赖

3. git与GitHub的连接问题

Validating config

一般就是以下几个方面的问题：
1. SSH
  
  运行以下命令检查与GitHub的连接
  1
  ssh -T git@github.com
2. Repository
  
  在本地博客目录下找到**_config.yml文件，用记事本打开，检查是否添加repository**地址。
3. GitHub登录
  
  运行以下命令检查当前用户和邮箱
  1
  2
  git config get user.email
  git config get user.name
  运行以下命令全局设置当前用户和邮箱
  
  用户邮箱必须与GitHub注册邮箱一致！！！
  1
  2
  git config --global user.email "用户邮箱"
  git config --global user.name "用户名"
4. VPN
  
  生成并上传文件时尝试关掉VPN代理。

4. hexo其它问题

说是hexo避坑指北，，其实也和hexo没太大关系

命令执行后一直等待ing

国内连接不上外网，解决方法如下：

~~科学上网（优先考虑）~~

npm换源

1
2
3

npm config get registry                                 # 查看原来的源
npm config set registry https://registry.npm.taobao.org # 修改为淘宝源
npm config get registry                                 # 查看现在的源

Blog の备份与迁移

本地魔改sever成功前，一定不要deploy！！！

Github备份

创建用于备份的Github仓库，并运行以下命令：

cd yourBlogBackup # 打开备份文件夹
git init
git remote add backup git@github.com:username/repositoryname.git
git add yourBlog/.
git commit -m "提交信息"
git push -u backup master # master 为默认分支名

而在进行备份时，也可不需要将整个博客目录全部备份，只需备份几个用户自定义的文件和配置

咲风比较懒，一般都是全部打包(#^.^#)

需要备份的文件和目录

scaffolds # 文章的模板
source # 文章和页面等源文件
themes # 主题文件与配置
_config.yml # 用户配置信息
package.json # 模块列表

不需要备份的文件和目录

node_modules  # 安装的模块
public # 生成的文件静态网页文件
db.json # 网页数据文件，编译生成静态网页时会自动更新
package-lock.json # 依赖的模块安装记录

此外如果主题目录下有.git 这个隐藏目录也可以删掉或者如下面所讲加入.gitignore 文件中在备份时忽略掉

后续备份，可将本地博客文件夹中需要备份的部分直接复制到备份文件夹，并运行以下命令：

1
2
3

git remote -v # 查看当前指向的远程仓库的详细信息
git commit -m "提交信息"
git push

以下为来自官网的参考命令：

echo "# repository's name" >> README.md # 输出内容并添加到md中
git init # 创建空仓库
git add . # 将所有文件添加进git暂存区
git commit -m "first commit" # 将暂存区的文件提交到本地仓库，并添加提交说明
git branch -M main # 将当前分支重命名为 main
git remote add origin git@github.com:username/repositoryname.git # 使用SSH，添加一个名为 origin 的远程仓库地址，指向 GitHub 上的仓库
git push -u origin main # 首次将本地 main 分支的代码推送到远程仓库 origin，并设置上游关联（后续提交可直接用 git push）

另外，通过以下操作，可灵活管理 Git 远程仓库的配置：

场景	命令
更换仓库地址	`git remote set-url origin 新地址`
重命名远程别名	`git remote rename origin 新别名`
删除旧远程仓库	`git remote remove origin`
添加新远程仓库	`git remote add origin 新地址`

迁移
1. 运行 hexo init 初始化一个hexo站点
2. 可运行以下命令将博客从GitHub重新clone到本地：
1
git clone git@github.com:username/repositoryname.git # 可从GitHub中SSH clone获取

图片路径问题（Butterfly主题）

有两种方法（源自DeepSeek）：
- 使用网络图片（图床/CDN）
  
  直接填写图片的完整 URL：
  1
  background: url(https://example.com/path/to/image.jpg)
  优点：无需本地存储图片，适合直接引用外部资源。
- 使用本地图片
将图片文件放入 Hexo 项目的 source/img 目录（若目录不存在可手动创建）
1
2
3
4
5
# 若网站根目录是 '/'（默认）
background: url(/img/your-image.jpg)

# 若网站根目录是子目录（如 `/blog`）
background: url(/blog/img/your-image.jpg)
优点：图片托管在本地，加载速度可控。

Butterfly官方文档是这样写的：

留意: 如果你的网站根目录不是’/‘,使用本地图片时，需加上你的根目录。
例如：网站是 https://yoursite.com/blog,引用一张img/xx.png图片，则设置 background 为 /blog/img/xx.png

**注意：**是/！不是\！