GitHub Actions 自動部署前端 Vue 項目

一. 概述

作爲前端技術人員，如果要部署一個項目大體要經過：代碼開發、代碼推送、打包dist文件、scp到服務器、服務器nginx配置、完成部署這幾個流程，現實中我們希望項目部署儘可能自動且簡單，因此誕生了各種CI/CD工具，比如：Jenkins、gitlab ci、gitlab runner等，其實我們最熟悉的 GitHub 也提供了CI/CD 的能力：GitHub Actions,它於2019年11月正式發佈，現已經支持多種的語言和框架：Node.js, Python, Java, PHP, Ruby, Go, Rust, C/C++, .NET, Android, iOS.當然在利用GitHub Actions自動部署項目之前，先要利用GitHub Pages來發布我們的前端項目。

二. GitHub Pages

什麼是 GitHub Pages？官網的介紹：Websites for you and your projects.Hosted directly from your GitHub repository. Just edit, push, and your changes are live. 說的很明確了，可以利用它,將我們託管在 GitHub 倉庫的項目部署爲一個可以對外訪問的網站，免去了我們自己購買與配置服務器的麻煩。

• 首先創建一個項目，以Vue項目爲例，利用 Vue 腳手架創建一個項目

npm init vue@latest

這裏假設你已經熟悉了 Vue 項目創建，如果不熟悉Vue可以去查看
執行如下命令：

> cd <your-project-name>
> npm install
> npm run dev

運行後在瀏覽器中打開本地地址，得到如下頁面：

• 在GitHub上創建一個新的Repository,將項目上傳到GitHub倉庫

git init
git add .
git commit -m "備註信息"
git remote add origin 你的遠程倉庫地址
git push -u origin master

• 配置 GitHub Actions
  回到GitHub,點擊Setting->Pages，看到如下界面
  
  
  並沒有展示網址，別急！此時還需要我們去新建一個名爲gh-pages的分支，創建完成後再次打開Pages，可以看到頁面發生了變化
  

Source: 選擇Deploy from a branch, Branch：github pages 默認只能識別項目根目錄的 index 文件，我們這裏選擇新建的gh-pages的root根目錄，意思是去這個分支的根目錄加載index.html文件.

• 打包應用，併發布到 gh-pages 分支
  打包應用，執行npm run build ，在項目根目錄下得到打包後的產物dist文件夾,
  

  切換當前分支到gh-pages,並且將原有內容全部刪除, 最後將dist文件夾下的內容全部拷貝到gh-pages上，push到遠端.
  

  
  再次點擊Setting->Pages ,稍等一會兒，下面出現了一個網址,這就是項目線上地址
  

• 遇到問題
  點擊查看網址，並沒有像我們預期的那樣展示頁面，而是一片空白。打開調試版查看錯誤信息：
  

  
  如果有項目部署經驗的一看就知道是怎麼回事了，這是打包編譯後的文件路徑配置有問題，資源文件css、js，加載的路徑地址不對，加載的是根路徑
  https://<用戶名>.github.io/assets/index.bf782a5b.js,而我們的資源文件在/vue-pages/目錄下，所以當然報錯404，修復也很簡單，如果你的Vue項目是基於 Vite 的構建的，需要修改vite.config.js，添加base:'./'

export default defineConfig({
  plugins: [vue(), vueJsx()],
  base:'./',// 將根路徑換成相對路徑
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
})

如果是基於webpack構建，修改vue.config.js添加publicPath: './'.

