Cookbook

JavaScript SDK 示例

Q: baseURL 应该写在哪里？

写在服务端环境变量里，并在初始化 SDK 时显式传入。OfApp.cn OpenAI 兼容入口 示例是 https://api.ofapp.cn/v1，如果工具会自动拼接版本路径，要避免重复 /v1。

Q: 应该优先用 Responses 还是 Chat Completions？

新项目可以优先了解 Responses API；但兼容服务是否支持、支持到什么程度，应 以 OfApp.cn 控制台或官方文档为准。排查连通性时，Chat Completions 往往更 简单。

Q: JavaScript SDK 会自动重试吗？

会对部分网络、408、409、429 和 5xx 错误做有限重试。生产环境仍应显式设置 maxRetries、timeout，并避免对 401、403、404 做无意义重试。

Q: 边缘运行时可以用吗？

要看运行时对环境变量、fetch、流式响应和超时的支持。上线前需要在目标平台 验证，不能只看本地 Node.js 成功。

Q: OfApp.cn 支持哪些 JavaScript SDK 参数？

请以 OfApp.cn 控制台或官方文档为准。OpenAI-compatible API 通常能复用常见 请求形态，但不代表每个模型、参数、端点和返回字段都完全一致。

OpenAI JavaScript SDK 接入 OfApp.cn 教程，覆盖 Node.js 服务端、baseURL、API Key、Responses、Chat Completions、流式输出、错误处理、重试和日志脱敏。

预计阅读: 6 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

JavaScript SDK 示例适合把 AI 能力接进 Node.js 服务端、CLI、Next.js API Route、后台任务和自动化脚本。它不是给浏览器组件直接调用的代码片段：API Key 必须留在服务端，前端页面只能调用你自己的后端接口。

本文示例基于 OfApp.cn 的 OpenAI 兼容接口写法。Base URL 使用 https://api.ofapp.cn/v1，真实模型、价格、额度、套餐和可用能力，请以 OfApp.cn 控制台或官方文档为准。

页面摘要

项目	内容
适合人群	Node.js 服务端、CLI、Next.js API Route、后台任务和自动化脚本开发者
阅读时间	约 6 分钟
核心问题	如何用 OpenAI JavaScript SDK 接入 OfApp.cn OpenAI 兼容入口
你会得到	环境变量模板、客户端初始化、Responses 与 Chat Completions 示例、流式输出、错误处理和上线检查
安全边界	API Key 只放服务端环境变量或 Secret；真实模型、价格、额度和能力请以 OfApp.cn 控制台或官方文档为准

适合谁读

读者	正在做什么	读完能完成什么
全栈开发者	给网站后台加 AI 摘要、改写、分类能力	在服务端封装 OpenAI JavaScript SDK
Node.js 用户	写 CLI、脚本或定时任务	用环境变量跑通最小请求
Next.js 开发者	想在 API Route 或 Server Action 调模型	避免把 API Key 暴露到浏览器
团队维护者	需要上线可排查的 AI 接口	加上错误处理、超时、重试和脱敏日志
正在迁移的人	从直连 OpenAI 改到 OpenAI-compatible API	理解 `baseURL`、模型名和端点边界

如果只是临时验证一句话，先看 curl 示例。JavaScript SDK 更适合重复调用、服务端封装和需要接入业务系统的场景。

接入流程图

这张图的重点是顺序。先跑通最小请求，再加流式输出、错误重试和业务封装。若最小请求失败，优先排查 API Key、Base URL、模型名和网络，而不是重写业务代码。

前置条件

npm install openai

export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_API_KEY="sk-xxxx"
export OPENAI_MODEL="以 OfApp.cn 控制台可用模型为准"

环境变量	作用	注意
`OPENAI_API_KEY`	给请求做鉴权	真实 Key 不写进代码、前端、日志和截图。
`OPENAI_BASE_URL`	指向 API 入口	OfApp.cn OpenAI 兼容入口示例为 `https://api.ofapp.cn/v1`。
`OPENAI_MODEL`	指定模型	从控制台复制，不凭记忆猜。

