关于如何利用github pages搭建个人博客

搞了一圈，终于算是明白github pages到底是怎么自动化搭建博客的了。 网上的教程很多，这里就不再赘述了，这里主要是帮xd们梳理一下概念以及大致流程，顺便记录一下自己搭建博客的过程，以及踩过的坑。

简要介绍

本项目的blog搭建脚手架选择了vuepressopen in new window，这是一个基于vue的静态网站生成器，可以很方便的生成静态网站，同时支持markdown语法，可以很方便的写博客。 选择的模版是vuepress-theme-recoopen in new window，这是一个非常炫酷的模版，你可以在这个的基础上更进开发。

概念梳理

vuepress

vuepress是一个静态网站生成器，其会基于你所给出的md文件等静态文件（如图片，css，js）渲染一个静态网页，也就是说，只要你搞好了配置，把md文件扔进去，然后利用vuepress提供的npm run build命令

或者是yarn docs:build，这个基于你的工具，也有可能是npm run build，这一个命令看你所使用脚手架的package.json文件：

  "scripts": {
    "dev": "vuepress dev .",
    "start": "vuepress dev .",
    "build": "vuepress build ."
  },

如在这里，json键值对的key值为dev，start，build，分别对应dev，start，build命令。其他的脚手架可能key值不同，比方说“docs:build”，请自行查看。我们所需要的是值为"vuepress build ."这一条的key值，只有这一条一定要准确！不能出错，否则自动配置的部署部分会报错！现在记不住不用担心，后面写自动化脚本了，我会提醒bro回去看一眼这个key值是否对的上。

就会生成一个静态web，这个web项目会被放到.vuepress/dist文件夹下（一般情况下vuepress都会将最终的web生成在这里，推荐还是仔细看一下自己选的脚手架是否有不同），所以注意.vuepress文件夹的路径，后续我们在写自动化的sh文件时这个路径也不能错，如果是在根路径那就不用加前缀了，假如.vuepress文件夹不是在你的项目根路径下，那一定要把项目中的父路径加上！

这里需要明确一点：最终生成的静态web才是最终展示的page，而vuepress只是生成器，请注意。

Github Page

github page提供了静态网页的展示，你可以搞一个个人的page（username.github.io）也可以是仓库的（repo）。

在仓库的setting --> page页面下可以配置该仓库的page，这里使用个人的github page，会自动配置page，完成配置后会显示具体分配的网页ip。

Github Action（自动化实现）

GitHub Actions 是 GitHub 提供的一项功能，允许你在 GitHub 上托管的代码仓库中创建自定义的工作流（workflows）。这些工作流可以自动化各种软件开发过程中的任务，比如构建、测试和部署代码。通过 GitHub Actions，开发者可以在代码提交、合并请求或定时触发等条件下自动运行特定的任务。

Github会检查仓库中是否存在.github文件夹来确认是否需要action等自动化操作，我们在项目的根目录下加入.github文件夹在里面创建workflows文件夹，在里面配置yml文件即可实现自动化工作流。

1. Workflow（工作流）：一个工作流是自动化过程的集合，由一个或多个作业组成。工作流通过 .github/workflows 目录下的 YAML 文件定义，并在 GitHub 仓库中配置。工作流可以根据不同的事件触发，如推送代码、创建拉取请求等。

2. Job（作业）：作业是工作流中的一个步骤集合。一个工作流可以包含一个或多个作业，每个作业都会在一个新鲜的虚拟机上运行或者是在同一个执行器中并行/串行地运行。

3. Step（步骤）：步骤是作业中的命令或动作。步骤可以是运行一些 shell 命令、使用 GitHub 社区分享的操作（actions），或者你自己的操作。

4. Action（操作）：操作是用于执行复杂但常见的任务的可重用单元，例如设置语言环境、打包代码等。你可以使用 GitHub 社区提供的操作，也可以编写自己的操作。

5. Runner（运行器）：runner 是执行你的工作流的机器。GitHub 提供了 Ubuntu Linux、Windows 和 macOS 的 runner，你也可以托管自己的 runner。

我们所需要的就是实现每次push触发vuepress的npm的安装，build成静态web，再推送到指定github page的分支。本次创建个人Blog所需要的就是在仓库根路径中加入.github/workflows下配置一个yml文件，实现每次push触发推送：

name: Deploy to GitHub Pages

