Vercel 500 / 502 / 503 / 504 錯誤排解大全｜完整解決方案

網站突然顯示 500、502、503 或 504 錯誤？

這些都是伺服器端錯誤，代表 Vercel 在處理請求時出了問題。

不同的錯誤代碼代表不同的問題。

這篇文章完整解析每種錯誤的原因和解決方法。

5xx 錯誤代碼速查表

先快速了解每個錯誤代表什麼。

最常遇到的是 500 和 504。

接下來一個一個解決。

500 Internal Server Error 解決方案

500 錯誤代表：你的程式碼在執行時出錯了。

常見原因

1. Serverless Function 程式碼錯誤

// ❌ 會導致 500 錯誤
export async function GET() {
  const data = await fetch(undefined);  // undefined 不是有效的 URL
  return Response.json(data);
}

2. 環境變數未設定

// ❌ 如果 DATABASE_URL 沒設定，會出錯
const db = new Database(process.env.DATABASE_URL);

3. 依賴套件問題

• 套件版本衝突
• 遺漏的依賴
• Node.js 版本不相容

診斷方法

1. 查看 Function Logs

1. 進入 Vercel Dashboard
2. 選擇你的專案
3. 點擊 Logs → Functions
4. 找到出錯的請求，看詳細錯誤訊息

2. 本機測試

# 使用 Vercel CLI 在本機模擬
vercel dev

然後訪問出錯的 API，看本機是否也會報錯。

解決方法

1. 修復程式碼錯誤

根據 Log 顯示的錯誤訊息，修復對應的程式碼。

2. 設定環境變數

1. 進入 Vercel Dashboard → Settings → Environment Variables
2. 加入缺少的環境變數
3. 重新部署

3. 加入錯誤處理

export async function GET() {
  try {
    const data = await fetchData();
    return Response.json(data);
  } catch (error) {
    console.error('API Error:', error);
    return Response.json(
      { error: 'Internal Server Error' },
      { status: 500 }
    );
  }
}

500 錯誤找不到原因？可以聯繫我們讓工程師幫你除錯。

502 Bad Gateway 解決方案

502 錯誤代表：Serverless Function 無法正常啟動。

常見原因

1. Function 啟動失敗

• 依賴套件載入錯誤
• 初始化程式碼出錯
• 記憶體不足

2. 冷啟動問題

Serverless Function 第一次啟動需要時間，如果太慢可能導致 502。

3. 套件太大

Function 的總大小有限制，超過會無法啟動。

診斷方法

檢查 Build Logs 和 Function Logs：

Error: Cannot find module 'xxx'

這類錯誤通常在 Log 中會有明確訊息。

解決方法

1. 確認套件安裝正確

# 清除 node_modules 重新安裝
rm -rf node_modules package-lock.json
npm install

2. 減少 Function 大小

• 不要在 Function 中 import 不必要的大型套件
• 使用 dynamic import
• 分割成多個小 Function

3. 優化初始化程式碼

// ❌ 不好：在模組層級做太多事
const heavyData = loadHeavyData();  // 每次冷啟動都要執行

// ✅ 好：延遲載入
let cachedData = null;
async function getData() {
  if (!cachedData) {
    cachedData = await loadHeavyData();
  }
  return cachedData;
}

503 Service Unavailable 解決方案

503 錯誤代表：服務暫時無法使用。

常見原因

1. Vercel 平台問題

有時候是 Vercel 自己的問題。

2. 超過用量限制

免費方案有各種限制，超過可能導致 503。

3. 區域性問題

特定地區的節點可能有問題。

診斷方法

1. 檢查 Vercel Status

前往 status.vercel.com 看是否有已知問題。

2. 檢查用量

Dashboard → Settings → Usage

看是否超過免費額度。

解決方法

1. 如果是 Vercel 平台問題

等待 Vercel 修復，通常很快。

2. 如果是用量問題

• 升級方案
• 等待下個月額度重置
• 優化程式碼減少資源使用

3. 暫時的解法

// 在前端加入重試邏輯
async function fetchWithRetry(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const res = await fetch(url);
      if (res.ok) return res;
      if (res.status === 503) {
        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
        continue;
      }
      throw new Error(`HTTP ${res.status}`);
    } catch (e) {
      if (i === retries - 1) throw e;
    }
  }
}

504 Gateway Timeout 解決方案

504 錯誤代表：Serverless Function 執行時間超過限制。

這是最常見的 5xx 錯誤之一。

Vercel 的時間限制

超過時間，Vercel 會強制終止 Function，回傳 504。

常見原因

1. 資料庫查詢太慢

// ❌ 這個查詢可能很慢
const allUsers = await db.users.findMany();  // 100 萬筆資料

2. 呼叫外部 API 太慢

// ❌ 如果外部 API 很慢，可能超時
const data = await fetch('https://slow-api.example.com/data');

3. 複雜運算

// ❌ 複雜運算可能超時
for (let i = 0; i < 10000000; i++) {
  // 大量運算
}

解決方法

方法一：優化程式碼

// ✅ 加入分頁，不要一次查詢全部
const users = await db.users.findMany({
  take: 20,
  skip: page * 20,
});

// ✅ 平行處理多個 API 呼叫
const [data1, data2, data3] = await Promise.all([
  fetch('/api/1'),
  fetch('/api/2'),
  fetch('/api/3'),
]);

