Hexo+GitHub搭建博客，实现云端编辑、一键发布

操作环境：Windows10、Node、Git、ssh

前置准备: <username>github.io 仓库已建立，预计托管博客网址为<username>github.io/blog

先对hexo有个清晰的认识，不至于稀里糊涂的跟着步骤走。

1、Hexo发布博客流程概览

1. 搭建hexo环境
2. hexo new "title" (创建新文章)
3. 编写md文档
4. hexo clean

• 清除缓存文件 (db.json) 和已生成的静态文件 (public)

5. hexo generate (生成静态文件)
6. hexo deploy (Hexo 会将 public 目录中的文件和目录推送至 _config.yml 中指定的远端仓库和分支中，并且完全覆盖该分支下的已有内容。)
7. 本地仓库同步到GitHub (不同步的话，文章源码只会保留在本地，不易管理)

由于 Hexo 的部署默认使用分支 master，所以如果你同时正在使用 Git 管理你的站点目录，你应当注意你的部署分支应当不同于写作分支。

Hexo 在部署你的站点生成的文件时并不会更新你的站点目录。因此你应该手动提交并推送你的写作分支。

一般来说第一步环境搭建只需要在最开始创建博客网站的时候进行，写文的话只需要重复第2-7步就可以了，这种使用方式强烈依赖于本地环境。但是，有时候我们并不只是固定在一台电脑上写文，（比如：一直写文的电脑坏了，需要换新电脑；电脑重装系统等等）这样就需要在另一台电脑上搭建环境，这样非常的麻烦，而且难免会带来一些其它依赖版本兼容问题。所以，可以采用GitHub Actions持续集成平台来简化发布文章的流程。

简化后的流程如下：

1. hexo new "title" (创建新文章)
2. 编写md文档
3. 本地仓库同步到GitHub
4. push到GitHub上之后，GitHub Actions会监听分支文件变动，触发发布流程（跟Jenkins 构建流程类似）

下文整体分为两个步骤：

1. 借助GitHub Pages手动部署。
2. 增加GitHub Actions配置，完成自动部署

2、Hexo 搭建博客

Hexo 是一个快速、简洁且高效的博客框架。Hexo 使用 Markdown（或其他渲染引擎）解析文章，在几秒内，即可利用靓丽的主题生成静态网页。

文档

npm install -g hexo-cli
cd [workspace]
hexo init <folder:blog>
cd <folder:blog>
npm install
hexo s

网站基础配置修改参考这里

3、GitHub 托管 Hexo 博客

可以采取分支管理的方式，也可以新建repo，在ci配置上略有不同，这里我采用的是将hexo博客源码托管到独立的repo上，将 Hexo 项目编译生成静态页面，部署到 gh-pages 分支

1. 新建仓库：blog （名字自己起）
2. 本地hexo仓库关联远程GitHub仓库
   将本地仓库推送到远端
3. 本地仓库一些必要的修改配置

4. 安装 hexo-deployer-git。

   https://github.com/hexojs/hexo-deployer-git

• 修改_config.yml配置，如下：

  url: https://all-smile.github.io/blog
  root: /blog/
  
  # ...
  
  deploy:
  type: 'git'
  repo: [e-mail]:all-smile/blog.git
  branch: gh-pages

• 提交到远程仓库

3. 创建 gh-pages 分支

hexo结合GitHub创建个人网站指定的分支名，hexo 内默认设置的分支也是叫这个名字

git checkout -b gh-pages
git push -u origin gh-pages

4. 远程仓库开启 github pages

指定部署分支：gh-pages

4、手动部署

本地项目执行命令：

hexo clean
hexo g
hexo deploy

hexo模板引擎生成静态文件，并推送到gh-pages分支下（替换原先分支下的所有文件）

到这里就已经完成了博客的搭建

需要注意的是：hexo deploy 命令并不会帮助我们同步本地的修改到远程仓库，所以当在本地写完博文之后，要做两件事：一是发布站点，二是同步远程仓库，这样做比较麻烦，下面会讲解如何配置持续集成

4.1、查看效果

这里我配置了自定义域名

5、自动部署