OpenAI JavaScript SDK 可以读取 OPENAI_API_KEY；接入 OfApp.cn 这类兼容入口时，建议显式传入 baseURL，让代码和部署环境一眼能看出请求会发往哪里。

初始化客户端

把 SDK 初始化集中放在一个服务端文件里，不要散落在页面组件或多个业务函数中。

import OpenAI from "openai";

export const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
  maxRetries: 2,
  timeout: 60 * 1000,
});

配置	建议
`apiKey`	使用服务端环境变量。
`baseURL`	OfApp.cn 示例为 `https://api.ofapp.cn/v1`。
`maxRetries`	对网络、429、5xx 等可重试错误保持有限重试。
`timeout`	按业务设置超时，避免请求一直挂起。

不要为了省事把 dangerouslyAllowBrowser 打开给普通前端页面用。这个选项会让浏览器端代码携带密钥，只有在非常受控的内部或临时调试场景才可能考虑。

SDK 调用方式选择

同一个 JavaScript SDK 可以调用不同端点，也可以用于不同运行位置。接入前先选清楚路径，后面的代码会更稳定。

目标	建议路径	适合场景	先验证什么
新项目生成文本	`client.responses.create()`	文本生成、总结、结构化任务探索	OfApp.cn 当前是否支持对应端点和模型
兼容性优先	`client.chat.completions.create()`	OpenAI-compatible API、旧项目迁移、连通性验证	Key、Base URL、模型名和 messages 格式
聊天 UI 或 CLI 输出	`stream: true`	逐字输出、长文本、命令行助手	非流式请求先成功，SSE 链路不被代理缓冲
Web 产品接入	服务端路由封装 SDK	Next.js API Route、后端服务、管理后台	前端不接触 Key，后端有鉴权、限流和日志脱敏
批处理和定时任务	Node.js 脚本或队列 Worker	批量摘要、分类、改写、数据清洗	超时、重试、失败重跑和成本边界

Responses 最小请求

OpenAI JavaScript SDK 文档把 Responses API 作为生成文本的主要路径。兼容服务是否支持 Responses API，需要以 OfApp.cn 控制台或官方文档为准。若支持，可以用下面的最小请求验证。

import { client } from "./client.js";

const response = await client.responses.create({
  model: process.env.OPENAI_MODEL,
  input: "用一句话解释什么是 AI 知识库。",
});

console.log(response.output_text);

如果返回结构和示例不同，先不要假设 SDK 写错。兼容服务可能支持不同端点或不同响应字段，排查时应回到 OpenAI-compatible API 快速开始。

Chat Completions 最小请求

Chat Completions 字段少，适合做连通性验证，也是很多 OpenAI-compatible API 保留的稳定路径。

import { client } from "./client.js";

const completion = await client.chat.completions.create({
  model: process.env.OPENAI_MODEL,
  messages: [
    {
      role: "user",
      content: "生成一句中文测试回复。",
    },
  ],
});

console.log(completion.choices[0]?.message?.content);

第一次接入时，不要同时加入 tools、JSON schema、图片、stream 和复杂业务 Prompt。最小请求成功后，再逐项增加能力。

流式输出

流式输出适合聊天 UI、CLI 工具和长文本生成，但排错成本更高。建议先用非流式请求验证连通，再打开 stream。

