Claude API TypeScript / Node.js 快速上手：安装 @anthropic-ai/sdk、第一个请求、流式、重试与超时

本文根据 Claude 官方《TypeScript SDK》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。代码里的模型名取自官方当天示例，请以官方模型页为准。本站（bigolab.com）不是 Anthropic 官方网站。API 是按用量计费的独立服务，与 Claude 订阅分开计算，Key 的获取见 /guides/claude-api-key-console。

适用于谁

• 用 Node.js、Deno、Bun 或 TypeScript 写后端、脚本、机器人，要接 Claude 的开发者；
• 看过 Python 版（/guides/claude-api-python-quickstart），想要对等的 TypeScript 写法的人；
• 已经有了 API Key（获取方式见 /guides/claude-api-key-console），想把请求跑通的人。

结论先说

1. 包名是 @anthropic-ai/sdk，用 npm install @anthropic-ai/sdk 安装。
2. 环境要求：TypeScript 5.0 及以上；Node.js 请用 20 LTS 及以上的非 EOL 版本。
3. Key 放环境变量 ANTHROPIC_API_KEY，SDK 默认会读，代码里不要写死。
4. 默认自动重试 2 次，超时 10 分钟，都可以配置。
5. 别在浏览器里直接调用：SDK 默认禁用浏览器环境，防止暴露密钥。

图：本站根据 Claude 官方《TypeScript SDK》 整理的示意图

一、环境准备

新建一个目录，初始化并安装：

bash
mkdir claude-demo && cd claude-demo
npm init -y
npm install @anthropic-ai/sdk

设置环境变量。macOS 或 Linux 终端：

bash
export ANTHROPIC_API_KEY="你的 Key"

Windows PowerShell：

powershell
$env:ANTHROPIC_API_KEY = "你的 Key"

这只对当前终端窗口有效。Key 相当于密码，不要提交到代码仓库，也不要发给别人。

官方列出的支持运行时：Node.js 20 LTS 及以上、Deno 1.28.0 及以上、Bun 1.0 及以上，以及 Cloudflare Workers、Vercel Edge Runtime 等；Jest 28 及以上需用 node 环境，jsdom 暂不支持；React Native 暂不支持。

二、第一个请求

新建 index.mjs（.mjs 后缀可以直接使用 import 和顶层 await）：

javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"], // 这是默认行为，可以省略
});

const message = await client.messages.create({
  model: "claude-opus-5-5", // 以官方模型页当天为准
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好，Claude" }],
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

运行：

bash
node index.mjs

三个必填项：model、max_tokens、messages。回答在 message.content 这个数组里，里面可能有不同类型的块，所以先判断 block.type === "text" 再取 block.text。如果用 TypeScript，把文件命名为 .ts 并用你熟悉的工具运行即可，类型提示会帮你补全字段。

三、类型与用量

SDK 带有所有请求参数和响应字段的 TypeScript 类型：

typescript
const params: Anthropic.MessageCreateParams = {
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好，Claude" }],
};
const message: Anthropic.Message = await client.messages.create(params);
console.log(message.usage); // 形如 { input_tokens: 25, output_tokens: 13 }

usage 是账单的依据。想在发请求前先估算，见 /guides/claude-api-count-tokens。

四、流式输出

方式一：stream: true，得到事件的异步迭代器。

javascript
const stream = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好，Claude" }],
  stream: true,
});
for await (const event of stream) {
  console.log(event.type);
}

要取消，可以 break 退出循环，或调用 stream.controller.abort()。

方式二：助手方法，更省事。

javascript
const stream = client.messages
  .stream({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "说声你好" }],
  })
  .on("text", (text) => process.stdout.write(text));

const finalMessage = await stream.finalMessage();

官方说明两者的区别：client.messages.stream(...) 提供事件处理和累积，最后能拿到完整消息；create({ stream: true }) 只返回事件迭代器，不累积，内存占用更少。事件细节见 /guides/claude-api-streaming。

五、错误怎么处理

图：本站根据 Claude 官方《TypeScript SDK》 整理的示意图