就是DevOps，可以理解成 GitHub 通过一些流水线的配置（CI/CD），然后在本地推送代码的时候触发流水线执行，自动部署站点。

由于 GitHub Actions 也可以实现CI/CD，travis-ci 的市场被挤压了，所以他们改变了运营策略，变成收费使用了！我们换用 GitHub Actions

GitHub Actions 是开源持续集成构建项目，用来持续集成托管在GitHub上的代码，使用起来也非常的简单方便。

使用 GitHub Actions 后，可以将前面部署的步骤自动化，我们只需要将本地修改的文件推送到 github 仓库，GitHub Actions 检测到 master 分支代码有变动，会自动执行脚本命令，将 Hexo 项目编译生成静态页面，部署到 gh-pages 分支，very good！

6、GitHub Actions

GitHub Actions文档请点击这里

使用Github Action来部署hexo，这样电脑本地就不需要安装npm相关的东西了。另外利用github.dev也可以实现在页面上编辑了。

在线编辑:
Github有提供一个在线编辑的页面，在Repo页面按下按键.就可以打开编辑页面了

每个 action 就是一个独立脚本，因此可以做成代码仓库，使用userName/repoName的语法引用 action。比如，actions/setup-node就表示github.com/actions/setup-node这个仓库，它代表一个 action，作用是安装 Node.js。事实上，GitHub 官方的 actions 都放在 github.com/actions 里面。

6.1、支持的令牌

支持三个令牌。

令牌	私人仓库	公开仓库	协议	设置
github_token	✅️	✅️	HTTPS	不必要
deploy_key	✅️	✅️	SSH	必要的
personal_token	✅️	✅️	HTTPS	必要的

注意：GITHUB_TOKEN不是个人访问令牌，GitHub Actions 运行器会自动创建一个GITHUB_TOKEN密钥以在您的工作流程中进行身份验证。因此，您无需任何配置即可立即开始部署

6.2、支持的平台

所有 Actions 运行器：支持 Linux (Ubuntu)、macOS 和 Windows。

环境	github_token	deploy_key	personal_token
ubuntu-20.04	✅️	✅️	✅️
ubuntu-18.04	✅️	✅️	✅️
macos-最新	✅️	✅️	✅️
windows-最新	✅️	(2)	✅️

7、为Hexo配置GitHub Actions

具体步骤：

7.1、设置 SSH 私钥 deploy_key

创建 SSH 部署密钥，使用以下命令生成部署密钥。

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""

您将获得 2 个文件：

• gh-pages.pub是公钥
• gh-pages是私钥

接下来，转到博客源码存储库设置

• 转到Deploy Keys并使用Allow write access添加您的公钥 gh-pages.pub，name写为public key of ACTIONS_DEPLOY_KEY，指定用途，方便后面维护

• 转到Actions secrets并将您的私钥 gh-pages 添加为 ACTIONS_DEPLOY_KEY（这个名称在yml文件中需要使用）

7.2、新建 .github/workflows/pages.yml 文件

yml文件通过缩进（空格，不是tab）来表示层级关系。

yaml不会的，可以去看一下这里，了解一下语法即可。

以下文件是我个人的配置的一部分，不建议直接使用

name: Pages

# 触发器、分支
on:
  push:
    branches:
      - master  # default branch
