Hexo博客搭建基础教程(一)

魔改前必看（我当你们都懂了，太细节的就不写在教程中了🤣🤣🤣）
1.博客魔改有风险，如果博客魔改出问题了又没有备份，可通过此项目查看基础源码进行回滚：jerryc127/hexo-theme-butterfly、ccknbc-actions/blog-butterfly.这部分魔改基本上都是大佬们造好的轮子，我按照大佬们的轮子结合自己的喜好进行魔改的，如有侵权请联系删除。
2.鉴于每个人的根目录名称都不一样，本帖博客根目录一律以[BlogRoot]指代。
3.本帖涉及魔改源码的内容，会使用diff代码块标识，复制时请不要忘记删除前面的+、-符号。
4.因为.pug和.styl以及.yml等对缩进要求较为严格，请尽量不要使用记事本等无法提供语法高亮的文本编辑器进行修改。
5.本帖基于Butterfly主题进行魔改方案编写，因此请读者优先掌握Butterfly主题官方文档的内容后再来进行魔改。
6.魔改会过程常常引入自定义的css与js文件，方法见Hexo博客添加自定义css和js文件(后续引入)
博客搭建与魔改系列教程导航🚥🚥🚥
1.🥬Hexo博客搭建基础教程(一) ⇦当前位置🪂
2.🍒Hexo博客搭建基础教程(二)
3.🥪Hexo博客搭建基础教程(三)
4.🍀博客魔改教程总结(一)
5.🍚博客魔改教程总结(二)
6.🎋博客魔改教程总结(三)
7.🥕博客魔改教程总结(四)
8.🍊博客魔改教程总结(五)

搭建环境

本文分为本机搭建和云端构建，本机搭建通过在本地搭建好必备环境配备代理工具以及上传仓库；而云端构建通过使用github action来进行操作，用写好的yml代码来进行构建。

本机搭建

环境与工具准备

操作系统：Windows11 24H2
Node v22.14.0
Git
Hexo V6.3.0
文本编辑器(强烈推荐VSCODE)
GitHub 帐号
一个域名（强烈推荐买个域名）
云服务器（可选）

下载node并简单切换镜像源

1. 打开Node官网，下载和自己系统相配的Node的安装程序。下载地址：https://nodejs.org/en/download/
2. 下载后安装，安装的目录可以使用默认目录【C:/Program Files/nodejs/】，也可以自定义路径。这个环境路径切换坑也很多，如果大家C盘空间足够可以直接装C盘，如果想切换其他盘或者把环境遍历切换到自定义路径也可以，具体教程百度(不过坑比较多就是了)!
3. 安装完成后，检查是否安装成功。在键盘按下win + R键，输入CMD，然后回车，打开CMD窗口，执行node -v命令，看到版本信息，则说明安装成功。
4. 切换npm源：
   • 官方源
   • 阿里云镜像源
   • 腾讯云镜像源
   • 华为云镜像源

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

   npm config set registry https://npm.aliyun.com

   npm config set registry http://mirrors.cloud.tencent.com/npm/

   npm config set registry https://mirrors.huaweicloud.com/repository/npm/

安装Hexo

在终端输入如下命令安装：

npm install -g hexo-cli

如果成功会出现以下内容:

added 1 package, removed 30 packages, and changed 52 packages in 12s

14 packages are looking for funding
  run `npm fund` for details

再次在终端中输入命令：

npm install hexo-server --save

如果成功会出现以下内容:

added 48 packages in 4s

3 packages are looking for funding
  run `npm fund` for details

注册github账号

看这个注册视频，按照步骤即可：

Git安装

1. 进入官网：https://git-scm.com/downloads ，由于官网下载太慢可以通过淘宝的开源镜像下载 网址：https://registry.npmmirror.com/binary.html?path=git-for-windows/v2.36.1.windows.1/ ，下载版本更具自己的需求选择即可。

2. 下载后傻瓜式安装Git即可，安装的目录可以使用默认目录【C:/Program Files/Git】，也可以自定义路径。