连不上 API 或收到 4xx、5xx 时，SDK 抛出 Anthropic.APIError 的子类：

javascript
try {
  await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "你好，Claude" }],
  });
} catch (err) {
  if (err instanceof Anthropic.APIError) {
    console.log(err.status); // 例如 400
    console.log(err.name);   // 例如 BadRequestError
  } else {
    throw err;
  }
}

官方给出的对应关系：

各状态码的含义与排查见 /guides/claude-api-error-codes，429 和 529 请看 /guides/claude-api-error-429-rate-limit 与 /guides/claude-api-error-529-overloaded。

六、重试和超时

• 重试：连接错误、408、409、429 和 500 及以上的错误，默认自动重试 2 次，带指数退避。可以用 maxRetries 改，客户端级别或单次请求都行：

javascript
  const client = new Anthropic({ maxRetries: 0 }); // 关闭自动重试
  await client.messages.create(params, { maxRetries: 5 });
  

• 超时：默认 10 分钟。如果你把 max_tokens 设得很大又没用流式，默认超时会按公式动态算，最长可到 60 分钟。可以用 timeout（毫秒）覆盖：

javascript
  const client = new Anthropic({ timeout: 20 * 1000 });
  await client.messages.create(params, { timeout: 5 * 1000 });
  

超时会抛 APIConnectionTimeoutError，并且默认同样会重试两次；

• 长请求：官方明确建议，大 max_tokens 的长请求用流式。SDK 预计非流式请求会超过约 10 分钟时，会直接抛错；传 stream: true 或自己指定 timeout 可以去掉这个报错。

七、排查与进阶

• request id：所有对象响应都有 _request_id 属性（来自响应头 request-id），日志里记下来，联系官方时提供；
• 日志：用环境变量 ANTHROPIC_LOG 或客户端选项 logLevel，取值 debug、info、warn（默认）、error、off。官方提醒 debug 级别会打印包含请求头和请求体的 HTTP 日志，可能含敏感数据，只在调试时用；
• beta 功能：通过 client.beta.messages.create({ ..., betas: ["..."] })，在 betas 里写对应的 beta 请求头；
• 其他能力：批量请求在 client.messages.batches（见 /guides/claude-api-message-batches），文件上传用 client.files.upload 配合 toFile（见 /guides/claude-api-files-api）。

八、写进项目前的几条小建议

下面几条是本站的经验性建议，不是官方的硬性要求：

• 把客户端放在一个模块里创建一次，到处复用，而不是每个请求都 new Anthropic()；
• 模型名集中放在一个常量或配置里，官方换模型、下线旧模型时只改一处；
• 给每个请求记录 _request_id、usage 和耗时，出了问题好查，也方便核对账单；
• 对用户可见的功能，先想好限流和过载时怎么提示，再决定要不要自己加一层重试，因为 SDK 本身已经默认重试两次；
• 本地调试时可以临时把 logLevel 调成 debug，调完改回来，避免日志里留下敏感内容。

九、关于浏览器

SDK 在浏览器里默认禁用，因为 Key 会暴露在前端代码里，任何访问者都能提取并滥用。官方承认，内部工具、短期调试等少数场景风险较小，可以显式设 dangerouslyAllowBrowser: true；但即使这样，启用了零数据保留或 Compliance API 的组织也不能直接从浏览器调用，会收到 401。通常的做法是由你自己的后端去调 Claude，前端只调你的后端。

常见问题

Q：报错 ANTHROPIC_API_KEY 找不到？

环境变量只在设置它的那个终端窗口里有效，换了窗口要重新设置；或者在创建客户端时传 apiKey（不要把真实 Key 写进代码仓库）。

Q：提示 Node 版本太低？

官方要求 Node.js 20 LTS 及以上的非 EOL 版本。

Q：想用工具调用？

工具的概念见 /guides/claude-tool-use-basics；SDK 的 toolRunner 和 betaZodTool 辅助函数在官方页面有说明，本文不展开。

参考资料

• Claude 官方：TypeScript SDK — https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript
• Claude 官方：Claude API errors — https://platform.claude.com/docs/en/api/errors