jobs:
  # 子任务
  pages:
    runs-on: ubuntu-latest # 定运行所需要的虚拟机环境
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v2
        # with:
        #   submodules: true
        #   fetch-depth: 0
      # 每个name表示一个步骤:step
      - name: Use Node.js 16.x
        uses: actions/setup-node@v2
        with:
          node-version: '16.14.1' # 自己正在使用的node版本即可
      # - run: node -v # 查看node版本号
      # 缓存依赖项: https://docs.github.com/cn/actions/using-workflows/caching-dependencies-to-speed-up-workflows
      - name: Cache NPM dependencies
        uses: actions/cache@v2
        with:
          # npm cache files are stored in `~/.npm` on Linux/macOS
          path: ~/.npm
          # path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      # 查看路径 : /home/runner/work/blog/blog
      # - name: Look Path
      #   run: pwd
      # 查看文件
      - name: Look Dir List
        run: tree -L 3 -a
      # 第一次或者依赖发生变化的时候执行 Install Dependencies，其它构建的时候不需要这一步
      - name: Install Dependencies
        run: npm install
      - name: Look Dir List
        run: tree -L 3 -a
      # - name: clean theme cache
      #   run: git rm -f --cached themes/tenacity
        # run: git submodule deinit themes/tenacity && git rm themes/tenacity
      # 安装主题
      - name: Install Theme
        run: git submodule add https://github.com/all-smile/tenacity.git themes/tenacity
      - name: Clean
        run: npm run clean
      - name: Build
        run: npm run build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY  }}
          user_name: xiao
          user_email: [e-mail]
          # 获取提交文章源码时的commit message，作为发布gh-pages分支的信息
          commit_message: ${{ github.event.head_commit.message }}
          full_commit_message: ${{ github.event.head_commit.message }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # GITHUB_TOKEN不是个人访问令牌，GitHub Actions 运行器会自动创建一个GITHUB_TOKEN密钥以在您的工作流程中进行身份验证。因此，您无需任何配置即可立即开始部​​署
          publish_dir: ./public
          allow_empty_commit: true # 允许空提交
      # Use the output from the `deploy` step(use for test action)
      - name: Get the output
        run: |
          echo "${{ steps.deploy.outputs.notify }}"

7.3、修改 _config.yml 文件中的Deploy配置

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: 'git'
  repo: [e-mail]:all-smile/blog.git
  branch: gh-pages
  # 默认提交信息： Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}
  message: ${{ github.event.head_commit.message }} # 直接将提交消息传输到 GitHub Pages 存储库

发布效果

本地仓库直接push，触发 GitHub Actions 自动构建发布

Hexo主题

请查看文档 ，自行安装配置

8、GitHub Actions问题解决

8.1、非法输入值

在 pages.yml 文件的 Deploy 步骤下，发布的时候需要一些参数配置，这些参数名是指定好的，不可以随便写，比如 commit_msg应该使用 commit_message

commit_message: ${{ github.event.head_commit.message }}

Warning: Unexpected input(s) 'commit_msg', valid inputs are ['deploy_key', 'github_token', 'personal_token', 'publish_branch', 'publish_dir', 'destination_dir', 'external_repository', 'allow_empty_commit', 'keep_files', 'force_orphan', 'user_name', 'user_email', 'commit_message', 'full_commit_message', 'tag_name', 'tag_message', 'enable_jekyll', 'disable_nojekyll', 'cname', 'exclude_assets']

8.2、The process '/usr/bin/git' failed with exit code 128

这个问题大概率是 GITHUB_TOKEN 造成的，参考配置文档

GITHUB_TOKEN 是一种 GitHub 应用程序安装访问令牌。 可以使用安装访问令牌代表仓库中安装的 GitHub 应用程序进行身份验证。令牌的权限仅限于包含您的工作流程的仓库。

解决：

• 查看 yml 文件中的名字是否写错

github_token: ${{ secrets.GITHUB_TOKEN }}

• 在 仓库 Settings/Actions/general 下，修改 GITHUB_TOKEN 的权限

8.3、deploy key问题

ERROR: Permission to all-smile/blog.git denied to deploy key
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

解决：

• 查看 pages.yml 中引用的变量名称是否跟 GitHub 仓库上设置的一样
• 公私钥是否匹配，如果不匹配，则重新生成添加即可

👉👉 如果还有其它问题也可以看一下这里，应该会有帮助的😊

最后

• 本地写文只需要在写完之后push到远程仓库即可发布
• 其它电脑本地使用，有git就可以了，直接拉取远程仓库源码，在本地创建文件、编辑、推送远端，即可发布
• 也可以用github.dev在线创建、编辑、发文

---

🎈🎈🎈

🌹 持续更文，关注我，你会发现一个踏实努力的宝藏前端😊，让我们一起学习，共同成长吧。

🎉 喜欢的小伙伴记得点赞关注收藏哟，回看不迷路 😉

🎁 欢迎大家评论交流, 蟹蟹😊