Table of Contents

GitHub Pages
完整指南：從零建立專業靜態網站

GitHub Pages 適合我嗎？

快速自我檢測

你適合使用 GitHub Pages 如果：

✅ 想建立個人作品集網站展示專案
✅ 需要技術文件或專案說明頁面
✅ 想寫技術部落格但不想處理伺服器
✅ 會基本 HTML/CSS，或願意學習 Markdown
✅ 希望完全免費且不用擔心流量問題

你可能不適合 GitHub Pages 如果：

❌ 需要資料庫功能（使用者註冊、留言系統）
❌ 需要後端處理（表單提交、即時聊天）
❌ 需要電商功能（購物車、金流處理）
❌ 文章數量超過 100 篇且在意建置速度

三種方案快速比較

方案	適合誰	優點	缺點	推薦度
純 HTML 手寫	完全新手	最簡單，立即上線	維護困難，每次修改都要改所有頁面	⭐⭐
Jekyll 主題套用	前端新手	開箱即用，維護簡單	需要學習基礎 Markdown 與 YAML	⭐⭐⭐⭐⭐
進階框架 (Hugo/Astro)	有經驗開發者	建置速度快，功能強大	學習曲線陡峭，需要 Terminal 操作	⭐⭐⭐

推薦路線： 新手從 Jekyll
主題開始，累積經驗後再考慮進階框架。

真實成本分析

完全免費包含：

✅ 無限流量（每月 100GB 軟限制）
✅ 自動 HTTPS 加密
✅ 1GB 儲存空間
✅ 自訂域名支援

何時該考慮替代方案：

你的需求	GitHub Pages	建議替代方案
純展示作品集	✅ 完美適合	–
技術部落格（<100 篇）	✅ 適合	–
技術部落格（>100 篇）	⚠️ 可用但慢	Hugo + Netlify
需要聯絡表單	⚠️ 需外掛服務	Formspree（免費）
需要使用者登入	❌ 不支援	Firebase + Netlify
電商網站	❌ 不支援	Shopify / WooCommerce
需要 CMS 後台	⚠️ 可外掛	Netlify CMS / Forestry

說明：

✅ = 開箱即用
⚠️ = 可以做到，但需要整合第三方服務
❌ = 不適合，建議其他方案

10 分鐘快速上手

情境 A：展示靜態 HTML（最基礎）

適合： 已有 HTML 檔案，只想快速上線

步驟：

建立 Repository
- 登入 GitHub
- 點擊右上角「+」→「New repository」
- Repository
  名稱填入：你的帳號名稱.github.io（例：yourname.github.io）
- 選擇「Public」
- 勾選「Add a README file」
- 點擊「Create repository」
上傳你的 HTML
- 進入 repository 頁面
- 點擊「Add file」→「Upload files」
- 拖曳你的 index.html 和其他檔案
- 點擊「Commit changes」
完成！
- 等待 1-2 分鐘
- 開啟 https://你的帳號名稱.github.io
- 你的網站已上線

預估時間： 5 分鐘

情境 B：使用 Jekyll
主題（推薦路線）⭐

適合： 想要專業外觀，但不想從零設計

步驟：

1. 選擇主題

我們推薦 3 個精選主題：

選項 1：Minimal Mistakes（最推薦） –
適合：工程師作品集、技術部落格 – 風格：現代、專業、可高度客製化 –
Demo：https://mmistakes.github.io/minimal-mistakes/
– 特色：響應式設計、支援搜尋、社群分享

選項 2：al-folio（學術風格） –
適合：研究人員、博士生、學術展示 – 風格：簡潔、學術、多語言支援 –
Demo：https://alshedivat.github.io/al-folio/
– 特色：出版品列表、專案展示、CV 支援

選項 3：Beautiful Jekyll（最簡單） –
適合：完全新手、個人部落格 – 風格：清爽、易讀、設定簡單 – Demo：https://beautifuljekyll.com/ –
特色：5 分鐘完成設定、豐富文件

2. Fork 主題（以 Minimal
Mistakes 為例）