const stream = await client.chat.completions.create({
  model: process.env.OPENAI_MODEL,
  stream: true,
  messages: [{ role: "user", content: "分三点说明 JavaScript SDK 接入步骤。" }],
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

现象	排查方向
非流式成功，流式失败	看代理、网关、SSE 转发和客户端读取。
中途断开	记录已输出内容、请求耗时、网络环境和状态码。
前端收不到片段	后端是否缓冲、压缩或一次性返回。
CLI 无输出	是否没有处理 delta，或模型暂未返回内容片段。

更多流式处理可以看 OpenAI API 流式输出示例。

服务端接口封装

在 Web 项目里，前端应该调用你自己的服务端接口，由服务端再调用 OfApp.cn。下面是一个简化的 Node.js 处理函数结构。

import { client } from "./client.js";

export async function summarizeText(input) {
  if (!input || input.length > 20_000) {
    throw new Error("输入为空或过长");
  }

  const completion = await client.chat.completions.create({
    model: process.env.OPENAI_MODEL,
    messages: [
      {
        role: "system",
        content: "你是严谨的中文摘要助手，只基于用户材料总结。",
      },
      {
        role: "user",
        content: input,
      },
    ],
  });

  return completion.choices[0]?.message?.content ?? "";
}

层级	负责什么	不应做什么
前端页面	收集输入、展示结果、处理加载状态	持有 API Key。
服务端路由	鉴权、限流、调用任务函数	直接把完整错误和密钥返回给浏览器。
AI 客户端	读取环境变量，发起 SDK 请求	写死模型价格、未确认能力或真实 Key。
业务函数	组织 Prompt、校验输入、解析输出	跳过人工复核和日志脱敏。

错误处理

OpenAI JavaScript SDK 会在连接失败、4xx 或 5xx 响应时抛出错误。实际接入兼容服务时，建议记录状态码、错误类型、请求 ID 和脱敏配置。

import OpenAI from "openai";
import { client } from "./client.js";

try {
  const completion = await client.chat.completions.create({
    model: process.env.OPENAI_MODEL,
    messages: [{ role: "user", content: "ping" }],
  });
  console.log(completion.choices[0]?.message?.content);
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error("AI request failed", {
      status: error.status,
      name: error.name,
      requestId: error.request_id,
      message: error.message,
    });
  } else {
    console.error("Unexpected AI client error", {
      name: error?.name,
      message: error?.message,
    });
  }
}

状态	SDK 错误类型方向	排查
401	鉴权错误	检查 Key、Bearer 头、环境变量加载。
403	权限错误	检查账号权限和服务商策略。
404	未找到	检查 Base URL、`/v1`、端点和模型名。
429	限流	降低并发，使用有限退避。
5xx	服务端或链路临时错误	记录请求 ID，有限重试。
连接错误	网络、DNS、代理	用 cURL 在同一机器复现。

错误页可以从 API 错误排查中心进入，逐个状态码排查。

重试、超时和日志

OpenAI JavaScript SDK 默认会对部分可重试错误进行有限重试，包括连接问题、 408、409、429 和 5xx。上线时仍建议把策略写清楚，不要让调用无限重试。

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
  maxRetries: 2,
  timeout: 30 * 1000,
});

项目	建议
重试	对 429、5xx、网络中断有限重试；对 401、403、404 不盲目重试。
超时	给用户交互设置较短超时，后台任务可适当放宽。
日志	记录状态码、请求 ID、耗时、模型名脱敏值和业务任务名。
调试日志	不在生产环境打开过细日志，避免请求体和响应体泄露。
请求 ID	出错时保留，方便和服务商或内部日志对齐。

如果使用 OfApp.cn，模型名、额度、可用能力和价格仍以控制台或官方文档为准。不要在代码里写死这些易变信息。

上线前检查清单

检查项	通过标准
环境变量	生产环境能读取 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 和 `OPENAI_MODEL`，但日志不打印真实值。
最小请求	在目标部署环境跑过一次非流式请求，确认不是只在本机成功。
超时和重试	交互式接口有明确超时，429、5xx 和网络错误只做有限重试。
前端边界	浏览器包、页面源码、localStorage、错误上报里都没有 API Key。
日志脱敏	记录状态码、请求 ID、耗时和任务名，不记录完整 Prompt、Key 或用户隐私材料。
人工复核	摘要、分类、改写、代码生成等结果进入业务前有复核或回滚路径。