module.exports = {
  /**
   * publicPath 默認是 / 是根路徑，這個是指服務的根路徑：https://xxx.github.io/，發佈後會從這個路徑下找 js.css 等資源，而生成的網站路徑是這個 https://xxx.github.io/Vue-Element/，顯然是找不到的
   * 我們需要修改爲 相對路徑'./' 或是‘.’ 或是 直接設置的項目子路徑 :/項目名稱/ 就可找到資源了
   */
  publicPath: './',
  outputDir: 'dist', // dist
  assetsDir: 'static',
  lintOnSave: process.env.NODE_ENV === 'development',
  productionSourceMap: false,
...

重新打包，將dist文件夾下內容拷貝到gh-pages分支下，並重新打開pages鏈接：https://<用戶名>.github.io/vue-pages/
成功部署！

每一次修改後都要重新打包，切換分支拷貝dist文件夾，實屬麻煩，能不能讓GitHub自動檢測push動作,自動進行打包部署嗎？那就是GitHub Actions的工作了.

三. GitHub Actions

什麼是GitHub Actions?

GitHub Actions是GitHub推出的一款持續集成（CI/CD）服務，它給我們提供了虛擬的服務器資源，讓我們可以基於它完成自動化測試、集成、部署等操作。這裏簡單介紹一下它的幾個基本概念，更多內容可以去官網查看

基本概念

• Workflows（工作流程）
  持續集成的運行過程稱爲一次工作流程，也就是我們項目開始自動化部署到部署結束的這一段過程可以稱爲工作流程.

• job （任務）
  一個工作流程中包含多個任務，簡單來說就是一次自動部署的過程需要完成一個或多個任務.

• step（步驟）
  部署項目需要按照一個一個的步驟來進行，每個job由多個step構成.

• action（動作）
  每個步驟step可以包含一個或多個動作，比如我們在一個步驟中執行打包命令這個Action.

語法簡介

• name
  name字段是workflow的名稱。如果省略該字段，默認爲當前workflow的文件名.

name: GitHub CI

• on
  on字段指定觸發workflow的條件，通常是某些事件,比如代碼推送push,拉取pull_request,可以是事件的數組.

on: push
or
on: [push, pull_request]

指定觸發事件時，可以限定分支或標籤:

on:
  push:
    branches:    
      - master

上面代碼表示：只有master分支發生push事件時，纔會觸發workflow.

• jobs
  workflow的核心就是jobs，任務job放在jobs這個集合下，每一個job都有job_id，用job_id標識一個具體任務
• jobs.<job_id>.name
  任務說明

jobs:
  my_first_job: // job_id
    name: My first job 
  my_second_job:// job_id
    name: My second job

上面的jobs字段包含兩項任務，job_id分別是my_first_job和my_second_job。

• jobs.<job_id>.runs-on
runs-on字段指定運行所需要的虛擬機環境,它是必填字段。

runs-on: ubuntu-18.04

GitHub Actions給我們提提供的運行環境主要有以下幾種：
ubuntu-latest，ubuntu-18.04或ubuntu-16.04
windows-latest，windows-2019或windows-2016
macOS-latest或macOS-10.14

• jobs.<job_id>.steps
  任務步驟，一個job可以包含多個步驟，我們需要分爲多個步驟來完成這個任務，每個步驟包含下面三個字段：

jobs.<job_id>.steps.name：步驟名稱。
jobs.<job_id>.steps.run：該步驟運行的命令或者 action。
jobs.<job_id>.steps.env：該步驟所需的環境變量。

使用介紹

• 新建.yml文件
  點擊主頁Actions -> New workflow -> set up a workflow yourself，當然你也可以選擇一個模板，點擊start commit則會自動在我們項目目錄下新建.github/workflows/main.yml文件.
  

整個workflow的核心就是yml腳本的書寫。如果你需要某個action，不必自己寫複雜的腳本，直接引用他人寫好的 action即可，整個持續集成過程，就變成了一個actions的組合，你可以在GitHub的官方市場，可以搜索到他人提交的actions. 下面是我們要自動發佈GitHub pages所寫的腳本：

name: CI Github Pages
on:
  #監聽push操作
  push:
    branches:
      - main # 這裏只配置了main分支，所以只有推送main分支纔會觸發以下任務
jobs:
  # 任務ID
  build-and-deploy:
    # 運行環境
    runs-on: ubuntu-latest
    # 步驟
    steps:
      # 官方action，將代碼拉取到虛擬機
      - name: Checkout  ️ 
        uses: actions/checkout@v3

      - name: Install and Build   # 安裝依賴、打包，如果提前已打包好無需這一步
        run: |
          npm install
          npm run build

      - name: Deploy   # 部署
        uses: JamesIves/[email protected]
        with:
          branch: gh-pages # 部署後提交到那個分支
          folder: dist # 這裏填打包好的目錄名稱

上面整個workflow的說明：

• 只有當main分支有新的push推送時候纔會執行整個workflow.
• 整個workflow只有一個job,job_id是build-and-deploy,name被省略.
• job 有三個step： 第一步是Checkout,獲取源碼，使用的action是GitHub官方的actions/checkout.
• 第二步：Install and Build,執行了兩條命令：npm install,npm run build,分別安裝依賴與打包應用.
• 第三步：Deploy 部署，使用的第三方action：JamesIves/[email protected],它有兩個參數：分別是branch、folder，更多關於這個action的詳情可以去查看.

當點擊Start commit，GitHub Actions 會自動運行workflow. 修改工程文字歡迎文字：

<HelloWorld msg="You did it!" />

改爲:

<HelloWorld msg="GitHub Actions CI Succeed!" />

push可以點擊Actions查看工作流的運行情況

當這個黃色加載動畫變成綠色後表示workflow運行完成，看下最終效果：

達到了自動部署的目的.

四. 設置Custom domain

其實經過上面的三步已經可以實現自動部署的目的了，但是還是有點瑕疵。我們部署後的項目地址是：https://<用戶名>.github.io/vue-pages/,域名還是GitHub的,能不能改成我們自己的專屬域名呢？比如改成http://<用戶名>.com/,那就需要設置Custom domain了。

1. 購買域名

如果想將項目地址改成自己的專屬域名，首先需要你去購買一個域名，目前阿里雲,騰訊雲都支持域名的購買，搜索自己喜歡的域名直接付款就好了。

2. 購買域名後，還需要我們進行實名認證以及備案，按照平臺的提示進行操作就好了，這裏不再涉及.

3. 進行DNS解析配置

這裏以阿里云爲例，打開域名解析控制檯，點擊解析按鈕

點擊添加記錄按鈕，將下面兩種類型的記錄值添加上，記錄類型是：CNAME，記錄值就是你GitHub的主域名.

4. 設置Custom domain

返回到項目的GitHub pages設置頁面，將我們購買的域名添加在Custom domain中，點擊save，可以看到pages的地址變成了我們自己的域名，訪問它就會看到你的網站了.

五. 小結

GitHub Actions給我們提供了一站式的自動化部署體驗，加上Custom domain的設置，完全可以用於搭建我們的個人博客，最重要的是這完全免費. 你也可以用它來部署其他框架的項目，當然這裏的重點是的yml腳本的書寫.

一些參考：

https://pages.github.com

https://github.com/features/actions

https://blog.csdn.net/formula10000/article/details/98946098