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

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

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

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

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


5xx 錯誤代碼速查表

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

錯誤代碼 名稱 常見原因 緊急程度
500 Internal Server Error 程式碼錯誤、環境變數問題 高
502 Bad Gateway Function 啟動失敗 高
503 Service Unavailable 服務過載、維護中 中
504 Gateway Timeout Function 執行超時 高

最常遇到的是 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 的時間限制

方案 Serverless Function Edge Function
Hobby 300 秒(預設即上限) 須 25 秒內開始回應,可串流至 300 秒
Pro 預設 300 秒,最大可設 800 秒,另有 1800 秒延伸方案(Beta) 須 25 秒內開始回應,可串流至 300 秒
Enterprise 預設 300 秒,最大可設 800 秒,另有 1800 秒延伸方案(Beta) 須 25 秒內開始回應,可串流至 300 秒

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

2026 年更新:Vercel 已把 Hobby 方案的預設執行時間從舊制的 10 秒大幅提升到 300 秒(即該方案上限),Pro/Enterprise 則可再往上調整。同時請確認你的專案有沒有啟用 Fluid compute(新專案預設開啟):2025 年 4 月 23 日之前建立、且未啟用 Fluid compute 的舊專案,限制仍是 Hobby 預設 10 秒/最大 60 秒、Pro 15 秒/最大 300 秒、Enterprise 15 秒/最大 900 秒——如果你遇到的真的是 10 秒就被砍斷,多半是這個原因。

常見原因

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/Enterprise 預設執行時間跟 Hobby 一樣都是 300 秒,差別在於可以再往上設定到最多 800 秒(Pro 與 Enterprise 另有 1800 秒 Beta 延伸方案),Hobby 則無法調高。

方法三:改用非同步處理

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

// 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 Function 執行時間限制怎麼處理?


進階診斷技巧

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

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. 優化程式碼,讓執行時間控制在 300 秒內(Hobby 預設上限)
  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 問題


延伸閱讀

分享文章:
V

VibeFix

專門解決 AI Vibe Coding 後的疑難雜症,讓你的專案順利上線。

這篇文章有幫到你嗎?

如果還有問題,讓我們直接幫你解決!

聯繫我們