OpenAI API 接入 Next.js 怎么做？Route Handler + 流式 + 报错处理完整流程

在 Next.js 里接 OpenAI API，第一条铁律：API Key 只能放服务端，绝不能出现在前端代码或 NEXT_PUBLIC_ 变量里。前端直接调 OpenAI 会把 key 暴露给所有访客，几分钟就被盗刷。正确做法是用 App Router 的 Route Handler 在服务端中转。

第一步：装 SDK + 配 Key

npm install openai

在 .env.local 里配 key（不要加 NEXT_PUBLIC_ 前缀）：

OPENAI_API_KEY=sk-xxxxx

.env.local 必须进 .gitignore，别提交进仓库。

第二步：写服务端 Route Handler

新建 app/api/chat/route.ts，在服务端调用 OpenAI：

import OpenAI from "openai";

export const runtime = "nodejs";
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export async function POST(req: Request) {
  const { messages } = await req.json();
  const completion = await openai.chat.completions.create({
    model: "gpt-4o-mini",      // 以 OpenAI 官方当前可用模型为准
    messages,
  });
  return Response.json({ reply: completion.choices[0].message });
}

前端只 fetch("/api/chat", { method: "POST", body: ... })，key 全程留在服务端。

第三步：流式返回（边生成边显示）

聊天体验的关键是流式（不让用户干等）。开 stream: true，把流转发给前端：

const stream = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages,
  stream: true,
});
const encoder = new TextEncoder();
return new Response(new ReadableStream({
  async start(controller) {
    for await (const chunk of stream) {
      const text = chunk.choices[0]?.delta?.content || "";
      if (text) controller.enqueue(encoder.encode(text));
    }
    controller.close();
  },
}), { headers: { "Content-Type": "text/plain; charset=utf-8" } });

前端用 response.body.getReader() 逐块读，追加到界面。

常见报错和修复

• 401 Incorrect API key provided：key 错、过期、或没读到 → 检查 .env.local 拼写、重启 dev（环境变量启动时才读）。
• 429 Rate limit / insufficient_quota：超频或余额不足 → 看 OpenAI 后台用量；加重试退避；insufficient_quota 是要充值，不是限流。
• key 在前端被暴露：说明你在客户端组件直接调了 OpenAI → 立刻挪到 Route Handler，并在 OpenAI 后台吊销并换新 key。
• 生产 undefined：本地有 .env.local，但 Vercel 没配 → 在 Vercel 环境变量补 OPENAI_API_KEY 并重新部署。

安全清单（上线前必看）

1. key 只在服务端，前端零暴露；
2. .env* 已 gitignore；
3. 加基本的频率限制 / 鉴权，别让 /api/chat 被人白嫖你的额度；
4. 设 OpenAI 后台用量上限，防止被刷爆。

让 Codex 辅助

我在 Next.js App Router 接 OpenAI，报 [贴报错]。
我的 key 放在 .env.local / 前端 / Vercel。请判断是 key、环境变量还是流式处理问题，
给出修复，并确认我的 key 没有暴露在客户端。

风险提醒

• 别把 key 写进代码、截图、或 NEXT_PUBLIC_；一旦泄露立刻吊销换新。
• 帮客户接 API 用客户自己的 key 和账号，别用你的额度承担客户用量。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关 AI 接入

接其他模型 / 管好 key 一起看：

• Claude API 怎么接入 Next.js
• Gemini API 怎么接 Next.js
• AI API Key 怎么安全管理

免责声明

本文 SDK 用法与 Route Handler 形态对应 OpenAI 与 Next.js 的通用行为；具体模型名、价格、限额以 OpenAI 官方文档为准，涉及客户密钥与账单时需明确授权并人工复核。