📖 本教程更新于 2023 年 05 月 18 日

📚 文档目录

🚀 搭建教程 | 1 - 📑 前置教程 | 2 - 🎈 主题调整 | 3 - ✨ 魔改教程 | 4 - 🐈 重构自用数据记录

前言

本教程仅仅是作为个人纪录
如若有兴趣动手按照本教程搭建自己的博客

搭建前，请提前浏览一遍本教程，和重要要点！

前期准备

安装Git

官网链接：https://git-scm.com/
阿里镜像源（下载速度快）：https://registry.npmmirror.com/binary.html?path=git-for-windows/

安装时，建议不要修改安装路径，否则会导致后面的批处理脚本出现问题

安装Node.js

官网链接：https://nodejs.org/zh-cn/

Node.js 版本需不低于 10.13，建议使用 Node.js 12.0 及以上版本
使用 Node.js 官方安装程序时，请确保勾选 Add to PATH 选项（默认已勾选）

更换npm镜像源

为了解决速度慢的问题
建议给Node.js换一个镜像源，这里更换的是淘宝的镜像源，代码如下：

1
2
3
4
5
6
淘宝镜像源：
$ npm config set registry https://registry.npm.taobao.org

npm官方源：
$ npm config set registry https://registry.npmjs.org/
(安装一些package 不容易报错)

安装Hexo

官网链接：https://hexo.io/

1
$ npm install hexo-cli -g

配置Git用户和ssh密钥

注：如需上传至GitHub或Gitee部署的，需要进行此步骤，其他可跳过

  • 在任意空白地方右键，选择 Git Bash Here 输入下面的命令
1
$ git config --global user.name "你的用户名"
1
$ git config --global user.email "你的邮箱"
1
$ ssh-keygen -t rsa -C "邮箱地址"

引号里对应填入自己的东西
接着在第三个命令后，会出现Enter开头的英文提示，这时候按三次 回车键 即可

配置SSH

SSH文件夹的默认存储位置是 C:\Users\电脑用户名.ssh

在ssh文件夹里，会显示 id_rsa 和 id_rsa.pub 两个文件
id_rsa是私钥，id_rsa.pub是公钥

将 id_rsa.pub 里的内容复制到 GitHub 的 Settings的SSH处

测试连接

完成上一步后可通过下面的这条命令测试是否于GitHub接通了

1
$ ssh -T git@github.com

Hexo搭建教程

初始化

  • 在你想存放的地方新建一个空文件夹，作为博客的源文件部署地

  • 在此文件夹内右键选择 Git Bash Here 输入下面的命令 初始化Hexo

1
$ hexo init

注：往后所有的操作都基于此文件夹
如果出现了什么问题无法解决，就只能删除
所以修改东西前注意做好备份

接下来就会在此目录下自动生成一些文件，初始化完成

本地调试

在Hexo根目录内右键选择 Git Bash Here 输入下面的命令
即可通过本地默认的4000端口访问进行预览调试

1
$ hexo s -debug

Butterfly主题教程

Butterfly主题官网：https://butterfly.js.org/
Butterfly项目地址：https://github.com/jerryc127/hexo-theme-butterfly
更多Hexo主题：https://hexo.io/themes/

主题安装

在Hexo根目录内右键选择 Git Bash Here 输入下面的命令

1
$ git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

接下来就会在此目录下自动下载主题文件到 themes 目录内

配置主题

在 Hexo根目录 内创建一个文件 _config.butterfly.yml
并把主题目录内 _config.yml 里面的内容 复制 到刚刚创建的 _config.butterfly.yml 里面去

注意: 复制的是主题内的 _config.yml，而不是 Hexo根目录 的 _config.yml

往后 _config.butterfly.yml 用来配置主题的文件
而 _config.yml 是用来配置Hexo框架等信息内容

启用主题

在Hexo根目录内打开 _config.yml
找到配置项 theme，修改为 theme: butterfly

在Hexo根目录内右键选择 Git Bash Here 输入下面的命令
即可通过本地默认的4000端口访问进行预览

1
$ hexo s -debug

上传网站

新建仓库

优点：
可以绑定自己的域名，也可以强制开启HPPTS
总体容量无限制，单个仓库推荐最大1G

缺点：

GitHub的服务器在国外，有时可能会访问不到、过慢或需要挂梯子
私有库需要付费使用
源代码完全公开，安全性略差

  • 打开 Github 官网并登录，点击右下角头像旁边的加号
  • 选择 New Repository（新建仓库）

  • 1、如果作为网站使用，仓库名称格式必须为：你的Github用户名.github.io

  • 2、选择 Public（公开）

  • 再点击 Create Repository 按钮完成创建

优点：
Gitee的服务器在国内，在国内访问的速度会很快
仓库出现问题，可快速联系管理员处理
私有库是免费的

缺点：
绑定域名属于付费内容
仓库、内容容易误封
涉及政治内容容易误封

  • 打开Gitee官网并登录，点击右下角头像旁边的加号
  • 选择新建仓库

  • 如果作为网站使用，仓库名称需要和你的用户名一样
  • Gitee Pages没有限制，开源和私有都能使用
  • 点击创建按钮完成创建

安装插件

在Hexo根目录内右键选择 Git Bash Here 输入下面的命令
即可安装Git部署插件

1
$ npm install --save hexo-deployer-git

_config.yml配置

  • 将下方左侧图的 url： 的链接改成：你的GitHub用户名.github.io
  • 再找到下方右侧图的 repo: 把SSH地址粘贴进去


  • 将下方左侧图的 url： 的链接改成：你的gitee用户名.gitee.io
  • 再找到下方右侧图的 repo: 把SSH地址粘贴进去


部署网站

在Hexo根目录内右键选择 Git Bash Here 安装顺序输入以下命令

  • 清除缓存
1
$ hexo clean
  • 生成静态文件
1
$ hexo g
  • 部署到远端
1
$ hexo d

报错案例

若遇到报错，请一个一个排查
更多报错案例请移步：Butterfly

本地预览出错

extends includes/layout.pug block content include ./includes/mixins/post-ui.pug #recent-posts.recent-posts +postUI include includes/pagination.pug

没有 pug 以及 stylus 的渲染器

解决方法：

  • 在Hexo根目录内右键选择 Git Bash Here 输入下面的命令
1
2
3
4
5
npm install hexo-renderer-pug hexo-renderer-stylus --save

或

yarn add hexo-renderer-pug hexo-renderer-stylus

push后出错/缺失/无效

本地可以正常运行，但是push上去后出错/缺失/无效

解决方法：

  • 清理浏览器缓存

  • 如果上方方法无效，请确认上传时是否有运行 hexo clean