on:
  push: # 每次push就会触发workflows
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write # 修改为 write 权限
      pages: write
      id-token: write

    steps:
      - name: 🚀 Checkout 源码
        uses: actions/checkout@v4

      - name: 🧱 设置 Node.js 环境
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: 📦 安装依赖
        run: npm install

      - name: 🔧 构建项目
        run: npm run build # 注意查看package.json确认命令是否正确

      - name: 🚀 部署到 GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .vuepress/dist # 注意检查位置是否正确
          commit_message: 'Deploy to GitHub Pages'
          publish_branch: gh-pages  # 可选，默认就是 gh-pages，可以省略

有了以上生成blog的工具，发布静态blog的工具，每次push就会自动部署的工具后，我们只需要写md文件，放到指定位置，再将整个vuepress push到vuepress仓库分支中，就会自动更新我们的blog了！

实现流程

1. npm安装vuepress/你的脚手架

打开你所准备好的文件夹，在命令行中输入：

# 初始化，并选择 2.x
npm install @vuepress-reco/theme-cli@1.0.7 -g
theme-cli init

（node请尽量安装18以上的）

如果你有本地/自己的服务器部署的需求，需要检查一下，也可以使用npm run dev来尝试运行vuepress，最终会生成本地的预览网页，具体访问地址也会在命令行给出，对应命令请参照自己的package.json文件：

  "scripts": {
    "dev": "vuepress dev .",
    "start": "vuepress dev .",
    "build": "vuepress build ."
  },

这样我们就完成了vuepress的下载

2. 创建分支并配置github page

现在，我们要完成将本地的vuepress push到github并创建分支，设置好对应的github page source

首先在github new一个仓库，如果你所要的page是你的个人blog，那么创建的仓库名称请以username.github.io的方式命名，其中username是你的github账号名称，大小写请注意。

然后创建一个分支gh-pages，source选择main即可，用于装载blog的静态页面。

接下来，我们借助工具将本地的vuepress push到指定的main分支中，可以用github desktop，也可以使用其他工具，git命令：

git init
git checkout -b docs
git remote add origin https://github.com/username/username.github.io.git

（username记得替换）

然后我们来到仓库settings --> pages，在Build and deployment下的source选择deploy from a branch，选择gh-pages，根据自己的项目选择根位置，我这里使用的是/root，点击save保存。

这样我们就完成了page的配置。

3. 配置自动化

现在，我们就需要创建github的自动化工作流来实现push就推送的功能。

来到vuepress项目的根目录下，创建.github/workflows，并在里面创建deploy.yml文件：

name: Deploy to GitHub Pages

on:
  push: # 每次push就会触发workflows
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write # 修改为 write 权限
      pages: write
      id-token: write

    steps:
      - name: 🚀 Checkout 源码
        uses: actions/checkout@v4

      - name: 🧱 设置 Node.js 环境
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: 📦 安装依赖
        run: npm install

      - name: 🔧 构建项目
        run: npm run build # 注意查看package.json确认命令是否正确

      - name: 🚀 部署到 GitHub Pages
        uses: peaceiris/actions-gh-pages@v3 # 如果你是推送到其他仓库请修改！
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .vuepress/dist # 注意检查位置是否正确
          commit_message: 'Deploy to GitHub Pages'
          publish_branch: gh-pages  # 可选，默认就是 gh-pages，可以省略

完成配置后push到github，等待action完成部署即可。

你也可以在仓库页面查看运行情况，action会根据你所设置的step一步一步完成构建，如若失败也可以看到失败原因。

现在我们就完成了blog的搭建了！效果：SaltFishGC`s Blogopen in new window

如果对这个页面效果比较满意，你也可以直接fork我的项目，在此基础上继续开发！

出现问题

为毛我已经把vuepress的项目push到github上面了，github page也配置好main做page的source了，跳转就是404呢？

因为github page最终要的是vue而不是vuepress，vuepress是生成vue的脚手架，在使用vuepress执行命令npm run build后，在.vuepress/dist文件夹里面的才是我们要的blog页面，你需要将这个vue给push到你的github仓库里面才能够发布出来。并且这个vue所在的仓库的github page才是最终看得到的静态web！（当然你放另一个分支里，然后在github的setting --> page里面指定好对应的分支也是完全没问题的）

如果是做额外的分支来存储vue的，记得把分支里面清空了再push进去/执行自动化sh文件。

github page要选Action吗？

这里我没用，因为我是把vue放到另一个分支的，如果是vuepress大概不需要，和ai一起在.github/workflows/下写个sh脚本即可，如果是hugo之类的可以试试（=。=）

private不行吗？

假如是分开两个仓库，一个vuepress推送vue到另一个仓库的话，作为vue的仓库一定要public（当然不public也开不了page）我是将两个全放一个仓库里面了，所以必须public