Netlify 502 Bad Gateway 錯誤完整解決指南【2025】

網站好好的，突然出現 502 Bad Gateway。訪客看到一片空白，你開始緊張。這個錯誤到底是什麼意思？要怎麼修？

這篇文章會把 Netlify 上的 502 錯誤從頭到尾解釋清楚，包含所有可能的原因和對應的解決方法。照著做，應該能讓你的網站恢復正常。

502 錯誤是什麼意思？

先搞懂這個錯誤代表什麼。

502 Bad Gateway 的定義

502 是 HTTP 狀態碼，表示「上游伺服器出問題了」。

用白話說：Netlify 的 CDN 嘗試取得你的網頁內容，但負責處理的伺服器沒有正確回應。

在 Netlify 上，502 通常代表

1. Serverless Function 出問題
   - 執行超時
   - 程式碼有 bug
   - 記憶體不足

2. 後端服務無回應
   - API 伺服器掛了
   - 資料庫連線失敗

3. 設定錯誤
   - Redirect 設定錯誤
   - Edge Function 問題

502 vs 其他錯誤

常見原因分析

Netlify 上出現 502 的幾個主要原因。

原因一：Serverless Function 超時

這是最常見的原因。

Netlify Function 的時間限制：
| 方案 | 時間限制 |
|------|----------|
| Starter（免費）| 10 秒 |
| Pro | 26 秒 |
| Background Functions | 15 分鐘 |

各方案的完整額度可以看 Netlify 免費方案解析。

如果你的 Function 執行超過限制時間，就會回傳 502。

容易超時的操作：
- 呼叫很慢的外部 API
- 大量資料處理
- 資料庫查詢太複雜
- 沒有設定 timeout 的 HTTP 請求

原因二：Function 程式碼錯誤

Function 裡面有 bug，執行到一半掛掉。

常見的程式碼問題：

// 錯誤：沒有處理 null
const data = await fetch(url);
const json = await data.json();
console.log(json.user.name); // 如果 user 是 null 會爆炸

// 錯誤：Promise 沒有正確處理
exports.handler = async (event) => {
  doSomethingAsync(); // 沒有 await，Function 可能提早結束
  return { statusCode: 200 };
};

原因三：記憶體不足

Netlify Function 的記憶體限制是 1024MB。如果處理大量資料，可能會超過。

容易吃記憶體的操作：
- 處理大型 JSON
- 圖片處理
- 讀取大檔案
- 沒有釋放資源

原因四：外部服務問題

Function 呼叫的外部服務沒有回應。

常見情況：
- 資料庫連線池用完
- 第三方 API 掛了
- DNS 解析失敗
- 網路延遲太高

原因五：Edge Function 問題

如果用了 Edge Functions，也可能是這裡出問題。

Edge Function 的限制：
- 執行時間較短
- 不支援所有 Node.js API
- 記憶體限制更嚴格

原因六：Build 或設定問題

有時候不是 Function 的問題，而是部署設定錯誤。

可能的設定問題：
- netlify.toml 設定錯誤
- Redirect 形成無限迴圈
- 環境變數沒設定
- 網域設定錯誤（參考 Netlify 自訂網域教學）

診斷方法

怎麼找出問題在哪？

步驟一：看 Function Logs

1. 登入 Netlify 後台
2. 選擇你的網站
3. 點「Functions」
4. 選擇有問題的 Function
5. 看「Logs」分頁

Logs 會顯示：
- Function 是否被呼叫
- 執行了多久
- 有沒有錯誤訊息
- 是否超時

步驟二：檢查 Deploy Logs

1. 點「Deploys」
2. 選擇最近的部署
3. 點開查看詳細 log

看看有沒有：
- Build 錯誤
- 警告訊息
- 環境變數問題

步驟三：本地測試

用 Netlify CLI 在本地測試：

# 安裝 CLI
npm install -g netlify-cli

# 登入
netlify login

# 本地執行
netlify dev

本地執行可以更容易 debug，因為可以看到完整的錯誤堆疊。

步驟四：檢查 Netlify Status

有時候是 Netlify 本身出問題。

檢查 Netlify Status Page，看看有沒有服務中斷。

步驟五：測試外部服務

如果 Function 有呼叫外部 API，單獨測試那些 API：

curl -X GET https://api.example.com/endpoint

確認外部服務正常運作。

各情境解決方案

針對不同原因的解決方法。

解決 Function 超時

方法一：優化程式碼

// 不好：串行呼叫
const user = await getUser(id);
const orders = await getOrders(id);
const reviews = await getReviews(id);

// 好：平行呼叫
const [user, orders, reviews] = await Promise.all([
  getUser(id),
  getOrders(id),
  getReviews(id),
]);

方法二：設定請求 timeout

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);

try {
  const response = await fetch(url, {
    signal: controller.signal,
  });
  clearTimeout(timeout);
  return response;
} catch (error) {
  if (error.name === 'AbortError') {
    // 處理超時
  }
  throw error;
}

方法三：使用 Background Functions

如果處理真的需要很長時間，改用 Background Functions：

// netlify/functions/long-task-background.js
exports.handler = async (event, context) => {
  // 這個 Function 可以跑 15 分鐘
  await veryLongProcess();
  return { statusCode: 200 };
};

注意：Background Functions 需要 Pro 方案。想了解 Pro 方案的費用？看這篇 Netlify 費用計算指南。

解決程式碼錯誤

方法一：加上錯誤處理

exports.handler = async (event, context) => {
  try {
    const data = JSON.parse(event.body);
    const result = await processData(data);
    return {
      statusCode: 200,
      body: JSON.stringify(result),
    };
  } catch (error) {
    console.error('Function error:', error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message }),
    };
  }
};

