博客搭建教程（二）

yngcy2024-07-102024-10-26

一、前言

在上一篇教程中，我们已经搭建了本地的博客，并且能够在本地调试查看博客页面。但是我们搭建博客的目的之一就是让别人能够看到我们的博客，这样做其他人并不能看到。因此需要将其部署在公网环境中，以便其他人可以通过链接访问到你的博客。

本篇教程介绍如何将博客发布在 GitHub Pages 上。在网上你可以找到很多类似本篇的教程，但是大多数文章已经是几年前的了，即使这些教程仍然具有一定的参考价值。本篇教程为尽可能采用相关技术的最新版本（截至本篇博客的最后更新时间），同时总结我在部署时碰到的一些问题，帮助你能在部署时少踩一些坑。

二、相关技术概述

在本篇教程中会有一些术语，可能对零基础的小伙伴来说有些生疏。为了方便你的更好地理解，下面我将介绍它们。同时，为了节省你的时间，我会尽我所能用精简的语言让你快速理解这些技术。如果你想做更深层次的了解，可以自行 Google 或是在评论区进行交流讨论。当然，你若都有了解过的话，可以选择跳过这一小节。

2.1 Git、GitHub、GitHub Pages是什么？

Git 是一个 分布式版本控制系统。版本控制是指记录若干文件的变化，并以版本来记录不同状态的文件。Git 与其他版本管理工具（如 SVN 等）的差别是 对待数据的方式，Git 采用的是直接记录快照的方式。Git 有三种状态，分别是 已提交（Committed）、已修改（modified）和已暂存（staged）。此外，Git 中还有一些基础概念：

仓库（Repository） 分为本地仓库和远程仓库，一个仓库包含了项目的所有版本历史。
分支（Branch） 用于管理代码的不同开发路线，主分支一般是 main 或 master，业内也有一套分支开发的规范，便于团队合作
克隆（Clone）、合并（Merge）、拉取（Pull）和推送（Push） 这几个是常用的几个 Git 操作，是本地与远程仓库的交互方式

GitHub 是基于 Git 的 在线代码托管平台，为团队协作提供便利。通过 GitHub 我们可以将代码上传到平台上，让他人可以看到我们的代码，同时也够参与到项目开发中。

GitHub Pages 是 GitHub 提供的一个 静态网站托管服务，它允许你直接从 GitHub 仓库中发布网站内容，一般适用于部署静态页面，如博客、项目文档等。

2.2 什么是 GitHub Action？

GitHub Action 是 GitHub 提供的一项 CI/CD 服务，也就是自动化工作流。其中你需要知道一些基本概念，包括：

工作流（Workflow）由一系列任务（Job）组成的自动化过程，定义于 .github/workflows 的 YAML 文件中。
任务（Job）是工作流中的一个独立任务，可以并行/顺序执行；一个任务中可以包含多个步骤。
事件（Event）是出发工作流执行的条件，一般是代码推送（Push）、PR（Pull Request）等。

三、GitHub Pages部署实战

在了解了相关概念后，下面来进行部署实战。在实践之前，我们来了解一下整个流程的工作原理。

3.1 工作原理

传统的工作流程是在本地使用 hexo generate 生成 public 目录，然后使用 hexo d 将其推送到 GitHub 的仓库中。在这种方式下，我们每次编写好新的文章后，都需要手动执行 hexo cl && && hexo g && hexo d，如果文件一多，生成的速度就会变慢，十分不方便。官方更推荐使用 GitHub Actions 来部署 GitHub Pages。博客的 GitHub Pages 工作流程下图所示。

3.2 准备工作

在部署之前，我们需要做一些准备工作，来让本地代码能够提交到 GitHub 上。

3.2.1 创建源码仓库

首先在 GitHub 上新建一个仓库，用于存放源码。

创建完成后，需要把博客源码创 push 到仓库。可以参考如下步骤：

如果 theme 目录下有主题文件，先删除 .git 目录以及所有文件，避免其被识别为子项目，从而无法上传到 GitHub 上。

在博客的工作目录下打开终端，输入如下命令：

1
2
3

git init
git remote add origin git@github.com:{github.username}/{hexo-SourceRepo}.git # github.username 是你的GitHub的用户名，hexo-SourceRepo是源码仓库名
git checkout -b main

添加 .gitignore 文件，可以参考如下内容：

.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
_multiconfig.yml
.deploy_git*/
.idea

将源码 push 到 GitHub 上，执行如下命令：

1
2
3

git add .
git commit -m "Initial Commit"
git push origin main

3.2.2 获取Access Token

在 GitHub 中，点击头像->Settings->Developer Settings->Personal access tokens，点击 Generate new tokens (classic)，创建 Token 用于后续步骤中的 GitHub Action。

在上图中，除了设置这个令牌的过期时间为永不过期，还设置了他的范围。因为我们要用这个令牌修改源码仓库以及 GitHub Action 的 workflow 工作流，因此需要勾选 repo 和 workflow。

注意生成的 token 只会显示一次，忘记了也没有关系，重新配置即可。

3.2.3 配置workflow

在上一篇教程中，在博客的工作目录中，你是否还记得 .github 用于存放博客工作流的配置文件？现在我们需要编写配置文件，在 .github 目录下新建 autodeploy.yml 文件，内容如下：

name: 自动部署
# 当有改动推送到mian分支时，启动Action
on:
  push:
    branches:
      - main
  release:
    types:
      - published


jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 检查分支
        uses: actions/checkout@v4
        with:
          ref: main
          fetch-depth: 0
      - name: Sync local file timestamps
        run: |
          git ls-files -z | while read -d '' path; do touch -d $(git log -1 --format="@%ct" "$path") "$path"; done

      - name: 安装 Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: 安装 Hexo
        run: |
          export TZ='Asia/Shanghai'
          npm install hexo-cli -g

      - name: 缓存 Hexo
        id: cache-npm
        uses: actions/cache@v4
        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 gulp-cli -g #全局安装gulp
          npm install --save --legacy-peer-deps # --legacy-peer-deps参数解决依赖的版本冲突
          npm ls --depth 0

      - name: 生成静态文件
        run: |
          hexo clean
          hexo bangumi -u #bilibili番剧更新
          hexo generate
          hexo algolia
          gulp

      - name: 部署到Github
        run: |
          cd ./public
          git init
          git config --global user.name "xxx"
          git config --global user.email "xxx@qq.com"
          git add .
          git commit -m '${{ github.event.head_commit.message }}'
          git push --force --quiet https://{}@github.com/xxx/xxx.github.io master:main


      # - name: 推送百度必应url
      #   run: |
      #     hexo deploy