方法二：升級到 Pro 方案

Pro 方案有 60 秒的限制，是 Hobby 的 6 倍。

方法三：改用非同步處理

把長時間任務改成背景處理：

// 1. 接收請求，立即回傳
export async function POST(request) {
  const taskId = generateTaskId();

  // 把任務丟到背景處理（使用外部服務如 Inngest、Trigger.dev）
  await queueBackgroundTask(taskId, request.body);

  // 立即回傳，不等待完成
  return Response.json({ taskId, status: 'processing' });
}

// 2. 另一個 API 讓前端查詢狀態
export async function GET(request) {
  const taskId = request.url.searchParams.get('taskId');
  const status = await getTaskStatus(taskId);
  return Response.json(status);
}

方法四：使用 Edge Functions

Edge Functions 有不同的限制，某些情況可能更適合。

詳細解法：Vercel 10 秒超時限制怎麼處理？

進階診斷技巧

當基本方法都試過了，用這些進階技巧。

1. 使用 Vercel CLI 除錯

# 安裝 Vercel CLI
npm i -g vercel

# 在本機模擬 Vercel 環境
vercel dev

# 可以看到即時的錯誤訊息

2. 加入詳細 Logging

export async function GET() {
  console.log('[API] Start processing');
  console.log('[API] Env check:', !!process.env.API_KEY);

  try {
    console.log('[API] Fetching data...');
    const data = await fetchData();
    console.log('[API] Data fetched:', data.length, 'items');
    return Response.json(data);
  } catch (error) {
    console.error('[API] Error:', error.message);
    console.error('[API] Stack:', error.stack);
    throw error;
  }
}

然後在 Vercel Dashboard 的 Logs 中查看。

3. 檢查 Request/Response

export async function POST(request) {
  // 印出請求內容
  const body = await request.json();
  console.log('[API] Request body:', JSON.stringify(body));

  // 印出 headers
  console.log('[API] Headers:', Object.fromEntries(request.headers));

  // ... 處理邏輯
}

4. 使用錯誤追蹤服務

整合 Sentry、LogRocket 等服務，自動捕捉錯誤：

import * as Sentry from '@sentry/nextjs';

export async function GET() {
  try {
    // 你的程式碼
  } catch (error) {
    Sentry.captureException(error);
    throw error;
  }
}

錯誤預防最佳實踐

預防勝於治療。

1. 永遠加入錯誤處理

// ✅ 完整的錯誤處理
export async function GET() {
  try {
    const data = await fetchData();
    return Response.json(data);
  } catch (error) {
    console.error('Error:', error);

    // 根據錯誤類型回傳不同狀態碼
    if (error.code === 'TIMEOUT') {
      return Response.json({ error: 'Request timeout' }, { status: 504 });
    }
    if (error.code === 'NOT_FOUND') {
      return Response.json({ error: 'Not found' }, { status: 404 });
    }

    return Response.json({ error: 'Internal error' }, { status: 500 });
  }
}

2. 設定請求超時

// ✅ 給外部 API 呼叫設定超時
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);

try {
  const res = await fetch(url, { signal: controller.signal });
  clearTimeout(timeout);
  return res.json();
} catch (error) {
  if (error.name === 'AbortError') {
    throw new Error('Request timeout');
  }
  throw error;
}

3. 使用快取

// ✅ 快取昂貴的運算結果
import { unstable_cache } from 'next/cache';

const getCachedData = unstable_cache(
  async () => {
    return await expensiveOperation();
  },
  ['my-cache-key'],
  { revalidate: 3600 }  // 1 小時快取
);

4. 監控和警報

設定監控，在問題發生時立即通知：

• Vercel 內建的 Analytics
• 第三方監控服務（Datadog、New Relic）
• 自訂警報（當錯誤率超過閾值時發送通知）

常見問題 FAQ

Q1：怎麼區分是我的問題還是 Vercel 的問題？

1. 檢查 status.vercel.com
2. 如果狀態正常，99% 是你的程式碼問題
3. 嘗試在其他時間、其他地區訪問

Q2：504 超時了但 Pro 方案太貴？

幾個替代方案：

1. 優化程式碼，讓它在 10 秒內完成
2. 改用非同步處理
3. 換到其他平台（Render、Railway）

Q3：錯誤時有時無怎麼辦？

可能是：

1. 冷啟動問題（第一次請求較慢）
2. 外部 API 不穩定
3. 資料量有時多有時少

加入更多 logging 來找出規律。

Q4：怎麼知道是哪個 Function 出錯？

在 Vercel Dashboard → Logs → Functions，可以看到每個請求的詳細資訊，包括：

• 請求的 URL
• 執行時間
• 錯誤訊息

還是無法解決？

如果你嘗試了以上所有方法還是有問題：

1. 收集這些資訊

• 錯誤代碼（500/502/503/504）
• Function Logs 截圖
• 重現步驟
• 專案框架和版本

2. 尋求專業協助

有些問題需要深入分析才能解決。

Vercel 部署失敗？

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

解決 Vercel 問題

延伸閱讀

• Vercel 是什麼？2025 完整教學｜從入門到部署一次搞懂
• Vercel 404 Not Found 完整解決方案
• Vercel Functions 完整教學｜Serverless 入門指南
• Vercel 10 秒超時限制怎麼處理？
• Vercel 免費方案完整解析