開啟主題的 GitHub 頁面
點擊右上角「Fork」
將 repository 名稱改為 你的帳號名稱.github.io
點擊「Create fork」

3. 啟用 GitHub Pages

進入你 fork 的 repository
點擊「Settings」→「Pages」
在「Source」選擇「Deploy from a branch」
選擇「main」或「master」分支
點擊「Save」

4. 修改基本資訊

找到並編輯 _config.yml 檔案（點擊檔案名稱 →
點擊鉛筆圖示編輯）：

# 只需修改這 5 個欄位
title: "你的名字"
name: "你的全名"
description: "一句話介紹自己"
url: "https://你的帳號名稱.github.io"
baseurl: ""

點擊「Commit changes」儲存。

5. 測試網站

等待 2-3 分鐘，開啟
https://你的帳號名稱.github.io，你的網站已上線！

預估時間： 15-20 分鐘

快速上手檢查清單

完成以下步驟，你的網站就上線了！

第一階段：建立基礎（預估 30 分鐘）

建立 GitHub 帳號
建立 username.github.io
repository
啟用 GitHub Pages（Settings →
Pages）
選擇一個主題（推薦：Jekyll
預設主題或 Minimal Mistakes）
修改 _config.yml
基本資訊（5 個欄位）
測試網站：開啟
https://username.github.io

第二階段：加入內容（預估 1-2 小時）

第三階段：優化（選做，預估 2-4 小時）

自訂域名（如果有的話）
Google Analytics 追蹤碼
SEO 基礎設定
社群分享預覽圖

內容維護實戰

新增文章的三種方式（由易到難）

方式一：GitHub
網頁編輯（推薦新手）⭐

適合： 不想安裝軟體，偶爾更新內容

步驟：

開啟 GitHub repository
進入 _posts 資料夾
點擊「Add file」→「Create new file」
檔名格式：YYYY-MM-DD-標題.md（例：2025-01-15-my-first-post.md）
貼上以下內容：

---
layout: post
title: "我的第一篇文章"
date: 2025-01-15
categories: blog
---

這是我的第一篇文章內容。

## 小節標題

你可以使用 Markdown 語法撰寫內容。

點擊「Commit changes」
等待 1-2 分鐘自動部署完成

優點： 不需安裝任何軟體，隨時隨地可編輯
缺點： 無法即時預覽，需要等待部署

方式二：GitHub
Desktop（視覺化工具）

適合： 想在本機編輯，但不熟悉 Git 指令

步驟：

下載 GitHub Desktop
- 前往 desktop.github.com
- 下載並安裝
Clone Repository 到本機
- 開啟 GitHub Desktop
- File → Clone Repository
- 選擇你的 username.github.io
- 選擇儲存位置
- 點擊「Clone」
修改檔案
- 用你喜歡的編輯器（如 VS Code、Sublime Text）修改檔案
- 新增文章到 _posts 資料夾
提交變更
- 回到 GitHub Desktop
- 左下角填入 commit 訊息（如：「新增文章：我的專案介紹」）
- 點擊「Commit to main」
- 點擊「Push origin」
完成
- 等待 1-2 分鐘自動部署

優點： 可本機預覽、批次修改多個檔案
缺點： 需要安裝軟體

方式三：Git 指令（進階使用者）

適合： 熟悉 Terminal，想要完整控制

# Clone repository
git clone https://github.com/你的帳號名稱/你的帳號名稱.github.io.git
cd 你的帳號名稱.github.io

# 新增文章
nano _posts/2025-01-15-my-post.md

# 提交變更
git add .
git commit -m "新增文章：我的專案介紹"
git push

提示：
新手建議先用方式一，熟悉流程後再考慮方式二。

常見內容更新場景

場景 1：修改個人簡介

檔案位置： _config.yml 或
about.md（依選用主題而定）

步驟：

找到檔案並編輯
修改 description 或 bio 欄位
儲存並 commit

**範例（_config.yml）：**

author:
  name: "你的名字"
  bio: "前端工程師 / 開源貢獻者 / 技術寫作者"
  location: "台北, 台灣"
  links:
    - label: "GitHub"
      url: "https://github.com/你的帳號"

