安装前先确认环境是否匹配

Next.js AI SDK 常用于在 Next.js 项目中接入大模型能力，例如对话生成、文本补全、流式输出和多步骤 AI 工作流。

安装失败并不一定是 SDK 本身问题，更多时候来自以下原因：

• Node.js 版本过低
• 包管理器混用
• 项目依赖冲突
• 环境变量读取错误

建议先确认本地环境：

• Node.js 使用 18.17 以上版本
• Next.js 项目建议为 13.4 以上，若使用 App Router，目录结构应包含 app 目录
• 包管理器 只选择 npm、pnpm 或 yarn 中的一种，避免同一项目同时存在 package-lock.json、pnpm-lock.yaml 和 yarn.lock

如果是新项目，可以先执行 npx create-next-app@latest 创建项目，选择 TypeScript、App Router 和 ESLint。

进入项目目录后再安装 AI SDK，例如使用 npm install ai。若需要接入特定模型服务，还要安装对应 provider 包，例如 npm install @ai-sdk/openai。

使用 pnpm 的项目则执行 pnpm add ai @ai-sdk/openai。安装完成后查看 package.json，确认 dependencies 中已出现 ai 和对应 provider。

安装失败的常见原因与处理步骤

第一类问题：Node 版本不符合要求

终端执行 node -v 查看版本，如果低于要求，建议升级到稳定长期支持版本。升级后关闭终端重新打开，再执行 npm cache verify 或 pnpm store prune 清理缓存，然后重新安装依赖。

第二类问题：锁文件冲突

很多项目从模板复制而来，可能保留了不同包管理器生成的锁文件。处理方式：保留当前实际使用的锁文件，删除其他锁文件和 node_modules 目录，再重新执行安装命令。

例如使用 npm 时保留 package-lock.json，删除 pnpm-lock.yaml、yarn.lock 和 node_modules，然后运行 npm install。

第三类问题：依赖版本不兼容

如果终端提示 peer dependency、ERESOLVE 或 cannot resolve dependency tree，可以先尝试 npm install --legacy-peer-deps。

但这只是临时兼容方案，更推荐检查 Next.js、React、React DOM 的版本是否过旧。对于生产项目，不建议盲目强制安装，应在测试分支中验证页面构建、接口调用和流式响应是否正常。

第四类问题：国内网络环境导致包下载不稳定

可以切换到可信的 npm 镜像源，或在团队内部使用统一的依赖缓存方案。切换源后要注意不要混用多个来源，避免出现同名包版本不一致的情况。

企业项目最好在 package.json 中固定关键依赖版本，减少后续构建漂移。

API Key 配置的标准做法

API Key 是调用模型服务的凭据，不能写在前端页面、组件 props 或可被浏览器读取的变量中。

推荐在项目根目录创建 .env.local 文件，并写入类似 OPENAI_API_KEY=你的密钥 这样的配置。变量名应与 provider 初始化代码保持一致，修改后必须重启开发服务，因为 Next.js 不会总是自动重新读取环境变量。

在服务端路由中读取密钥更安全。以 App Router 为例，可在 app/api/chat/route.ts 中创建接口，服务端通过 process.env.OPENAI_API_KEY 获取配置，再调用 AI SDK。前端页面只向自己的后端接口发送用户输入，不直接接触密钥。这样即使浏览器打开开发者工具，也不会看到完整 Key。

还要区分不同环境的配置：

• 开发环境使用 .env.local
• 测试环境和线上环境应在部署平台的环境变量面板中单独配置
• 不要把 .env.local 提交到代码仓库，.gitignore 中应包含 .env*.local

若团队多人协作，可提供 .env.example，只写变量名和说明，不写真实值。例如 OPENAI_API_KEY=请在本地填写。

一个可复用的最小调用流程

安装完成并配置 API Key 后，可以先搭建最小闭环：

