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 秒重新验证上游请求,而 sourcemarket_sessiondata_updated_at 会说明缓存汇率实际代表什么。

Key points
EXCHANGERATE_API_KEY 保存在仅服务端可见的环境变量中,不要添加 NEXT_PUBLIC_ 前缀。
使用服务端 fetchnext: { 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 秒。它能减少重复调用,但不会把每日参考汇率变成盘中汇率,因此必须保留 sourcemarket_sessiondata_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