第21天 - 部署 Github 個人檔案專案到 Github Pages - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2025 iThome 鐵人賽

DAY 22

Vue.js

作為 Angular 專家探索 Vue 3 和 Svelte 5系列第 22 篇

第21天 - 部署 Github 個人檔案專案到 Github Pages

17th鐵人賽 svelte5 vue3 angular

connieleung

2025-09-06 06:23:55

150 瀏覽

分享至

在第21天，我會將所有的示範部署到 Github Pages，因為 Github Pages 是免費的，且可以透過 Github Actions 自動化處理。

當 Angular 應用程式不包含敏感的環境變數（例如密鑰）時，使用 ng deploy 比透過 Github Actions 更方便。當應用程式包含敏感環境變數時，我只能透過 Github Actions 在建置 Angular 應用程式時使用這些密鑰。

GitHub Actions 部署到 GitHub Pages

Vue 3 application

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'

// https://vite.dev/config/
export default defineConfig({
  base: '/vue-github-profile/',
  plugins: [
    vue(),
    vueDevTools(),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    },
  },
})

建置應用程式

在 vite.config.ts 中，於 defineConfig 函式的物件 (object) 添加新的 base 屬性。在本機環境中，URL 是 http://localhost:4173/vue-github-profile/。否則，URL 是 https://railsstudent.github.io/vue-github-profile/。

打開終端機 (terminal) 並執行 npm run build，將應用程式建置到 dist/ 目錄。接著執行 npm run preview，即可在 http://localhost:4173/vue-github-profile 預覽並測試應用程式。

由 Github Actions 部署到 Github Pages

建立 .github/workflows/main.yml，用以執行建置與部署到 Github Pages 所需的命令。

應用程式需要使用 VITE_GITHUB_TOKEN 環境變數，必須在建置步驟中提供此變數。

接著，使用命令 touch 建立空白的 .nojekyll 檔案。

將 index.html 複製為 404.html，當使用者存取不存在的資源時，瀏覽器會呈現 404.html。建置應用程式

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main # or your default branch
  workflow_dispatch:  # Also allow manual trigger

permissions:
  id-token: write
  contents: read # You might also need other permissions like contents: read
  pages: write # If deploying to GitHub Pages

jobs:
  build-and-deploy:
    environment: 
      name: github-pages   # Specify the deployment environment here
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js (if needed for static site generator)
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Build site (example for a static site generator)
        env:
          VITE_GITHUB_TOKEN: ${{ secrets.VITE_GITHUB_TOKEN }}
        run: npm run build # or your build command

      - name: Add .nojekyll file
        run: touch dist/.nojekyll

      - name: Add 404.html file
        run: cp dist/index.html dist/404.html

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v3

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist # or the path to your built site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

提交 yaml 檔案到 main 分支以自動化部署流程。

這時候應該會失敗，因為尚未建立 secrets.VITE_GITHUB_TOKEN。
前往 https://github.com/<repo users>/<repo name>/settings/environment，確認已建立 github-pages 環境。點擊該環境名稱，確認部署分支和標籤。確保加入 main 並且只有此分支可部署到 Github Pages。

在 Environment secrets 中，點擊 Add environment secret 按鈕新增 VITE_GITHUB_TOKEN 變數。

對程式碼進行修改，提交變更檔案以觸發新的工作流程開始重新部署。
接著前往 https://github.com/<repo users>/<repo name>/settings/pages，選擇 Github Action 為 Build and deployment 的來源。

點擊現況網站的連結，確認網站已成功上線與運作。

SvelteKit application

Install new dev dependencies

npm i --sav-exact --save-dev @sveltejs/adapter-static

import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
	// Consult https://svelte.dev/docs/kit/integrations
	// for more information about preprocessors
	preprocess: vitePreprocess(),

	kit: {
	     adapter: adapter({
			fallback: '404.html'
		}),
		paths: {
			base: '/svelte-github-profile'
		}
	}
};

export default config;

修改 svelte.config.ts，從 @sveltejs/adapter-static 匯入適配器（adapter）。

更新適配器設定並在 kit 屬性中新增 paths 設定。

kit: { 
    adapter: adapter({
	    fallback: '404.html'
    }),
    paths: {
	    base: '/svelte-github-profile'
    }
}

建立一個 .github/workflows/main.yml 以執行建置檔案及部署到 Github Pages 所需的命令

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main # or your default branch
  workflow_dispatch:  # Also allow manual trigger

permissions:
  id-token: write
  contents: read # You might also need other permissions like contents: read
  pages: write # If deploying to GitHub Pages

jobs:
  build-and-deploy:
    environment: 
      name: github-pages   # Specify the deployment environment here
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js (if needed for static site generator)
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Build site (example for a static site generator)
        env:
          VITE_GITHUB_TOKEN: ${{ secrets.VITE_GITHUB_TOKEN }}
        run: npm run build # or your build command

      - name: Add .nojekyll file
        run: touch build/.nojekyll

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v3

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist # or the path to your built site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

main.yml 與其他類似，不同的是 Svelte 會自動建立 404.html，而且 Svelte 將 JavaScript 檔案編譯和複製到 build 資料夾。

將 yaml 檔案提交（commit）到 main 分支，以自動化部署流程。

確認儲存庫中的設定相同，線上網站應該能成功運行。

Angular 20 application

我使用 Github Actions 取代 ng deploy，因為 ng deploy 僅接受配置 (configuration，例如 development 或production)。然而，我無法將 Github personal access token 加入到 angular.json 並將該檔案提交到 Github public repository。

更新 angular.json 配置

"outputPath": {
  "base": "dist",
  "browser": ""
}

在 architect -> build -> options 下新增 outputPath，使得 npm run build 會將 JavaScript 檔案編譯到 dist/。

使用 Github Actions 部署到 Github Pages

建立一個 .github/workflows/main.yml 來執行必要的指令，以建置檔案並部署至 Github Pages。

"scripts": {
    "ng": "ng",
    "build": "ng build",
}

在 package.json 中，npm run build 腳本會呼叫 ng build 來建置 Angular 應用程式。指定了以下選項參數：

define - 用 secrets.SECRET_GITHUB_TOKEN 替換環境變數 SECRET_GITHUB_TOKEN

base-href - 設定部署後應用程式的基底 URL (Base URL)。此範例中基底 URL 為 https://railsstudent.github.io/angular-github-profile/。

接著，使用 touch 指令建立一個空白的 .nojekyll 檔案。

將 index.html 複製為 404.html，當使用者存取不存在的資源時，瀏覽器會呈現 404.html。

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main # or your default branch
  workflow_dispatch:  # Also allow manual trigger

permissions:
  id-token: write
  contents: read # You might also need other permissions like contents: read
  pages: write # If deploying to GitHub Pages

jobs:
  build-and-deploy:
    environment: 
      name: github-pages   # Specify the deployment environment here
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js (if needed for static site generator)
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Build site (example for a static site generator)
        run: npm run build -- --define SECRET_GITHUB_TOKEN=\'${{ secrets.SECRET_GITHUB_TOKEN }}\' --base-href=https://railsstudent.github.io/angular-github-profile/  # or your build command

      - name: Add .nojekyll file
        run: touch dist/.nojekyll

      - name: Add 404.html file
        run: cp dist/index.html dist/404.html

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v3

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist # or the path to your built site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

將 yaml 檔案提交（commit）到 main 分支以自動化部署流程。

確認儲存庫中設定相同，線上網站應可成功運行。將 yaml 檔案提交（commit）到 main 分支以自動化部署流程。

確認儲存庫中設定相同，線上網站應可成功運行。