大模型Node.js SDK入门：从安装到首次调用的完整步骤
如果你已经有一个 Node.js 项目，想调用大模型接口，最省事的方式通常是装一个官方或兼容的 SDK，而不是自己拼 HTTP 请求。
本文按顺序讲清：环境怎么准备、密钥怎么放、代码怎么写、报错怎么查，最后如何确认调用真的成功。
先确认运行环境和密钥
开始前需要两样东西：可用的 Node.js 环境，以及一个大模型平台签发的 API Key。
Node.js 建议使用仍在维护的 LTS 版本，用下面命令确认：
node -v
npm -v如果版本过低，先升级 Node.js 再继续。
API Key 不要写死在代码里，后面统一用环境变量读取。
在项目根目录初始化并安装 SDK。
以常见的 OpenAI 兼容 SDK 为例：
npm init -y
npm install openai不同厂商的 SDK 包名可能不同，安装前先看对应平台文档里的包名和基础地址，不要照搬别人的包名。
把密钥放进环境变量
在项目根目录新建 .env 文件，写入：
MODEL_API_KEY=你的密钥
MODEL_BASE_URL=平台提供的基础地址同时把 .env 加入 .gitignore，避免密钥被提交到仓库。
安装读取环境变量的依赖：
npm install dotenv这样密钥与代码分离，换环境时只改配置文件，不用动业务代码。
编写第一次调用代码
新建 index.js，按下面结构编写：
import 'dotenv/config';
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.MODEL_API_KEY,
baseURL: process.env.MODEL_BASE_URL,
});
const res = await client.chat.completions.create({
model: '平台提供的模型名',
messages: [{ role: 'user', content: '用一句话解释什么是环境变量' }],
});
console.log(res.choices[0].message.content);如果项目是 CommonJS，把前两行换成 require 写法即可。
运行：
node index.js终端能打印出模型回复，说明 SDK 安装和鉴权都通了。
调用失败时先查这几项
报错不要急着改代码，按顺序排查通常最快：
- 401 或鉴权失败：检查 Key 是否复制完整、是否带多余空格，以及环境变量是否真的被加载。
- 404 或模型不存在：核对
baseURL和model名称是否与平台文档一致，注意有些平台需要带版本路径。 - 超时或连接失败：确认服务器能访问外网，必要时检查代理和防火墙出站规则。
- 返回内容为空：先打印完整
res对象，确认返回结构，而不是只取choices[0]。
另外，SDK 通常支持设置超时和重试参数。
生产环境建议显式设置超时时间，避免请求一直挂起。
验证调用结果是否可靠
跑通一次不代表稳定。
建议做三项验证：连续调用 3 到 5 次，确认都能返回；
故意填错 Key，确认程序能捕获并输出可读错误；
把调用封装成函数，检查异常时不会让进程直接退出。
确认无误后，再把调用逻辑接入业务代码。
密钥继续放在环境变量中，不要写进前端代码或公开仓库。
常见疑问
SDK 和直接发 HTTP 请求有什么区别？
SDK 帮你处理了鉴权头、请求格式和错误类型，代码更短；直接发请求则依赖更少。新手优先用 SDK。
可以在浏览器前端直接调用吗？
不建议。密钥会暴露给用户，应由后端中转请求。
换模型需要改很多代码吗？
只要平台兼容同一套接口，通常改 model 和 baseURL 即可，业务代码基本不动。
按本文顺序完成安装、配置、调用和验证，你就完成了大模型 Node.js SDK 使用的第一次落地。
后续接入流式输出、多轮对话或函数调用时，都建立在这个基础之上。