3. 点击电脑左下角开始即可看见Git Bash。

git快捷方式

• Git CMD 是windows 命令行的指令风格
• Git Bash 是linux系统的指令风格（建议使用）
• Git GUI是图形化界面（新手学习不建议使用）

1. 常用命令

   git config -l  //查看所有配置
   git config --system --list //查看系统配置
   git config --global --list //查看用户（全局）配置

2. 配置用户名和邮箱:

   git config --global user.name "你的用户名"
   git config --global user.email "你的邮箱"

3. 查看git当前配置：

   git config -l

部署博客

初始化hexo

1. 在目标路径（我这里选的路径为【D:/sxiaohe/sxiaohe】）打开cmd命令窗口，执行hexo init初始化项目。

   hexo init blog-demo

   如果成功会出现以下内容：

   INFO  Cloning hexo-starter https://github.com/hexojs/hexo-starter.git
   INFO  Install dependencies
   warning ..\package.json: No license field
   warning hexo > warehouse > cuid@2.1.8: Cuid and other k-sortable and non-cryptographic ids (Ulid, ObjectId, KSUID, all UUIDs) are all insecure. Use @paralleldrive/cuid2 instead.
   warning hexo-renderer-stylus > stylus > glob@7.2.3: Glob versions prior to v9 are no longer supported
   warning hexo-renderer-stylus > stylus > glob > inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
   INFO  Start blogging with Hexo!

2. 进入blog-demo ，输入npm i安装相关依赖:

   cd blog-demo  //进入blog-demo文件夹
   npm i

   如果成功会出现以下内容：

   changed 16 packages, and audited 228 packages in 3s
   
   32 packages are looking for funding
     run `npm fund` for details
   
   found 0 vulnerabilities

3. 初始化项目后，blog-demo有如下结构：

   |-- blog-demo
       |-- .gitignore
       |-- package-lock.json
       |-- package.json
       |-- yarn.lock
       |-- _config.landscape.yml
       |-- _config.yml
       |-- .github
       |   |-- dependabot.yml
       |-- scaffolds
       |   |-- draft.md
       |   |-- page.md
       |   |-- post.md
       |-- source
       |   |-- _posts
       |       |-- hello-world.md
       |-- themes
           |-- .gitkeep

   文件夹介绍:
   【node_modules】：依赖包
   【scaffolds】：生成文章的一些模板
   【source】：用来存放你的文章
   【themes】：主题
   【.npmignore】：发布时忽略的文件（可忽略）
   【_config.landscape.yml】：主题的配置文件
   【config.yml】：博客的配置文件
   【package.json】：项目名称、描述、版本、运行和开发等信息
4. 输入hexo server或者hexo s 启动项目，启动成功终端会出现以下内容：

   INFO  Validating config
   INFO  Start processing
   INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

   初始化github存储库

   当我们新建存储库后，需要对存储库进行初始化
5. 在bash中键入以下代码，初始化存储库：

   echo "# ACTION" >> README.md
   git init
   git add README.md
   git commit -m "first commit"
   git branch -M main
   git remote add origin https://github.com/661111/ACTION.git
   git push -u origin main

   终端输出：

   C:\Users\ASUS>echo "# ACTION" >> README.md
   C:\Users\ASUS>git init
   Initialized empty Git repository in C:/Users/ASUS/.git/
   C:\Users\ASUS>git add README.md
   C:\Users\ASUS>git commit -m "first commit"
   [master (root-commit) ac892ea] first commit
    1 file changed, 1 insertion(+)
    create mode 100644 README.md
   C:\Users\ASUS>git branch -M main
   C:\Users\ASUS>git remote add origin https://github.com/661111/ACTION.git
   C:\Users\ASUS>git push -u origin main

6. github页面如图，已经创建好了：
   

部署到github存储库

1. 安装 hexo-deployer-git：

   npm install hexo-deployer-git --save

