程式開發流程進化版

v2 現代流程最佳化 GitHub 為 單一事實來源 HF Spaces 快速 預覽/測試 Docker/GitLab 穩定部署

現代程式開發流程優化

以 GitHub 為中心，善用分支策略與多遠端部署測試，讓「開發快、部署穩、歷史清楚、可追溯」。

🚀 實戰案例 🔁 GitHub × Hugging Face 流程 🐳 Docker × GitLab 流程 ❓ 常見問題

導覽

核心優化理念 高階流程圖 第零步：初始化 日常開發循環（GitHub ↔ HF） 本地 Docker + GitLab 流程比較表 實戰案例：Gradio 小工具 常見錯誤排查 常用模板與小抄 FAQ

核心優化理念

• 單一事實來源（Single Source of Truth）：所有正式程式碼以 GitHub 為中心，Hugging Face Spaces 僅作為預覽/測試環境。
• 分支策略（Branching）：以 feature/*、fix/* 為單元開發；main 永遠乾淨可發布。
• 多遠端命名：清楚區分 origin（GitHub）、hf（Hugging Face）、gitlab（GitLab）。
• 可回溯與審查：PR/MR 驗證品質；HF 快速驗證行為；GitHub 保留最終可追溯歷史。

小提醒：把「測試用提交」留在 feature 分支；等測過再合併回 main，主線歷史就會乾淨漂亮。

高階流程圖

第零步：初始設定（一次性）

1. 從 GitHub Clone 主倉庫

   git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
   
   cd YOUR_REPO

2. 新增 Hugging Face 遠端

   # 在 HF Space 頁面找到 Git 連結
   
   git remote add hf https://huggingface.co/spaces/YOUR_HF_USERNAME/YOUR_SPACE_NAME

3. （選用）新增 GitLab 遠端

   git remote add gitlab https://gitlab.com/YOUR_GROUP/YOUR_PROJECT.git

完成指標：執行 git remote -v 可同時看到 origin / hf / gitlab。

日常開發循環（GitHub ↔ Hugging Face）

1. 從 main 開新功能分支

   git checkout main
   
   git pull origin main
   
   git checkout -b feature/add-new-module

2. 撰寫程式並提交

   git add .
   
   git commit -m "feat: 新增模組與單元測試"

3. 推到 HF 的 main 以觸發即時預覽
   注意：這只會更新 HF 的 main，不影響 GitHub 的 main。

   # 語法：git push <remote> <local-branch>:<remote-branch>
   
   git push hf feature/add-new-module:main

4. 到 HF Spaces 驗證行為：確認 UI、功能、效能、日誌。
5. 測過沒問題 → 合併回 GitHub main

   git checkout main
   
   git merge feature/add-new-module --no-ff
   
   git push origin main

為何要「把 feature 推到 HF 的 main」？

這是最省事的「快速預覽」手法：HF 的 main 即代表目前要測的版本；等測通過，再把 feature 合回 GitHub 的 main，確保主線歷史乾淨。

本地 Docker + GitLab

1. VS Code Remote：建議使用 Remote - SSH 或 Dev Containers，確保一致環境。
2. 本地建置與測試

   docker build -t myapp:dev .
   
   docker run --rm -p 7860:7860 myapp:dev

3. 推送到 GitLab（或建立 MR）

   git push gitlab feature/add-new-module
   
   # 或合併後直推主線
   
   git checkout main
   
   git merge feature/add-new-module
   
   git push gitlab main

常見 Dockerfile 片段（含代理設定）

# syntax=docker/dockerfile:1

FROM python:3.11-slim

# 2️⃣ 代理設定（建置階段 & 執行階段）

ENV HTTP_PROXY  http://proxy-s2.cwa.gov.tw:8888

ENV HTTPS_PROXY http://proxy-s2.cwa.gov.tw:8888

ENV http_proxy  $HTTP_PROXY

ENV https_proxy $HTTPS_PROXY

# 讓本機回環地址不走代理（Gradio 需要直接呼叫 localhost）

ENV NO_PROXY localhost,127.0.0.1,192.168.20.200

ENV no_proxy $NO_PROXY

WORKDIR /app

COPY requirements.txt .

RUN pip install -r requirements.txt

COPY . .

CMD ["python","app.py"]

流程比較表

項目	原始流程	建議優化流程
程式碼來源	從 HF Clone	從 GitHub Clone
開發方式	直接改 main	用 feature/fix 分支
測試部署	push 到 HF 測試	把 feature 推到 HF 的 main 快速測
最終備份	再回推 GitHub	測通過 → 合併回 GitHub main
Git 歷史	main 夾雜測試提交	main 乾淨、可追溯

實戰案例：用 Gradio 做「地震資訊小工具」並快速發佈

情境：需要 24 小時內讓同事與學生「線上可用」，但主線要保持乾淨。

1. 建立功能分支與骨架

   git checkout -b feature/eq-info-widget
   
   echo "gradio==4.44.0" > requirements.txt
   
   cat > app.py << 'PY'
   
   import gradio as gr
   
   def mag_energy(m): return 10**(1.5*m + 4.8)  # 粗略能量估算
   
   with gr.Blocks(title="地震資訊小工具") as demo:
   
       m = gr.Slider(3.0, 8.0, step=0.1, label="震級 (M)")
   
       out = gr.Number(label="相對能量 (J) 量級指標", precision=0)
   
       m.change(lambda x:int(mag_energy(x)), m, out)
   
   demo.launch(server_name="0.0.0.0", server_port=7860)
   
   PY
   
   git add .
   
   git commit -m "feat(widget): 初版地震能量估算器"

2. 推到 HF 的 main 測試

   git push hf feature/eq-info-widget:main
   
   # 等 Space 自動建置完成 → 開網頁驗證互動是否正常

3. 收斂修正：若有 bug，直接在同一個 feature 分支修，重推到 HF 的 main 迭代。
4. 確認穩定 → 合回 GitHub main

   git checkout main
   
   git merge feature/eq-info-widget --no-ff
   
   git push origin main

成效：利⽤ HF 當「預覽舞台」，快速收斂互動與依賴；等穩定後才回 main，主線歷史保持乾淨。

常見錯誤排查（精選）

• Space 無法建置：檢查 requirements.txt 是否遺漏、Python 版本是否與 Space 設定一致。
• Gradio 圖形中文字亂碼：Matplotlib/系統字型缺失，改用 Noto Sans CJK 或在程式中設定字型。
• 代理導致 HF 內部迴圈不通：加入 NO_PROXY（如 localhost,127.0.0.1,192.168.20.200）。
• 推錯遠端：用 git remote -v 確認；或用明確語法 git push hf feature:main。
• main 混入測試提交：嚴格採 PR/Code Review；功能一定走分支，別直推 main。

常用模板與小抄

分支命名建議

類型	範例	說明
功能	feature/add-hf-preview	新功能/大變更
修 bug	fix/gradio-chinese-font	修正錯誤
文件	docs/update-readme-ci	純文件改動
效能	perf/calc-optim	效能微調

GitHub Action（自動跑測試）

# .github/workflows/ci.yml

name: CI

on: [push, pull_request]

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5

        with: { python-version: "3.11" }

      - run: pip install -r requirements.txt

      - run: python -m pytest -q || true  # 先允許基本驗證

快速檢視遠端與分支

git remote -v

git branch --all

git log --oneline --graph --decorate -n 20

FAQ

為什麼不直接改 GitHub 的 main？

main 是「可發布」的保證；任何實驗在 feature 裡做，避免污染主線歷史。

HF 的 main 與 GitHub 的 main 不一致會混亂嗎？

不會。把 HF 視作「預覽舞台」：它的 main 表示當前預覽版本；GitHub main 才是正式版本。

什麼時候該推 Docker/GitLab？

當功能在 HF 驗證穩定、要進入更嚴謹的 CI/CD 與長期部署時。

© 2025 現代開發流程示例頁。安全第一・流程清楚・迭代快速。