Skip to main content

專案歷程總結

🎯 專案目標​

將「視頻亮點編輯工具」從 styled-components 遷移到 Tailwind CSS + Material Design 風格，並建立可靠的 CI/CD 自動部署流程。

🛠️ 技術棧轉換​

  • 從: sty- 錯誤的文件結構導致 GitHub Pages 找不到 index.htmled-components + 自定義樣式
  • 到: Tailwind CSS + Material Design 3 + Google Fonts

🚧 遇到的主要困難與解決方案​

1️⃣ 樣式系統遷移問題​

困難:

  • styled-components 語法與 Tai3. 測試部署: 總是在本地測試 npm run build 和 npm run previewwind utility classes 完全不同
  • 大量 styled.div 等宣告需要逐一替換
  • Material Design 色彩系統需要整合到 Tailwind

解決方案:

// ❌ 舊的 styled-components
const StyledButton = styled.button`
  background: #2DEA9E;
  padding: 12px 24px;
`;

// ✅ 新的 Tailwind + Material Design
<button className="bg-primary text-on-primary px-6 py-3 rounded-lg 
                   elevation-2 hover:elevation-4 transition-all">

關鍵配置:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#2DEA9E',
        secondary: '#080635',
        surface: '#FEFBFF',
        // Material Design 色彩系統
      }
    }
  }
}

2️⃣ PostCSS 配置問題​

困難:

Error: PostCSS plugin autoprefixer requires PostCSS 8

解決方案:

// postcss.config.js - 正確配置

module.exports = {

  plugins: {

    tailwindcss: {},

    autoprefixer: {},

  },

}

// ❌ 錯誤的 ES6 import 語法會導致問題

3️⃣ 依賴版本衝突​

困難:

npm error Invalid: lock file's picomatch@2.3.1 does not satisfy picomatch@4.0.2

npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync

解決方案:

# 完全重置依賴
rm package-lock.json node_modules -rf
npm install

# 在 CI/CD 中添加備用方案
if ! npm ci; then
  echo "npm ci failed, falling back to npm install"
  rm -f package-lock.json
  npm install
fi

4️⃣ GitHub Pages 部署架構問題​

困難:

  • 官方 actions/deploy-pages@v4 需要特殊權限設置
  • GitHub Pages 必須先手動啟用
  • actions/configure-pages@v5 出現 "Not Found" 錯誤

解決方案:

# ❌ 複雜的官方 Actions
- uses: actions/configure-pages@v5
- uses: actions/deploy-pages@v4

# ✅ 簡單可靠的第三方 Action
- uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./dist
    enable_jekyll: false

5️⃣ GitHub Pages 404 錯誤​

困難:

  • 構建文件位於 dist/ 子目錄而不是根目錄
  • 錯誤的文件結構導致 GitHub Pages 找不到 

解決方案:

# ❌ 錯誤結構
gh-pages/
├── dist/
│   ├── index.html
│   └── assets/

# ✅ 正確結構  
gh-pages/
├── index.html
├── assets/
└── .nojekyll

6️⃣ Vite Base Path 配置​

困難:

  • GitHub Pages 的 URL 結構為 username.github.io/repo-name/
  • 需要正確設置 base path 讓資源載入

解決方案:

// vite.config.ts
export default defineConfig({
  base: process.env.NODE_ENV === 'production' 
    ? '/video-highlight-tool/' 
    : '/',
  // 確保生產環境使用正確的基礎路徑
})

🎯 新專案建立最佳實踐​

📋 初始化檢查清單​

1. 專案結構規劃​

project/
├── src/
│   ├── components/
│   ├── types/
│   ├── utils/
│   └── api/
├── public/
│   └── .nojekyll          # 📌 GitHub Pages 必須
├── .github/
│   └── workflows/
│       └── ci-cd.yml      # 📌 自動部署
├── tailwind.config.js     # 📌 樣式配置
├── postcss.config.js      # 📌 PostCSS 配置
└── vite.config.ts         # 📌 正確的 base path

2. 依賴管理策略​

# 📌 使用固定版本避免衝突
npm install --save-exact tailwindcss@3.4.0
npm install --save-exact @tailwindcss/typography@0.5.0

# 📌 定期清理
npm run clean  # 自定義腳本
rm -rf node_modules package-lock.json && npm install

3. Tailwind + Material Design 設置模板​

// tailwind.config.js 標準模板
module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        // Material Design 3 色彩
        primary: '#6750A4',
        'on-primary': '#FFFFFF',
        secondary: '#625B71',
        surface: '#FFFBFE',
        outline: '#79747E',
      },
      fontFamily: {
        sans: ['Roboto', 'system-ui', 'sans-serif'],
      },
      boxShadow: {
        'elevation-1': '0px 1px 2px rgba(0, 0, 0, 0.3), 0px 1px 3px 1px rgba(0, 0, 0, 0.15)',
        'elevation-2': '0px 1px 2px rgba(0, 0, 0, 0.3), 0px 2px 6px 2px rgba(0, 0, 0, 0.15)',
      }
    }
  },
  plugins: [require('@tailwindcss/typography')],
}

4. 可靠的 CI/CD 模板​

name: Build and Deploy
on:
  push:
    branches: [ main ]

permissions:
  contents: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
        cache: 'npm'
    
    - name: Install dependencies
      run: |
        if ! npm ci; then
          rm -f package-lock.json
          npm install
        fi
    
    - run: npm run build
    
    - uses: peaceiris/actions-gh-pages@v4
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist
        enable_jekyll: false

5. Vite 配置模板​

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: process.env.NODE_ENV === 'production' 
    ? '/your-repo-name/' 
    : '/',
  build: {
    outDir: 'dist',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        }
      }
    }
  },
})

🚀 部署準備檢查​

GitHub 倉庫設置​

  1. Actions 權限: Settings → Actions → "Read and write permissions"
  2. Pages 設置: Settings → Pages → "Deploy from branch" → "gh-pages"
  3. 分支保護: 可選，但建議對 main 分支啟用

本地開發檢查​

# 📌 部署前測試腳本
#!/bin/bash
echo "🔍 部署前檢查..."

# 依賴檢查
npm ci || npm install

# 代碼質量
npm run lint
npx tsc --noEmit

# 構建測試
npm run build

# 預覽測試
npm run preview &
sleep 3
curl -f http://localhost:4173 || echo "❌ 預覽失敗"

echo "✅ 準備就緒！"

🎯 關鍵經驗教訓​

🔑 避免的錯誤​

  1. 不要混用樣式系統: 徹底移除 styled-components，避免樣式衝突
  2. 版本管理: 使用 --save-exact 鎖定關鍵依賴版本
  3. 測試部署: 總是在本地測試 [npm run build] 和 npm run preview
  4. 漸進遷移: 一次處理一個組件，逐步驗證樣式效果
  5. 備用方案: CI/CD 中總是準備依賴安裝的備用方案

🎯 成功要素​

  1. 系統性方法: 先設置配置文件，再遷移組件
  2. 完整測試: 每個步驟都驗證功能正常
  3. 文檔記錄: 創建詳細的設置和故障排除指南
  4. 工具輔助: 使用腳本自動化常見任務
  5. 監控機制: 設置檢查腳本監控專案健康狀態