2. 修改 _config.yml 文件
   在blog-demo目录下的_config.yml，就是整个Hexo框架的配置文件了。可以在里面修改大部分的配置。详细可参考官方的配置描述。
   修改最后一行的配置，将repository修改为你自己的github项目地址即可，还有分支要改为main代表主分支（注意缩进）。

   deploy:
     type: git
     repository: https://github.com/661111/ACTION.git
     branch: main

3. 修改好配置后，运行如下命令，将代码部署到 GitHub（Hexo三连）:

   hexo clean && hexo generate && hexo deploy  // Git BASH终端
   hexo clean; hexo generate; hexo deploy  // VSCODE终端

• hexo clean：删除之前生成的文件，若未生成过静态文件，可忽略此命令。
• hexo generate：生成静态文章，可以用hexo g缩写
• hexo deploy：部署文章，可以用hexo d缩写
  如果成功会出现以下内容：

  INFO  Validating config
  INFO  Deleted database.
  INFO  Validating config
  INFO  Start processing
  INFO  Files loaded in 103 ms
  INFO  Generated: archives/index.html
  INFO  Generated: archives/2025/index.html
  INFO  Generated: archives/2025/03/index.html
  INFO  Generated: index.html
  INFO  Generated: fancybox/jquery.fancybox.min.js
  INFO  Generated: css/style.css
  INFO  Generated: js/script.js
  INFO  Generated: fancybox/jquery.fancybox.min.css
  INFO  Generated: js/jquery-3.6.4.min.js
  INFO  Generated: css/images/banner.jpg
  INFO  Generated: 2025/03/24/hello-world/index.html
  INFO  11 files generated in 313 ms
  INFO  Validating config
  INFO  Deploying: git
  INFO  Setting up Git deployment...
  Initialized empty Git repository in D:/sxiaohe/sxiaohe/blog-demo/.deploy_git/.git/
  [master (root-commit) 61e96f4] First commit
   1 file changed, 0 insertions(+), 0 deletions(-)
   create mode 100644 placeholder
  INFO  Clearing .deploy_git folder...
  INFO  Copying files from public folder...
  INFO  Copying files from extend dirs...
  warning: in the working copy of '2025/03/24/hello-world/index.html', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'archives/2025/03/index.html', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'archives/2025/index.html', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'archives/index.html', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'css/style.css', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'fancybox/jquery.fancybox.min.js', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'index.html', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'js/jquery-3.6.4.min.js', LF will be replaced by CRLF the next time Git touches it
  warning: in the working copy of 'js/script.js', LF will be replaced by CRLF the next time Git touches it
  [master 7b5f7ea] Site updated: 2025-03-24 21:01:33
   12 files changed, 2475 insertions(+)
   create mode 100644 2025/03/24/hello-world/index.html
   create mode 100644 archives/2025/03/index.html
   create mode 100644 archives/2025/index.html
   create mode 100644 archives/index.html
   create mode 100644 css/images/banner.jpg
   create mode 100644 css/style.css
   create mode 100644 fancybox/jquery.fancybox.min.css
   create mode 100644 fancybox/jquery.fancybox.min.js
   create mode 100644 index.html
   create mode 100644 js/jquery-3.6.4.min.js
   create mode 100644 js/script.js
   delete mode 100644 placeholder
  Enumerating objects: 27, done.
  Counting objects: 100% (27/27), done.
  Delta compression using up to 16 threads
  Compressing objects: 100% (19/19), done.
  Writing objects: 100% (27/27), 278.04 KiB | 11.58 MiB/s, done.
  Total 27 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
  remote: Resolving deltas: 100% (4/4), done.
  To https://github.com/661111/ACTION.git
   + ac892ea...7b5f7ea HEAD -> main (forced update)
  branch 'master' set up to track 'https://github.com/661111/ACTION.git/main'.
  INFO  Deploy done: git

1. 打开存储库，可以看到页面出现许多文件：
   

云端构建