場景 2：新增作品展示

檔案位置： 建立 _portfolio 資料夾（或
_posts）

步驟：

在 _portfolio 資料夾中新增 Markdown 檔案
填入專案資訊（標題、描述、連結等）
儲存並 commit

**範例檔案（_portfolio/project-name.md）：**

---
title: "專案名稱"
excerpt: "專案簡短描述（一句話）"
header:
  teaser: /assets/images/project-screenshot.png
tags:
  - React
  - TypeScript
  - Firebase
---

## 專案概述

這個專案解決了...

## 技術堆疊

- **前端：** React, TypeScript, Tailwind CSS
- **後端：** Firebase Functions
- **部署：** Vercel

## 專案連結

- [Live Demo](https://your-project.com)
- [GitHub Repository](https://github.com/你的帳號/專案名稱)

## 專案截圖

![專案首頁](/assets/images/project-home.png)

## 遇到的挑戰與解決方案

1. **效能優化**：使用 React.memo 減少不必要的 re-render
2. **狀態管理**：採用 Zustand 簡化複雜狀態邏輯

場景 3：調整導航選單

檔案位置： _config.yml 或
_data/navigation.yml

範例（navigation.yml）：

main:
  - title: "關於我"
    url: /about/
  - title: "作品集"
    url: /portfolio/
  - title: "部落格"
    url: /blog/
  - title: "聯絡我"
    url: /contact/

場景 4：更換主題風格

檔案位置： _config.yml

範例：

# Minimal Mistakes 主題提供多種配色
minimal_mistakes_skin: "default" # 可選：air, aqua, contrast, dark, dirt, neon, mint, plum, sunrise

修改後儲存，等待重新部署即可看到新配色。

Markdown
快速上手（只教必要的）

80% 需求只需這些語法：

# 標題 1（最大）
## 標題 2
### 標題 3

**粗體文字**
*斜體文字*

[連結文字](https://example.com)

![圖片說明](/assets/images/photo.jpg)

- 項目符號 1
- 項目符號 2

1. 編號清單 1
2. 編號清單 2

程式碼區塊（技術部落格必備）：

def hello_world():
    print("Hello, GitHub Pages!")

更多進階語法： Markdown Guide

真實案例分析

案例 1：前端工程師作品集

網站： Brittany Chiang

使用技術： – GitHub Pages – 自訂 HTML/CSS（非
Jekyll） – 響應式設計

內容結構： – 首頁： Hero Section +
精選 3 個專案 – About： 個人簡介 + 技能標籤（React,
TypeScript, Node.js） – Projects： 6
個代表專案，每個包含： – 專案截圖 – 技術堆疊 – GitHub repo 連結 – Live
Demo 連結 – Contact： Email + LinkedIn + GitHub

值得學習的地方： – ✅ 極簡設計，專注內容 – ✅
互動效果流暢（滑鼠移入效果） – ✅ 專案說明簡潔（3 句話：問題 → 解決方案
→ 成果） – ✅ 行動裝置優化完善

建置時間估計： 首次建置 4 小時 + 內容填寫 6 小時

案例 2：開源專案文件

網站： Vue.js
Documentation（早期使用 GitHub Pages）

使用技術： – VuePress（基於 Vue.js
的靜態網站生成器） – GitHub Pages 部署 – 多語言支援

內容結構： – Guide： 逐步教學文件 –
API Reference： 完整 API 說明 –
Examples： 互動式範例 – Migration
Guide：版本升級指南

值得學習的地方： – ✅ 左側導航清晰（文件網站必備） –
✅ 搜尋功能強大（使用 Algolia DocSearch） – ✅ 程式碼範例可複製 – ✅
暗色模式支援

適用場景： 如果你的專案需要完整文件，VuePress 或
Docusaurus 比 Jekyll 更適合。

案例 3：個人技術部落格

網站： Dan
Abramov’s Overreacted

使用技術： – Gatsby（React 靜態網站生成器） – GitHub
Pages 部署 – Markdown 撰寫

內容結構： – 首頁：
文章列表（依時間排序） – 文章頁：
深度技術文章（2000-5000 字） – About： 極簡個人簡介 –
RSS Feed： 支援訂閱

值得學習的地方： – ✅ 內容為王（沒有多餘設計元素） –
✅ 閱讀體驗優化（字體大小、行距、寬度） – ✅
文章結構清晰（標題、程式碼、結論） – ✅ SEO 優化完善（每篇文章都有 meta
description）

啟示：
好的技術部落格不需要花俏設計，專注內容品質更重要。

三個案例的共同特點

特點	案例 1 作品集	案例 2 文件	案例 3 部落格
載入速度	< 1 秒	< 2 秒	< 1 秒
行動優化	✅ 完美	✅ 完美	✅ 完美
SEO 設定	✅ 有	✅ 完整	✅ 完整
自訂域名	✅ 有	✅ 有	✅ 有
更新頻率	每季更新	每週更新	每月 2-4 篇

結論： 無論哪種類型，成功的 GitHub Pages
網站都重視：速度、行動優化、內容品質。

進階優化（選讀）

自訂域名設定

從 username.github.io 改成
blog.yourname.com

步驟 1：購買域名

推薦：Cloudflare
Registrar（價格透明、無隱藏費用）
其他選擇：Namecheap、GoDaddy、Gandi

步驟 2：設定 DNS

在域名商的 DNS 設定頁面新增以下記錄：

類型: A
名稱: @
值: 185.199.108.153

類型: A
名稱: @
值: 185.199.109.153

類型: A
名稱: @
值: 185.199.110.153

類型: A
名稱: @
值: 185.199.111.153

類型: CNAME
名稱: www
值: 你的帳號名稱.github.io

步驟 3：GitHub 設定

進入 repository
Settings → Pages
在「Custom
domain」填入你的域名（如：blog.yourname.com）
點擊「Save」
勾選「Enforce HTTPS」（等待 DNS 生效後，約 10-30 分鐘）

常見錯誤排解

錯誤 1：DNS_PROBE_FINISHED_NXDOMAIN – 原因：DNS
尚未生效 – 解決：等待 24-48 小時（通常 1 小時內即可）

錯誤 2：HTTPS 無法啟用 – 原因：DNS 記錄不正確 –
解決：檢查 A 記錄是否正確，確認 CNAME 指向
username.github.io

SEO 基礎優化

1. 自動生成 sitemap.xml

Jekyll 預設會自動生成，確認 _config.yml 有以下設定：

plugins:
  - jekyll-sitemap

驗證方式：開啟 https://你的網站/sitemap.xml

2. Google Search Console 設定

前往 Google
Search Console
新增資源 → 輸入你的網站 URL
驗證擁有權（選擇「HTML 標籤」方式最簡單）
將驗證碼加入 _includes/head.html 的
<head> 區段
提交 sitemap：https://你的網站/sitemap.xml

3. 社群分享預覽圖（Open Graph）

在每篇文章的 front matter 加入：

---
title: "文章標題"
image: /assets/images/og-image.jpg
description: "這篇文章的簡短描述（120-160 字）"
---

確認主題的 _includes/head.html 包含以下 meta 標籤：

<meta property="og:title" content="{{ page.title }}" />
<meta property="og:description" content="{{ page.description }}" />
<meta property="og:image" content="{{ site.url }}{{ page.image }}" />
<meta property="og:url" content="{{ site.url }}{{ page.url }}" />

效能優化

1. 圖片壓縮建議

工具： – TinyPNG（線上壓縮） – ImageOptim（Mac 應用程式） – Squoosh（Google 開源工具）

建議： – 專案截圖：寬度 1200px，JPG 品質 85% – Open
Graph 圖片：1200x630px，< 200KB – 頭像：400x400px，< 100KB

2. CDN 加速（Cloudflare
免費方案）

註冊 Cloudflare
新增你的網站
將域名 DNS 改為 Cloudflare 提供的 nameservers
啟用以下功能：
- Auto Minify（自動壓縮 HTML/CSS/JS）
- Brotli 壓縮
- Browser Cache TTL

效果： 全球載入速度提升 30-50%

3. 延遲載入技巧

在圖片標籤加入 loading="lazy"：

<img src="/assets/images/photo.jpg" alt="描述" loading="lazy">

Markdown 中則需要用 HTML 語法：

<img src="/assets/images/photo.jpg" alt="描述" loading="lazy">

GitHub Actions 自動化（進階）

自動部署流程範例：

建立 .github/workflows/deploy.yml：

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true

      - name: Build site
        run: bundle exec jekyll build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

功能： 每次 push 到 main 分支時自動建置並部署。

常見問題 FAQ

Q1: 修改內容後沒有立即生效？

原因： 瀏覽器快取或 GitHub Pages 尚未完成部署

解決方法： 1. 強制重新整理頁面（Ctrl+F5 或
Cmd+Shift+R） 2. 開啟無痕視窗測試 3. 檢查 repository
的「Actions」頁面，確認部署完成（綠色勾勾） 4. 通常部署需要 1-3 分鐘

Q2: 出現 404 Not Found 錯誤？

可能原因與解決方法：

原因 1：Repository 名稱錯誤 – 確認 repository 名稱是
你的帳號名稱.github.io（全小寫） – 範例：如果帳號是
JohnDoe，repository 應該是
johndoe.github.io

原因 2：GitHub Pages 未啟用 – 進入 Settings → Pages
– 確認「Source」已設定為正確分支（通常是 main）

原因 3：檔案名稱錯誤 – 首頁檔案必須命名為
index.html 或 index.md – 文章檔案格式必須是
YYYY-MM-DD-標題.md

Q3: 如何客製化 CSS 樣式？

方法： 建立自訂 CSS 檔案並覆蓋主題樣式

步驟：

建立 /assets/css/custom.css
寫入你的自訂樣式：

/* 修改主標題顏色 */
h1 {
  color: #2c3e50;
}

/* 修改連結顏色 */
a {
  color: #3498db;
}

/* 修改程式碼區塊背景 */
pre {
  background-color: #f8f9fa;
  border-radius: 4px;
}

在
_includes/head-custom.html（或主題對應檔案）加入：

<link rel="stylesheet" href="{{ '/assets/css/custom.css' | relative_url }}">

Q4: 可以使用 Google
Analytics 追蹤流量嗎？

可以！ Jekyll 主題通常內建 Google Analytics
支援。

設定方法：

取得 Google Analytics 追蹤 ID（格式：G-XXXXXXXXXX 或
UA-XXXXXXXXX-X）
在 _config.yml 加入：

# Google Analytics
google_analytics: G-XXXXXXXXXX

重新部署後，等待 24 小時即可在 Google Analytics 看到資料

Q5: 如何新增留言功能？

GitHub Pages
本身不支援留言功能，但可以整合第三方服務：

選項 1：Disqus（最簡單）

註冊 Disqus
建立一個 site（取得 shortname）
在 _config.yml 加入：

disqus:
  shortname: 你的-shortname

確認主題有啟用 Disqus（Minimal Mistakes 預設支援）

選項 2：giscus（開源、隱私友善）

使用 GitHub Discussions 作為留言系統：

前往 giscus.app
按照步驟設定
將生成的程式碼加入 _layouts/post.html

選項 3：Utterances（極簡風格）

使用 GitHub Issues 作為留言系統：

前往 utteranc.es
按照步驟設定
將生成的 script 加入文章頁面

Q6: 如何備份我的網站？

GitHub
本身就是版本控制系統，你的所有內容都已經備份在雲端！

額外保險：

本機備份： 使用 Git clone 下載到本機

git clone https://github.com/你的帳號/你的帳號.github.io.git

定期匯出：
每季將重要內容（如文章、圖片）匯出到外部硬碟
多平台備份： 使用 GitHub Desktop
同步，確保本機與遠端一致

Q7: 可以使用自己的
CSS 框架（如 Tailwind CSS）嗎？

可以！ 但需要設定建置流程。

簡易方法（使用 CDN）：

在 _includes/head.html 加入：

<script src="https://cdn.tailwindcss.com"></script>

專業方法（本機建置）：

安裝 Tailwind CSS

npm install -D tailwindcss
npx tailwindcss init

設定 tailwind.config.js

module.exports = {
  content: [
    './_layouts/**/*.html',
    './_includes/**/*.html',
    './_posts/*.md',
  ],
  theme: {},
  plugins: [],
}

建立 GitHub Actions workflow 自動編譯 CSS

Q8: 網站速度慢怎麼辦？

診斷工具：

常見優化方法：

問題	解決方法
圖片太大	壓縮圖片、使用 WebP 格式
載入資源過多	移除不必要的 JavaScript 外掛
沒有快取	使用 Cloudflare CDN
CSS/JS 未壓縮	啟用 GitHub Actions 自動 minify
自訂字型太大	使用系統字型或僅載入需要的字重

目標： – PageSpeed Insights 分數 > 90 –
首次載入時間 < 2 秒

總結

關鍵重點回顧

GitHub Pages 適合誰：
前端新手、想建立作品集、技術部落格的開發者
最快上手路徑： 使用 Jekyll 主題（如 Minimal
Mistakes），30 分鐘完成基礎架構
內容維護： 新手用 GitHub 網頁編輯，熟悉後使用
GitHub Desktop
進階優化： 自訂域名、SEO、CDN
加速都是選做項目，優先專注內容品質

下一步建議

初學者（第 1-2 週）： 1. 完成快速上手檢查清單 2.
新增 3-5 個專案展示 3. 撰寫 About 頁面 4. 測試手機版顯示

進階（第 1 個月）： 1. 自訂域名（如果有需要） 2.
設定 Google Analytics 3. 優化 SEO（sitemap、meta description） 4. 學習
Markdown 進階語法

長期維護（3 個月以上）： 1.
定期更新作品集（每季至少一次） 2. 撰寫技術文章（每月 1-2 篇） 3.
監控網站流量與優化 4. 考慮是否需要更進階工具（Hugo、Gatsby）

GitHub Pages 完整指南：從零建立專業靜態網站

目錄

GitHub Pages 適合我嗎？

快速自我檢測

三種方案快速比較

真實成本分析

10 分鐘快速上手

情境 A：展示靜態 HTML（最基礎）

情境 B：使用 Jekyll 主題（推薦路線）⭐

1. 選擇主題

2. Fork 主題（以 Minimal Mistakes 為例）

3. 啟用 GitHub Pages

4. 修改基本資訊

5. 測試網站

快速上手檢查清單

內容維護實戰

新增文章的三種方式（由易到難）

方式一：GitHub 網頁編輯（推薦新手）⭐

方式二：GitHub Desktop（視覺化工具）

方式三：Git 指令（進階使用者）

常見內容更新場景

場景 1：修改個人簡介

場景 2：新增作品展示

場景 3：調整導航選單

場景 4：更換主題風格

Markdown 快速上手（只教必要的）

真實案例分析

案例 1：前端工程師作品集

案例 2：開源專案文件

案例 3：個人技術部落格

三個案例的共同特點

進階優化（選讀）

自訂域名設定

步驟 1：購買域名

步驟 2：設定 DNS

步驟 3：GitHub 設定

常見錯誤排解

SEO 基礎優化

1. 自動生成 sitemap.xml

2. Google Search Console 設定

3. 社群分享預覽圖（Open Graph）

效能優化

1. 圖片壓縮建議

2. CDN 加速（Cloudflare 免費方案）

3. 延遲載入技巧

GitHub Actions 自動化（進階）

常見問題 FAQ

Q1: 修改內容後沒有立即生效？

Q2: 出現 404 Not Found 錯誤？

Q3: 如何客製化 CSS 樣式？

Q4: 可以使用 Google Analytics 追蹤流量嗎？

Q5: 如何新增留言功能？

Q6: 如何備份我的網站？

Q7: 可以使用自己的 CSS 框架（如 Tailwind CSS）嗎？

Q8: 網站速度慢怎麼辦？

總結

關鍵重點回顧

下一步建議

推薦學習資源

Related posts: