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