Tutorial/Next.js 與 TypeScript

在 Next.js 與 TypeScript 使用匯率

從 Next.js Server Component 取得即時匯率，把 API 密鑰留在伺服器，並在快取回應時保留底層匯率的實際更新時間。

MMexchangerate.dev·Jul 17, 2026·6 分鐘閱讀

請從 Server Component 或 Route Handler 呼叫 exchangerate.dev，不要把密鑰放進瀏覽器程式碼。Next.js 可每 60 秒重新驗證上游請求，而 source、market_session 與 data_updated_at 會說明快取匯率的實際狀態。

Key points
把 EXCHANGERATE_API_KEY 保存在只供伺服器使用的環境變數，不要加上 NEXT_PUBLIC_。
使用伺服器端 fetch 與 next: { revalidate: 60 }，避免每次瀏覽都呼叫上游。
顯示 data_updated_at，不要把回應 timestamp 當成市場觀測的新鮮度。
指示性匯率用於展示與分析，最終結算金額由付款服務商決定。

從伺服器端取得匯率

Server Component 不在瀏覽器執行，因此可讀取私人環境變數。此例只請求 USD 對 EUR 與 GBP，檢查 HTTP 狀態並回傳有類型的 JSON。

typescript · app/page.tsxcopy
type LatestRates = {
  base: string;
  source: "live" | "ecb_daily" | "fred_daily";
  market_session: string;
  data_updated_at: string;
  rates: Record<string, number>;
};

async function getRates(): Promise<LatestRates> {
  const apiKey = process.env.EXCHANGERATE_API_KEY;
  if (!apiKey) throw new Error("EXCHANGERATE_API_KEY is missing");

  const response = await fetch(
    "https://api.exchangerate.dev/v1/latest/USD?symbols=EUR,GBP",
    {
      headers: { Authorization: `Bearer ${apiKey}` },
      next: { revalidate: 60 },
    },
  );

  if (!response.ok) {
    throw new Error(`FX request failed: ${response.status}`);
  }

  return response.json() as Promise<LatestRates>;
}

export default async function Page() {
  const fx = await getRates();

  return (
    <main>
      <p>1 USD = {fx.rates.EUR} EUR</p>
      <small>
        {fx.source} · {fx.market_session} · updated {fx.data_updated_at}
      </small>
    </main>
  );
}

快取請求，同時保留觀測時間

next: { revalidate: 60 } 把上游請求的快取壽命限制為 60 秒。它會減少重複呼叫，但不會把每日參考匯率變成盤中匯率，因此必須保留 source、market_session 與 data_updated_at。

不要公開密鑰
以 NEXT_PUBLIC_ 開頭的環境變數可能進入瀏覽器套件。請只在伺服器程式碼讀取 EXCHANGERATE_API_KEY。匿名呼叫適合快速測試，正式環境應使用密鑰。

分開展示貨幣與結算貨幣

商店可用指示性匯率顯示約數本地價格。最終扣款應由付款服務商提供，因為費用、點差、四捨五入及結算時間都會改變可執行金額。

  • 把 API 密鑰留在伺服器。
  • 只快取成功回應，不快取 401 或 429。
  • 需要判斷新鮮度時顯示來源與觀測時間。
  • 以原來的商品價格和貨幣作為結算依據。
MM
exchangerate.dev
為使用外匯數據的開發者而設的整合指南。

Keep reading

Tutorial在 JavaScript 與 Node.js 進行貨幣換算Read Reference閱讀 source 與 market_sessionRead Guide指示性匯率與可執行匯率Read