1. 前端输入问题，提交到 /api/chat
2. 服务端调用 AI SDK
3. 接口返回流式文本
4. 前端逐步展示结果

这样做的好处是能快速判断三件事：依赖是否可用、密钥是否有效、模型响应是否能被页面正确消费。

如果使用 AI SDK 的 streamText 能力，服务端应放在 route.ts 中，并确保运行环境支持流式返回。开发时可先用简单 prompt 测试，例如“用三句话解释什么是向量检索”。

若接口返回 401，多半是 API Key 错误或未读取到环境变量；若返回 404，检查模型名称是否写错；若页面一直等待，检查接口是否正确返回响应对象，以及前端是否使用匹配的读取方式。

AI 工作流模板导入思路

所谓 AI 工作流模板，通常是把一个完整业务流程拆成固定节点，例如：输入清洗、意图判断、知识检索、模型生成、格式校验和结果展示。

导入模板时不要急于替换业务代码，建议先在独立分支中验证模板能否跑通，再逐步接入现有项目。

导入步骤可以按以下顺序进行：

1. 下载或复制模板目录，查看 package.json 中的依赖版本
2. 对比当前项目的 Next.js、React 和 AI SDK 版本，避免直接覆盖核心配置
3. 把模板中的 api 路由、components 组件和 lib 工具函数分批迁入
4. 把环境变量合并到 .env.example
5. 在本地运行 npm run dev 或 pnpm dev，先测试模板自带页面，再接入真实业务页面

工作流模板常见目录包括：app/api/workflow/route.ts、lib/ai.ts、lib/prompts.ts、components/chat-panel.tsx。

lib/ai.ts 适合集中初始化 provider，lib/prompts.ts 用于管理提示词，接口路由负责组织调用链，组件层只处理交互和展示。这样后续更换模型、调整提示词或增加审查节点时，不需要大面积修改页面代码。

常见报错排查

报错“Module not found: Can't resolve 'ai'”：说明依赖未安装到当前项目，确认终端所在目录是否正确，再重新安装。

报错“process.env.OPENAI_API_KEY is undefined”：说明变量未生效，检查 .env.local 是否位于项目根目录，变量名是否拼写一致，开发服务是否重启。

报错“Invalid API key”：通常是 Key 填写错误、复制时带入空格，或使用了不匹配的服务商配置。可以重新生成 Key，并只放在服务端环境变量中。

报错“model not found”：应检查模型名称、provider 包版本和账号权限。

报错“Edge runtime does not support certain Node APIs”：说明代码里使用了当前运行环境不支持的 Node 能力，可切换 route 的 runtime，或移除相关依赖。

构建时报 TypeScript 错误时，不建议直接关闭类型检查。应根据报错定位参数类型、返回值类型和消息结构。AI SDK 版本更新后，部分方法签名可能变化，升级前要阅读变更说明，并在锁文件中固定版本，防止团队成员安装到不同版本。

安全边界与实用建议

API Key 必须按最小权限原则管理：

• 不要把同一个 Key 同时用于开发、测试和线上环境
• 不要在浏览器端暴露
• 不要写入日志、截图或报错回传内容
• 若怀疑 Key 泄露，应立即停用并更换，同时检查访问记录和调用量异常

对用户输入也要设置边界。AI 工作流接入真实业务后，应加入长度限制、频率限制、异常重试和超时控制，避免单次请求占用过多资源。

生成结果用于客服、文案或数据处理时，最好增加格式校验和人工确认环节。尤其是涉及价格、合同、医疗建议等高风险场景时，不应完全依赖模型自动输出。

最后，建议把安装、环境变量、启动命令、模板目录说明写入 README。团队协作时统一 Node 版本、包管理器和依赖安装命令，可以显著减少“我这里能跑、你那里失败”的问题。

对于 Next.js AI SDK 项目，最稳妥的路线是：先跑通最小示例，再导入工作流模板，最后接入实际业务逻辑。