Vercel Preview 部署完整教學｜2025 團隊協作最佳實踐

每個 PR 自動產生一個預覽網址。

不用等 merge 就能看到改動效果。

這是 Vercel Preview Deployments 的威力。

這篇文章教你如何充分利用這個功能。

什麼是 Preview Deployments？

Preview Deployments 是針對每個分支或 PR 自動產生的臨時部署。

運作方式

main 分支 ──────────────────── Production（正式環境）
                                 https://your-app.vercel.app

feature/new-login ────────────── Preview
                                 https://your-app-abc123.vercel.app

fix/bug-123 ─────────────────── Preview
                                 https://your-app-def456.vercel.app

主要功能

自動啟用

連接 GitHub 後自動生效

當你把專案連接到 GitHub：

1. 每次 push 到任何分支 → 自動產生 Preview
2. 開 PR 時 → Vercel Bot 自動留言 Preview 網址
3. Merge 到 main → 自動更新 Production

GitHub PR 留言範例

當你開 PR 時，Vercel Bot 會留言：

✅ Deploy Preview for your-app ready!

🔍 Inspect: https://vercel.com/your-team/your-app/xxx
✅ Preview: https://your-app-abc123.vercel.app

Built with ⬛ Vercel

Preview 網址格式

分支 Preview

https://<project>-git-<branch>-<team>.vercel.app

範例：

https://my-app-git-feature-login-my-team.vercel.app

Commit Preview

每個 commit 也有獨特網址：

https://<project>-<commit-hash>-<team>.vercel.app

自訂 Preview 網域

可以設定 wildcard 網域：

*.preview.your-domain.com

在 Vercel Dashboard → Settings → Domains 設定。

團隊協作流程

標準開發流程

1. 開發者建立 feature branch
   git checkout -b feature/new-login

2. 開發並 commit
   git add . && git commit -m "Add login page"

3. Push 到 GitHub
   git push origin feature/new-login
   → Vercel 自動建立 Preview

4. 開 PR
   → Vercel Bot 留言 Preview 網址

5. 團隊成員檢視 Preview
   → 可以直接在頁面上留言

6. 修改並更新
   → 每次 push 都會更新 Preview

7. Merge PR
   → 自動部署到 Production

Preview 評論功能

Vercel 提供頁面上的評論功能：

1. 在 Preview 頁面，點擊 Vercel 工具列
2. 選擇「評論」模式
3. 點擊頁面上任何位置留言
4. 評論會同步到 GitHub PR

這對設計和前端審查非常有用。

環境設定

Preview 專用環境變數

# Production
STRIPE_KEY=sk_live_xxxx

# Preview（使用測試 key）
STRIPE_KEY=sk_test_xxxx

在 Vercel Dashboard 設定時，選擇只適用 Preview 環境。

Preview 專用功能

// 判斷是否在 Preview 環境
const isPreview = process.env.VERCEL_ENV === 'preview';

if (isPreview) {
  // 顯示測試環境標示
  console.log('This is a preview deployment');
}

Preview 環境變數

Vercel 自動注入的變數：

// 使用範例
export async function GET() {
  return Response.json({
    env: process.env.VERCEL_ENV,
    url: process.env.VERCEL_URL,
    commit: process.env.VERCEL_GIT_COMMIT_SHA,
    branch: process.env.VERCEL_GIT_COMMIT_REF,
  });
}

進階設定

保護 Preview 部署

使用 Vercel Authentication：

1. Settings → Deployment Protection
2. 啟用 Vercel Authentication
3. 只有團隊成員能看到 Preview

使用密碼保護：

// middleware.ts
import { NextResponse } from 'next/server';

export function middleware(request) {
  // 只在 Preview 環境啟用
  if (process.env.VERCEL_ENV !== 'preview') {
    return NextResponse.next();
  }

  const authHeader = request.headers.get('authorization');
  if (authHeader !== `Basic ${process.env.PREVIEW_PASSWORD}`) {
    return new Response('Authentication required', {
      status: 401,
      headers: { 'WWW-Authenticate': 'Basic' },
    });
  }

  return NextResponse.next();
}

限制 Preview 分支

如果不想每個分支都產生 Preview：

1. Settings → Git → Ignored Build Step
2. 設定只有特定分支 build

# 只 build feature/ 開頭的分支
if [[ "$VERCEL_GIT_COMMIT_REF" == feature/* ]]; then
  exit 1  # 繼續 build
else
  exit 0  # 跳過
fi

自訂 Preview 行為

// vercel.json
{
  "github": {
    "enabled": true,
    "autoJobCancelation": true,
    "silent": false
  }
}

測試整合

在 Preview 執行測試

# .github/workflows/test.yml
name: Test Preview

on:
  deployment_status:

jobs:
  test:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run E2E tests
        run: |
          npm install
          npx playwright test
        env:
          BASE_URL: ${{ github.event.deployment_status.target_url }}

使用 Playwright

// playwright.config.ts
export default {
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
  },
};

最佳實踐

1. 統一的分支命名

feature/xxx  → 新功能
fix/xxx      → 修復 bug
chore/xxx    → 維護工作

2. 有意義的 commit 訊息

feat: add user login page
fix: resolve navigation bug
refactor: optimize database queries

3. 及時清理舊的 Preview

Vercel 會自動管理，但也可以手動刪除：

1. Deployments 頁面
2. 找到舊的 Preview
3. 點擊刪除

4. 使用 Preview 進行 QA

1. 開發者完成功能
2. 推送並產生 Preview
3. QA 在 Preview 環境測試
4. 通過後 merge 到 main

5. 善用評論功能

• 設計師：標註 UI 問題
• PM：確認功能符合需求
• 開發者：技術討論

常見問題 FAQ

Q1：Preview 會永久保留嗎？

不會。Preview 會在一段時間後自動刪除。

如果需要保留，可以建立正式的部署。

Q2：Preview 消耗額度嗎？

是的。Preview 會計算在 Build 分鐘數和頻寬中。

Hobby 方案有 6,000 Build 分鐘/月。

Q3：如何分享 Preview 給外部人員？

1. 直接分享網址（如果沒有保護）
2. 使用密碼保護 + 分享密碼
3. 暫時關閉 Deployment Protection

Q4：Preview 和 Production 資料分開嗎？

取決於你的設定：

• 如果 Preview 用不同的資料庫 URL → 分開
• 如果用同一個 → 共用

建議 Preview 使用獨立的測試資料庫。

Q5：每個 commit 都會產生 Preview 嗎？

是的，但可以設定跳過某些 build。

Vercel 部署失敗？

Build Error、環境變數、自訂網域，我們幫你快速排除問題。

解決 Vercel 問題

延伸閱讀

• Vercel 是什麼？2025 完整教學｜從入門到部署一次搞懂
• Vercel 部署教學｜從 GitHub 到上線只要 5 分鐘
• Vercel 環境變數設定完整教學
• Vercel 自訂網域設定教學
• Vercel 免費方案完整解析