常见错误速查

现象	更可能原因	处理方式
`process.env.OPENAI_API_KEY` 为空	环境变量没有加载	打印脱敏配置，确认运行进程已重启。
浏览器报错或暴露 Key	在客户端组件里调用 SDK	改为服务端路由或后端服务。
401	Key 错误或未传鉴权	看 401 Unauthorized。
404	Base URL、`/v1` 或端点错误	看 404 Not Found。
`model not found`	模型名不可用或无权限	从 OfApp.cn 控制台重新复制。
timeout	网络、代理、服务端耗时	设置超时，必要时改为后台任务。
stream 中断	SSE 传输或网关问题	先验证非流式，再看 OpenAI API 流式输出示例。

常见问题

可以在 React 组件里直接调用 SDK 吗？

不建议。浏览器端代码会暴露 API Key。应在服务端路由、后端服务、Server Action 或 CLI 中调用 SDK，再把处理后的结果返回给前端。

`baseURL` 应该写在哪里？

写在服务端环境变量里，并在初始化 SDK 时显式传入。OfApp.cn OpenAI 兼容入口示例是 https://api.ofapp.cn/v1，如果工具会自动拼接版本路径，要避免重复 /v1。

应该优先用 Responses 还是 Chat Completions？

新项目可以优先了解 Responses API；但兼容服务是否支持、支持到什么程度，应以 OfApp.cn 控制台或官方文档为准。排查连通性时，Chat Completions 往往更简单。

JavaScript SDK 会自动重试吗？

会对部分网络、408、409、429 和 5xx 错误做有限重试。生产环境仍应显式设置 maxRetries、timeout，并避免对 401、403、404 做无意义重试。

如何记录日志才安全？

记录状态码、错误类型、请求 ID、耗时、任务名和脱敏模型名。不要记录完整 API Key、Authorization header、用户隐私内容、内部 URL 和未脱敏请求体。

边缘运行时可以用吗？

要看运行时对环境变量、fetch、流式响应和超时的支持。上线前需要在目标平台验证，不能只看本地 Node.js 成功。

OfApp.cn 支持哪些 JavaScript SDK 参数？

请以 OfApp.cn 控制台或官方文档为准。OpenAI-compatible API 通常能复用常见请求形态，但不代表每个模型、参数、端点和返回字段都完全一致。

如何用 OpenAI SDK 接入：从 JavaScript 和 Python 两条 SDK 路径理解整体接入。
OpenAI-compatible API 快速开始：先用 cURL 排除连接问题。
curl 示例：不用 SDK 直接验证 HTTP 请求。
Responses API 示例：理解 Responses 风格调用。
Chat Completions 示例：继续使用聊天补全路径。
Streaming 示例：处理 SSE 和流式输出。
错误重试示例：为 429、5xx 和网络中断添加退避。
常见错误排查：按 Key、Base URL、模型和网络分层定位。

资料来源

OfApp.cn 官方接入说明：核对 API Key、Base URL、Bearer 鉴权和 /v1 入口相关信息。
OfApp.cn 首页：核对 OfApp.cn 面向 OpenAI、Codex、GPT Image、Claude 和 AI 客户端的入口语境。
天才游乐场：核对普通用户从网页入口体验模型、图片和 Key 配置的上下文。
OpenAI API SDKs and CLI 文档：参考 SDK 安装、环境变量和 API Key 读取方式。
OpenAI API 认证文档：参考 Bearer 鉴权和服务端密钥保护原则。

带走什么

JavaScript SDK 接入 OfApp.cn 的关键不是复制一段示例，而是建立服务端调用秩序：环境变量保存 Key、baseURL 指向统一入口、模型名以控制台为准、最小请求先跑通，再加流式输出、错误处理、重试、日志和业务封装。前端只调用自己的后端接口，不直接持有 API Key。