🎉 零基础小白从零搭建 Hexo 博客踩坑全记录(附常用指令小抄)
前言
作为一个完全零基础的小白,从最初不知道命令行是什么,到最后成功把博客上线、换上漂亮的Reimu主题、改好头像,一路踩坑一路填,终于拥有了自己的网站:https://moanjinhuan.top。
这篇文章记录了我整个搭建过程、遇到的报错以及解决办法,希望帮到同样零基础的你!
🛠️ 第一阶段:环境准备
1. 注册 GitHub 账号
访问 https://github.com/,点击 Sign up 注册。记住你的用户名,这是你博客网址的一部分。
2. 安装 Git 和 Node.js
下载安装 Git 时,一定要注意这三个选项:
- 默认编辑器:选 VS Code 或 Notepad。
- PATH 环境变量:选 Git from the command line and also from 3rd-party software(第二项)。
- 换行符转换:保持默认第一项即可。
3. 安装 Hexo
❌ 遇到的坑: 错误地打开了 Node.js 的快捷方式,在里面输入 npm i -g hexo-cli,结果报错 npm should be run outside of the Node.js REPL…。
✅ 解决办法: 退出 Node.js 环境(按 Ctrl + C 或 Ctrl + D),打开 Git Bash(在桌面右键选择 Git Bash Here)。在 Git Bash 中输入:
{ |
🏗️ 第二阶段:初始化博客和部署到 GitHub
1. 初始化博客
我在 ~/Moanjinhuan 目录下直接执行了:
{hexo init |
注意:并没有单独建 blog 文件夹,直接在 Moanjinhuan 文件夹里初始化了。
2. 创建 GitHub Pages 仓库
在 GitHub 新建仓库,名字必须是 你的用户名.github.io(例如 Moanjinhuan.github.io),设为 Public。
3. 连接本地与远程(九九八十一难开始)
❌ 遇到的坑一(SSH 连接被拒):
使用 git clone [email protected]:… 报错 Connection refused。
✅ 解决办法: 改用 HTTPS 协议。
git clone https://github.com/Moanjinhuan/Moanjinhuan.github.io.git |
❌ 遇到的坑二(Git 身份未知):
执行 hexo deploy 报错 Author identity unknown。
✅ 解决办法: 在 Git Bash 中告诉 Git 我是谁:
git config --global user.name "Moanjinhuan" |
❌ 遇到的坑三(授权卡住):
弹窗要求登录,浏览器授权卡死。
✅ 解决办法: 选择浏览器授权(Sign in with your browser)或直接使用 GitHub Token。去 GitHub 的 Settings -> Developer settings -> Personal access tokens 生成一个 Token(勾选 repo 权限),粘贴到密码框即可。
❌ 遇到的坑四(Pages 设置无法保存):
在 GitHub 仓库 Settings -> Pages 里,选 main 分支后 Save 按钮点不了。
✅ 解决办法: 因为页面顶部提示“已从 main 分支构建”,说明已经配置好了,无需重复保存。
4. 配置 Hexo 部署文件
在根目录 _config.yml 底部修改:
deploy: |
🎨 第三阶段:更换 Reimu 主题与个性化
1. 下载主题
在 ~/Moanjinhuan 下执行:
git clone https://github.com/D-Sketon/hexo-theme-reimu.git themes/reimu |
2. 启用主题并创建覆盖配置
将 _config.yml 中的 theme 改为 reimu。
为了以后更新方便,在根目录创建 _config.reimu.yml 文件,以后主题的配置都在这里改。
❌ 遇到的坑五(线上显示“xiba”,本地正常):
改完配置部署后,线上一直显示我之前随便测试的“xiba”。
✅ 解决办法: 重新执行部署三连,并在浏览器按 Ctrl + F5 强制刷新,清除 GitHub 的顽固缓存。
hexo clean && hexo generate && hexo deploy |
3. 修改网站标题和头像
修改标题:在 _config.reimu.yml 里找到 title:,修改冒号后面的文字(注意冒号后要有空格)。
修改头像:
把图片重命名为纯英文如 bayunzi.jpg。
把图片放到 Moanjinhuan/source/_data/avatar/ 文件夹里。
在 _config.reimu.yml 中找到 avatar:,改成 avatar: “bayunzi.jpg”(千万不要加路径,只写文件名)。
📝 第四阶段:日常维护与指令小抄
⭐ 日常写博客“三板斧”(最重要!)
以后每次写完文章,或者改完配置,只需要在 Git Bash 里依次输入下面这三行:
hexo clean # 清理旧缓存 |
💡 懒人极致版(一行搞定):
hexo clean && hexo generate && hexo deploy |
✍️ 写新文章
hexo new post "文章标题" |
然后去 source/_posts/ 文件夹里找那个 .md 文件写内容。
🧭 迷路指南
- cd ~/Moanjinhuan:回到你的博客目录(每次打开 Git Bash 的第一件事)。
- cd ..:退回到上一级文件夹。
- ls:看看当前文件夹里有什么。
- pwd:看看我现在在哪个路径。
🚀 偷懒
- 按键盘上的 ↑(上箭头):自动出现刚刚输入过的命令,不用手打!
- 按键盘上的 Tab 键:自动补全文件名或路径,防止拼错。
💡 避坑总结
所有命令都在 Git Bash 里敲,不要打开 Node.js 去敲!
改外观(头像、标题、颜色)都在 _config.reimu.yml 里改。
改了配置一定要重新执行部署三连,并且浏览器按 Ctrl + F5 强制刷新。
非常重要:定期备份你的本地 Moanjinhuan 文件夹,因为你的文章源码全在这里!
希望这篇文章能记录下我今天的努力,也能帮助到未来的自己。博客已上线,接下来就是好好写文章啦!🎉
编辑中,更新时间:2026年9月16日