方法二：檢查 null/undefined

// 使用 optional chaining
const name = json?.user?.name ?? 'Unknown';

// 或者明確檢查
if (!data || !data.user) {
  return { statusCode: 400, body: 'Invalid data' };
}

方法三：記得 await

// 確保所有 async 操作都有 await
exports.handler = async (event, context) => {
  await saveToDatabase(data); // 記得 await
  await sendEmail(user);      // 記得 await
  return { statusCode: 200 };
};

解決記憶體問題

方法一：分批處理大資料

// 不好：一次載入所有資料
const allData = await fetchAllRecords(); // 可能很大

// 好：分批處理
const batchSize = 100;
let offset = 0;
while (true) {
  const batch = await fetchRecords(offset, batchSize);
  if (batch.length === 0) break;
  await processBatch(batch);
  offset += batchSize;
}

方法二：使用 stream

// 對於大檔案，使用 stream 而不是一次讀取
const { Readable } = require('stream');
// ... stream 處理邏輯

解決外部服務問題

方法一：加上重試機制

async function fetchWithRetry(url, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url);
      if (response.ok) return response;
    } catch (error) {
      if (i === retries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * (i + 1)));
    }
  }
}

方法二：設定 fallback

async function getData() {
  try {
    return await fetchFromAPI();
  } catch (error) {
    console.error('API failed, using cache');
    return getCachedData();
  }
}

解決設定問題

檢查 netlify.toml

# 確保格式正確
[build]
  command = "npm run build"
  publish = "dist"

# 檢查 redirect 沒有形成迴圈
[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

檢查環境變數

1. 去 Site settings > Environment variables
2. 確認必要的變數都有設定
3. 確認值是正確的

預防措施

怎麼避免再次發生 502？

設定監控

方法一：用 Netlify 的監控

Pro 方案有 Analytics，可以看到錯誤率。

方法二：用外部監控服務

• UptimeRobot（免費）
• Pingdom
• Better Uptime

設定定期檢查你的網站，出問題時通知你。

加上健康檢查

建立一個簡單的健康檢查 endpoint：

// netlify/functions/health.js
exports.handler = async () => {
  // 檢查關鍵服務
  try {
    await checkDatabase();
    await checkExternalAPI();
    return { statusCode: 200, body: 'OK' };
  } catch (error) {
    return { statusCode: 503, body: error.message };
  }
};

設定 Rate Limiting

避免 Function 被濫用：

const rateLimit = new Map();

exports.handler = async (event) => {
  const ip = event.headers['x-forwarded-for'];
  const now = Date.now();
  const limit = rateLimit.get(ip) || { count: 0, reset: now + 60000 };

  if (now > limit.reset) {
    limit.count = 0;
    limit.reset = now + 60000;
  }

  if (limit.count >= 100) {
    return { statusCode: 429, body: 'Too many requests' };
  }

  limit.count++;
  rateLimit.set(ip, limit);

  // 正常處理...
};

寫好的錯誤處理

每個 Function 都要有完整的錯誤處理：

exports.handler = async (event, context) => {
  const startTime = Date.now();

  try {
    // 驗證輸入
    if (!event.body) {
      return { statusCode: 400, body: 'Missing body' };
    }

    // 處理邏輯
    const result = await processRequest(event);

    // 記錄成功
    console.log(`Success in ${Date.now() - startTime}ms`);
    return { statusCode: 200, body: JSON.stringify(result) };

  } catch (error) {
    // 記錄錯誤
    console.error(`Error after ${Date.now() - startTime}ms:`, error);

    // 回傳友善的錯誤訊息
    return {
      statusCode: 500,
      body: JSON.stringify({ error: 'Internal server error' }),
    };
  }
};

常見問題 FAQ

502 錯誤會影響 SEO 嗎？

會。如果 Google 爬蟲遇到 502，可能會認為網站有問題。偶爾一次沒關係，但持續出現會影響排名。

怎麼知道是 Function 還是其他問題？

看 URL。如果是 /.netlify/functions/xxx 或 /api/xxx（有設定 redirect），大概率是 Function 問題。如果是一般頁面，可能是 Edge Function 或設定問題。如果是 Next.js 專案，可以參考 Next.js 部署到 Netlify 教學。

免費方案的 10 秒夠用嗎？

對簡單的操作夠用（讀取資料庫、呼叫快速的 API）。但如果要處理圖片、寄送 email、複雜計算，可能不夠。

可以延長 Function 的超時時間嗎？

升級到 Pro 可以有 26 秒。需要更長時間的話，要用 Background Functions（15 分鐘）。

502 跟 504 差在哪？

502 是上游伺服器回傳錯誤回應。504 是上游伺服器沒回應（完全超時）。處理方式差不多，都要檢查 Function 和外部服務。

網站突然 502，我什麼都沒改？

可能是：
1. 外部 API 掛了
2. Netlify 服務中斷
3. 達到用量限制
4. 程式碼有時間相關的 bug（例如憑證過期）

Netlify 502 錯誤排查重點整理

Netlify 502 錯誤大部分是 Serverless Function 造成的。解決步驟：

1. 看 Function Logs：找出是哪個 Function 出問題
2. 確認錯誤類型：超時、程式碼錯誤、還是外部服務問題
3. 針對原因修復：優化程式碼、加上錯誤處理、設定 fallback
4. 加上預防措施：監控、健康檢查、Rate Limiting

遇到 502 不用慌，按照這個流程排查，通常都能解決。

想了解更多 Netlify？看這篇 Netlify 完整指南。

VibeFix 是專門幫助非工程師處理程式部署問題的服務。AI 幫你寫代碼，我們幫你上線。

Netlify 錯誤排不掉？Function 一直出問題？讓 VibeFix 幫你診斷修復