说完本机搭建，那么说说云端构建吧。其实云端构建就是本地有一份已经修改完但还没有发布到存储库，而存储库存储着之前的文件，相当于一份备份，当我们修改完发表到云端。先上传到存储库，存储库里的文件更新后自动触发action，成功后存储库和服务器上的博客会自动更新，vercel会开始构建静态文件，就可以看到新内容了。

开始之前

为了确保交由Github Action来持续部署时，Github Action 具备足够的权限来进行 hexo deploy 操作,需要先获取 Token。

• GITHUB

访问 Github->头像（右上角）->Settings->Developer Settings->Personal access tokens->generate new token,创建的 Token 名称随意，但必须勾选 repo 项 和 workflows 项。

新建action工作流

1. 在[Blogroot]新建.github文件夹,注意开头是有个.的。然后在.github 内新建 workflows 文件夹，再在 workflows 文件夹内新建 autodeploy.yml,在[Blogroot]/.github/workflows/autodeploy.yml 里面输入：

   name: 自动部署
   on:
     push:
       branches:
         - main
     release:
       types:
         - published
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - name: 检查分支
           uses: actions/checkout@v2
           with:
             ref: main
   
         - name: 安装 Node
           uses: actions/setup-node@v1
           with:
             node-version: "22.13.0"
   
         - name: 安装 Hexo
           run: |
             export TZ='Asia/Shanghai'
             npm install hexo-cli -g
         - name: 缓存 Hexo
           id: cache-npm
           uses: actions/cache@v3
           env:
             cache-name: cache-node-modules
           with:
             path: node_modules
             key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
             restore-keys: |
               ${{ runner.os }}-build-${{ env.cache-name }}-
               ${{ runner.os }}-build-
               ${{ runner.os }}-
         - name: 安装依赖
           if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
           run: |
             npm install --global gulp-cli
             npm update hexo --save
             npm install --save
   
         - name: 生成静态文件
           run: |
             hexo clean
             hexo generate
             gulp
   
         - name: 推送到Github仓库
           uses: JamesIves/github-pages-deploy-action@v4
           with:
             token: ${{ secrets.HEXO_TOKEN }}
             repository-name: 661111/hexo-site-page
             branch: main
             folder: public
             commit-message: "${{ github.event.head_commit.message }} Updated By Github Actions"

2. 之后需要自己到仓库的 Settings->Secrets->actions 下添加环境变量，变量名参考表格：

   如何添加：
   

参数	参数内容	是否需要
HEXO_TOKEN	github账号密钥	✅

部署云端

1. 添加屏蔽项
   因为能够使用指令进行安装的内容不包括在需要提交的源码内，所有我们需要将这些内容添加到屏蔽项，表示不上传到 github 上。这样可以显著减少需要提交的文件量和加快提交速度。
   打开[Blogroot]/.gitignore,输入以下内容：

   .DS_Store
   Thumbs.db
   db.json
   *.log
   node_modules/
   public/
   .deploy*/
   .deploy_git*/
   .idea
   themes/[改成你自己的主题名称]/.git

2. 提交源码到私有仓库[SourceRepo]
   在博客根目录[Blogroot]下启动终端，使用 git 指令重设仓库地址。这样在新建仓库，我们仍旧可以保留珍贵的 commit history，便于版本回滚。

   git remote rm origin # 删除原有仓库链接
   git remote add origin https://github.com/[GithubUsername]/[SourceRepo].git #[SourceRepo]为新的存放源码的github私有仓库
   git checkout -b main # 切换到main分支，
   git add .
   git commit -m "github action update"
   git push origin main

3. 查看部署情况
   打开 GIthub 存放源码的私有仓库，找到 action。
   
   根据刚刚的 Commit 记录找到相应的任务
   
   点击 Deploy 查看部署情况,如果看到全部打勾，即为成功
   

4. 如果在有加速的情况下有时候无法正常上传，可以再追加命令行:

   git add .
   git commit -m "github action update"
   git rebase --continue
   git push -f origin main