【筆記】利用 Github Actions 將 node 專案自動部署至 Ubuntu 伺服器

GitHub Actions

前言

將程式碼 push 到 GitHub，同時自動部署到伺服器上，是再方便不過的事。一直仗著 SPA 部署簡單而不肯學習自動部署的我，在面對最近開發的 Next.js 專案繁瑣的部署流程，決定好好研究 GitHub Actions，並將過程筆記下來與大家分享。

一、準備 SSH Key

在你的 Ubuntu 伺服器上生成 SSH Key pair（如果有生成過可忽略此步驟）：

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

這會生成一對公鑰和私鑰（通常是 ~/.ssh/id_rsa.pub 和 ~/.ssh/id_rsa）。

將公鑰新增到伺服器的 ~/.ssh/authorized_keys 中：

cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

二、設定 GitHub Actions 工作流程

在你的專案中創建一個工作流程檔案（例如 .github/workflows/deploy.yml）：

name: Deploy to Ubuntu Server

on:
  push:
    branches:
      - main  # 或你希望觸發部署的分支

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v2

    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '20'  # 根據需要選擇 Node.js 版本

    - name: Install dependencies
      run: npm install

    - name: Build project
      run: npm run build

    - name: Deploy to server
      uses: appleboy/ssh-action@v0.1.7
      with:
        host: ${{ secrets.SERVER_HOST }}
        username: ${{ secrets.SERVER_USERNAME }}
        key: ${{ secrets.SSH_PRIVATE_KEY }}
				port: ${{ secrets.SERVER_PORT }}
        script: |
          echo "Connected to server"
          cd /your/project/path
          git pull origin main
          npm install
          npm run build
          npm run start

三、新增 GitHub Secrets

進入你的 GitHub 專案。
點擊 “Settings”。
點擊 “Secrets and variables” > “Actions”。
點擊 “New repository secret”，新增以下 Secrets：
- SERVER_HOST：你的伺服器 IP 或域名。
- SERVER_USERNAME：你的伺服器用戶名。
- SSH_PRIVATE_KEY：步驟 1 的 Ubuntu 伺服器私鑰內容（~/.ssh/id_rsa）。
- SERVER_PORT：你的伺服器 SSH 進入 PORT 號。預設是 22。

這樣，每當你將程式碼 push 到 GitHub 的 main 分支時，GitHub Actions 就會自動執行工作流程，將程式碼部署到你的 Ubuntu 伺服器。

注意，在 job name Deploy to server 之前的內容都是在 GitHub Actions 的環境上執行，目的是為了確保程式碼能在目標環境上正確運行；在這之後則是利用 SSH 工具 appleboy/ssh-action@v0.1.7 來連上你的伺服器，而 script 就是你在你的伺服器上要運行 node 應用的指令。

我自己實際執行的 script

echo "Connected to server"
source ~/.zshrc  # 環境變數都是設在 zshrc 上，所以要確保現在是使用 zsh shell 否則會出錯
nvm use v20  # 透過 nvm 工具切換成這個 node 應用要使用的 node 版本
node -v
pm2 --version
cd /your/project/path
git pull origin main
npm install
npm run build
pm2 restart your-project-name  # 透過 pm2 啟用 node 應用

我自己遇到的問題

在 Deploy to server 階段出現 SyntaxError: Unexpected token ? 的錯誤。
- 原因：伺服器上的 node 版本與你的 node 專案版本不一致；或是 shell 找不到指令（例如找不到 nvm 和 pm2）。
- 解法：使用 nvm 來切換對應的 node 版本，並確保 shell 有設定好各指令的環境變數，以我個人為例，我平常是使用 zsh，但顯然 GitHub Actions 不是使用 zsh 操作，所以我在 scirpt 一開始加了 source ~/.zshrc 以確保 GitHub Actions 是使用 zsh 執行我後續的指令。
伺服器上原本運行的 node 專案沒有用 Git，沒辦法 git pull。
- 原因：因為之前我都是手動上傳檔案到伺服器上，所以當然沒有 Git……。
- 解法：我們已經要用 GitHub Actions 了，所以就大膽刪除伺服器上的專案，使用 Git 來建立專案。以下簡單說明如何在 Ubuntu 伺服器上建立 Git 專案。

在 Ubuntu 伺服器上建立 Git 專案

由於你的伺服器需要連線到你的 GitHub 專案，所以需要將你伺服器的公鑰加到你的 GitHub 帳號上。

執行 cat ~/.ssh/id_rsa.pub 並將內容複製。
登入你的 GitHub 帳號。
點擊 “Settings” > “SSH and GPG keys”。
點擊 “New SSH key”。
將公鑰貼上到文字框中，新增一個有意義的標題，點選 “Add SSH key”。

接下來就可以回到你的伺服器上初始化 git 專案囉。

cd /your/project/path
git init
git remote add origin <your-repository-url>
git pull origin main

結語

GitHub Actions 沒有想像中的難，實作後深深感謝 GitHub 有提供這種免費的服務（公開專案免費，非公開專案有限額），讓個人小專案也可以輕鬆實現部署自動化。

JS Ying's Blog