#安装与环境

#环境要求

• Node.js 22+（官方在 22 / 24 / 26 上测试；生产建议跟当前 LTS）
• pnpm（官方 Quickstart 默认；npm / bun / yarn 也可以）
• 至少一个密钥：AI_GATEWAY_API_KEY（Gateway）或厂商 Key（如 OPENAI_API_KEY）

AI SDK 7 只支持 ESM。Next.js App Router 项目一般已经是 ESM；纯 Node 脚本请在 package.json 里加 "type": "module"，或使用 .mjs。require('ai') 会失败。

#创建 Next.js 应用（推荐路径）

官方 App Router Quickstart：

pnpm create next-app@latest my-ai-app
cd my-ai-app

提示里选择 App Router 与 Tailwind（可选）。Next.js 细节见本站 Next.js 教程。

#安装 AI SDK 依赖

pnpm add ai @ai-sdk/react zod

直连 OpenAI（不用 Gateway 字符串）时再装：

pnpm add @ai-sdk/openai

#配置密钥

在项目根创建 .env.local（Next.js 会加载；不要提交 Git）：

# Vercel AI Gateway（官方 Quickstart 默认）
AI_GATEWAY_API_KEY=xxxxxxxxx

# 若走 @ai-sdk/openai 直连
OPENAI_API_KEY=sk-...

Gateway 会默认读取 AI_GATEWAY_API_KEY。直连 OpenAI 读取 OPENAI_API_KEY。

Windows PowerShell 里临时设置：

$env:AI_GATEWAY_API_KEY = "xxxxxxxxx"

密钥只出现在 Route Handler / Server Action / Node 脚本，永远不要 NEXT_PUBLIC_ 前缀。

#两种模型写法（务必分清）

1. Gateway（默认全局 Provider） — 字符串即可，无需厂商包：

import { generateText, gateway } from 'ai';

await generateText({
  model: 'openai/gpt-4.1-mini', // 或 gateway('anthropic/claude-sonnet-4.5')
  prompt: 'Say hello in one sentence.',
});

gateway('anthropic/claude-sonnet-4.5') 与字符串等价；也可 import { gateway } from '@ai-sdk/gateway'。

2. 直连 OpenAI — 安装 @ai-sdk/openai：

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

await generateText({
  model: openai('gpt-5.1'), // 官方文档示例 ID；以控制台为准，会变
  prompt: 'Say hello in one sentence.',
});

Gateway 的 "openai/gpt-4.1-mini" 不是 openai('gpt-4.1-mini')。前者走 Gateway 路由；后者走 OpenAI API。混用会连错后端或报「找不到模型」。

#纯 Node 脚本（无 Next.js）

mkdir ai-script && cd ai-script
pnpm init
pnpm add ai

package.json 增加 "type": "module"。用同一套 generateText。聊天 UI 才需要 @ai-sdk/react 与 React。

#项目结构建议

my-ai-app/
├── .env.local          # 密钥，已 gitignore
├── app/
│   ├── api/chat/route.ts
│   └── page.tsx        # 'use client' + useChat
├── package.json
└── tsconfig.json

TypeScript 与 App Router 约定见本站对应教程。

#常见问题

ERR_REQUIRE_ESM / require is not defined？
项目不是 ESM。加 "type": "module"，或只在 Next.js app/ 里用 import。

Node 版本不够？
node -v 必须 ≥ 22。

Gateway 401？
检查 .env.local 文件名、是否重启 pnpm dev、Key 是否属于 AI Gateway。

直连 OpenAI 超时？
国内网络需代理或改用 Gateway / 本地 Ollama（见 Provider）。

#下一步

• 快速上手
• Provider 与模型