GitHub 版本控制與 Cloudflare Pages 部署實務

01網站部署與版本控制的基本觀念

前五章完成的金融網站目前只在個人電腦中執行。若網站只保存在本機，會遇到：其他人無法透過網路使用、電腦故障可能遺失檔案、修改錯誤後不容易回復舊版本、不同電腦之間難以同步，以及無法建立正式網址等問題。

反面教材：檔名版本控制——很多初學者用這種方式管理版本，不可持續：

網站最新版.html
網站最新版2.html
網站最新版最後.html
網站最新版最後修正版.html
網站最新版真的最後.html   ← 真的是最後嗎？

這種方式的問題：無法判斷哪一個才是正確版本、不知道每個版本修改了什麼、修改錯誤時難以回復、多人合作時容易覆蓋彼此的檔案、不同電腦之間無法同步。

版本控制的好處：以 Git commit 管理版本

02Git、GitHub 與 Cloudflare Pages 的差異

03Repository 的基本概念

Repository（簡稱 Repo）可以理解為「一個具有版本紀錄的專案資料夾」。金融網站的 Repository 包含所有 HTML、CSS、JavaScript、JSON、圖片、Python 程式與說明文件。

financial-platform/
├─ index.html            ← 第一章：複利計算器
├─ time-value.html       ← 第二章：貨幣時間價值
├─ bond-database.html    ← 第三章：債券資料庫
├─ visualization.html    ← 第五章：金融圖表
├─ css/                  ← 所有 CSS 樣式
├─ js/                   ← 所有 JavaScript
├─ data/                 ← JSON、CSV 資料
├─ images/               ← 圖片資源
├─ output/                ← Plotly 輸出 HTML
├─ python/               ← Python 分析程式
├─ README.md             ← 專案說明（必填）
└─ .gitignore            ← 排除不應上傳的檔案

Public vs Private Repository

04建立 GitHub Repository

登入 GitHub 後，新建 Repository 的操作步驟：選擇 New repository → 輸入名稱（建議英文小寫連字號格式）→ 填寫說明 → 選擇 Public 或 Private → 可勾選建立 README → 建立。

05建立 README.md

README.md 是專案說明文件，顯示在 Repository 首頁。應包含：專案名稱與目的、主要功能、資料夾結構、本機測試方式、免責聲明。

# 金融程式設計與知識網站實作

本專案是一個金融教育與分析工具網站，包含複利、
貨幣時間價值、債券資料庫、股票分析與互動圖表。

## 主要功能

1. 複利終值計算器（index.html）
2. 現值與終值計算器（time-value.html）
3. 債券 JSON 資料庫（bond-database.html）
4. 股票 CSV 資料清理與報酬分析（python/stock-analysis.py）
5. Chart.js 金融圖表（visualization.html）
6. Plotly 互動圖表（python/stock-charts.py）

## 本機測試

在專案資料夾中執行：

```bash
python -m http.server 8000
```

瀏覽器開啟 http://localhost:8000

## 免責聲明

本專案僅供金融教育、程式設計與情境試算使用，
不構成任何投資建議或報酬保證。

06建立 .gitignore

.gitignore 用來告訴 Git 哪些檔案不應加入版本控制。即使這些檔案存在本機，Git 也不會追蹤或上傳它們。

# Python 虛擬環境（不上傳，佔用空間且含平台設定）
.venv/
venv/

# Python 快取
__pycache__/
*.pyc

# ⚠️ Streamlit 機密設定（絕對不能上傳）
.streamlit/secrets.toml

# ⚠️ 環境變數（絕對不能上傳）
.env
.env.*
!.env.example          ← 範例檔案（不含實際值）可以上傳

# ⚠️ Token 與金鑰檔案（絕對不能上傳）
token.txt
secrets.json
credentials.json

# 作業系統暫存檔
.DS_Store               ← macOS
Thumbs.db                ← Windows

# 編輯器設定
.vscode/
.idea/

# 暫存與日誌
*.tmp
*.bak
*.log

# 個人或未公開資料
data/private/
data/personal/

07哪些檔案應上傳、哪些絕對不能上傳

前端 JavaScript 不能藏密碼

// ✗ 這樣寫是嚴重錯誤！
const apiKey = "sk-xxxxxxxxxxxxxxxxxxxxxxxx";

// 問題：瀏覽器下載整份 JS 檔案給使用者，
// 任何人按 F12 → Sources 就能看到這個金鑰！

// ✓ 正確做法：
// 1. 金鑰放在伺服器端（Node.js / Python 後端）
// 2. 使用環境變數（.env，已加入 .gitignore）
// 3. 使用 Cloudflare Workers Secrets 或 GitHub Secrets

08使用 GitHub 網頁上傳檔案（初學者友善方式）

若尚未安裝 Git，可先使用 GitHub 網頁介面上傳檔案。操作方式：進入 Repository → Add file → Upload files → 拖曳檔案 → 填寫 commit 訊息 → 確認提交。

commit 訊息範例

