Hexo+GitHub搭建個人部落格
- 2022 年 8 月 20 日
- 筆記
- github actions, Hexo
操作環境：Windows10、Node、Git、ssh
前置準備:
<username>github.io倉庫已建立，預計託管部落格網址為<username>github.io/blog
先對hexo有個清晰的認識，不至於稀里糊塗的跟著步驟走。
1、Hexo發布部落格流程概覽
-
搭建hexo環境
-
hexo new "title"(創建新文章) -
編寫md文檔
-
hexo clean
- 清除快取文件 (db.json) 和已生成的靜態文件 (public)
-
hexo generate(生成靜態文件) -
hexo deploy(Hexo 會將 public 目錄中的文件和目錄推送至_config.yml中指定的遠端倉庫和分支中，並且完全覆蓋該分支下的已有內容。) -
本地倉庫同步到GitHub (不同步的話，文章源碼只會保留在本地，不易管理)
由於 Hexo 的部署默認使用分支 master，所以如果你同時正在使用 Git 管理你的站點目錄，你應當注意你的部署分支應當不同於寫作分支。
Hexo 在部署你的站點生成的文件時並不會更新你的站點目錄。因此你應該手動提交並推送你的寫作分支。
一般來說第一步環境搭建只需要在最開始創建部落格網站的時候進行，寫文的話只需要重複第2-7步就可以了，這種使用方式強烈依賴於本地環境。但是，有時候我們並不只是固定在一台電腦上寫文，（比如：一直寫文的電腦壞了，需要換新電腦；電腦重裝系統等等）這樣就需要在另一台電腦上搭建環境，這樣非常的麻煩，而且難免會帶來一些其它依賴版本兼容問題。所以，可以採用GitHub Actions持續集成平台來簡化發布文章的流程。
簡化後的流程如下：
-
hexo new "title"(創建新文章) -
編寫md文檔
-
本地倉庫同步到GitHub
- push到GitHub上之後，
GitHub Actions會監聽分支文件變動，觸發發布流程（跟Jenkins 構建流程類似）
下文整體分為兩個步驟：
-
藉助
GitHub Pages手動部署。 -
增加
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分支
-
新建倉庫：
blog（名字自己起） -
本地hexo倉庫關聯遠程GitHub倉庫
將本地倉庫推送到遠端 -
本地倉庫一些必要的修改配置
//github.com/hexojs/hexo-deployer-git
- 修改
_config.yml配置，如下：
url: //all-smile.github.io/blog
root: /blog/
# ...
deploy:
type: 'git'
repo: [email protected]:all-smile/blog.git
branch: gh-pages
- 提交到遠程倉庫
- 創建
gh-pages分支
hexo結合GitHub創建個人網站指定的分支名，hexo 內默認設置的分支也是叫這個名字
git checkout -b gh-pages
git push -u origin gh-pages
- 遠程倉庫開啟 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版本號
# 快取依賴項: //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 //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: [email protected]
# 獲取提交文章源碼時的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: //hexo.io/docs/one-command-deployment
deploy:
type: 'git'
repo: [email protected]: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 倉庫上設置的一樣 -
公私鑰是否匹配，如果不匹配，則重新生成添加即可
👉👉 如果還有其它問題也可以看一下這裡，應該會有幫助的😊
🎈🎈🎈
🌹 持續更文，關注我，你會發現一個踏實努力的寶藏前端😊，讓我們一起學習，共同成長吧。
🎉 喜歡的小夥伴記得點贊關注收藏喲，回看不迷路 😉
🎁 歡迎大家評論交流, 蟹蟹😊