09使用 Git 與 PowerShell 管理版本

# 確認 Git 已安裝
git --version

# 設定使用者名稱（出現在 commit 紀錄中，首次使用執行一次）
git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"

# 確認設定
git config --list

10完整 Git 第一次上傳流程

# 步驟 1：進入專案資料夾
cd C:\financial-platform

# 步驟 2：初始化 Git（建立 .git 隱藏目錄）
git init

# 步驟 3：查看狀態（確認哪些檔案待追蹤）
git status

# 步驟 4：加入所有檔案到暫存區
git add .

# 步驟 5：建立第一個 commit
git commit -m "建立金融網站初始版本"

# 步驟 6：設定主要分支名稱為 main
git branch -M main

# 步驟 7：連接 GitHub Repository（貼上你的 Repository 網址）
git remote add origin https://github.com/帳號/financial-platform.git

# 步驟 8：第一次推送
git push -u origin main

# ── 若 GitHub 已有 README（非空 Repository），需先 pull ──
# git pull origin main --rebase
# 再重新執行步驟 8

11日常更新流程

# 查看修改狀態
git status

# 加入所有修改
git add .

# 建立說明修改內容的 commit
git commit -m "修正債券資料庫篩選邏輯"

# 推送到 GitHub（Cloudflare 會自動重新部署）
git push

12常用 Git 指令速查表

commit / push / pull / clone 的差別

13branch 分支概念

branch 讓你在不影響正式網站的情況下開發新功能。main 是正式穩定版本，feature/bond-tool 等功能分支在獨立環境中開發，測試通過後再合併回 main。

# 建立並切換到新分支
git switch -c feature/bond-tool

# 在新分支中修改、commit、push...

# 切回 main
git switch main

# 合併功能分支
git merge feature/bond-tool

# 推送合併結果
git push

14建立 Cloudflare Pages 專案

15GitHub 更新與 Cloudflare 自動部署

16自有網域設定

Cloudflare Pages 預設提供 https://專案名稱.pages.dev 網址。若要使用自有網域，可在 Pages 專案的 Custom domains 中新增。

17DNS 基本觀念

DNS（Domain Name System）可以理解為網路的地址簿。使用者輸入 example.com，DNS 告訴瀏覽器應連到哪個服務。

18HTTPS 與 SSL 憑證

19相對路徑與絕對路徑

<!-- 相對路徑（推薦用於靜態網站）-->
<link rel="stylesheet" href="css/style.css">
← 從目前頁面位置往下找 css 資料夾

<!-- 根目錄路徑（以 / 開頭）-->
<link rel="stylesheet" href="/css/style.css">
← 從網站根目錄開始找

<!-- ✗ 本機絕對路徑（部署後一定失效）-->
<img src="C:\\financial-platform\\images\\bond.png">
← 部署環境沒有 C:/ 路徑，一定 404！

20Token 與機密資料保護

Token 外洩後的正確處理步驟

1. 立即 revoke Token（GitHub Settings → Developer settings → Tokens → Revoke）
2. 建立新 Token（最小必要權限 + 設定有效期限）
3. 將 Token 移至安全位置（.env 或 secrets.toml，已加入 .gitignore）
4. 清理 Git 歷史中的 Token 記錄（使用 git filter-repo 或聯繫 GitHub）
5. 檢查帳號是否有異常操作紀錄
6. 更新所有使用此 Token 的程式設定

Secrets 與環境變數的正確存放位置

21部署前安全檢查清單

22十步驟完整部署操作流程

發布功能測試清單（步驟⑨）

23常見部署錯誤與除錯

F12 開發者工具除錯

24Git 版本回復

# 1. 查看 commit 紀錄
git log --oneline
# a1b2c3d 修正債券JSON（這次有問題）
# d4e5f6g 新增金融圖表（這個版本正常）
# h7i8j9k 建立首頁

# 2. 查看某次修改內容
git show a1b2c3d

# 3. 安全回復（建立新的反向 commit，不改寫歷史）
git revert a1b2c3d

# 4. 推送（Cloudflare 自動重新部署穩定版本）
git push

25Git Tag 版本標籤

# 建立附說明的 Tag
git tag -a v1.0 -m "金融網站第一個正式上線版本"

# 推送 Tag 到 GitHub
git push origin v1.0

# 查看所有 Tag
git tag

# 適合建立 Tag 的時機：
# - 網站第一次正式上線
# - 新增大型金融工具
# - 完成重要改版
# - 重要活動前的穩定版本

26實務案例

27常見 Git 錯誤與除錯

28網站發布四大檢查表

29關鍵字

30實作練習

本章沒有可以直接在瀏覽器裡執行的計算工具，所以挑戰任務（04 分頁）改成情境診斷形式——針對「常見部署錯誤」「常見 Git 錯誤」與「Token／資安判斷」三大類設計選擇題，答題後立即看到詳解與正確處理方式。實際動手操作，請照著「示範分頁」的模擬終端機跑一次流程，再到自己電腦真正操作一遍。