SDK 是什麼?跟 API 差在哪,什麼時候該用、什麼時候不用
一句話回答
SDK(Software Development Kit,軟體開發套件)是服務商幫工程師準備好的工具箱,最常見的是把「怎麼呼叫自家 API」包成現成的程式,裝進專案就能用。API 是對方開的窗口和規則,SDK 是幫你照規則跟窗口打交道的工具,金鑰、版本、資料格式、出錯重試都先處理好了。有官方 SDK 的服務,多數情況直接用最省事。只用到一兩支 API、又很在意程式大小時,自己呼叫 API 也可以。
先從一句話開始:「先安裝某某 SDK」
用 AI 寫程式的人應該都看過這個畫面。你請它串接一個服務,例如接 AI 模型、寄信、收款,它的第一步常常是:「先安裝某某 SDK。」接著跑了一行安裝指令。
大部分人就直接按同意了。這篇把那一步拆開來講:SDK 是什麼、跟 API 差在哪、它到底幫你做了什麼,還有什麼時候其實不用裝。
我自己的專案裡,有的一口氣裝了三套 SDK,有的刻意一套都不裝,後面會拿這些實際例子來講。沒有程式背景也看得懂。如果還不熟 API,建議先看API 是什麼,這篇會接著那篇的餐廳比喻往下講。
SDK 是什麼:服務商幫你準備的工具箱
SDK 是 Software Development Kit 的縮寫,中文叫軟體開發套件。AWS 的官方說明把它定義成「一組針對特定平台的開發工具」,裡面可能有程式庫、範例程式、除錯工具和文件。
對用 AI 做網站的人來說,最常碰到的是其中一種:服務商把「怎麼呼叫自家 API」寫成現成的程式,讓你裝進專案直接用。Claude、AWS、LINE 都有自己的官方 SDK。
延續 API 那篇的比喻。API 是餐廳的點餐櫃台和點餐規則:要說哪些話、照什麼格式填單、出示什麼會員證,櫃台才幫你出餐。SDK 像店家自己出的點餐 App,你在 App 上按幾個按鈕,它把單填成櫃台要的格式、附上會員證,櫃台太忙還會自己再送一次。
送進廚房的是同一張單。差別只在填單、排隊、重送這些瑣事,是你自己來,還是交給 App。
一套 SDK 裡通常有什麼
打開一套串服務用的 SDK,大概會看到這幾樣:
- 呼叫 API 的程式:最核心的部分。原本要自己組網址、標頭、資料格式,現在呼叫一個函式就好,例如
client.messages.create(...) - 型別定義:告訴編輯器每個欄位叫什麼、該填什麼。用 TypeScript 寫的話,欄位名字打錯,還沒執行編輯器就先畫紅線
- 文件與範例:照著範例改,通常是上手最快的方式
- 輔助功能:例如串流(AI 的回答一段一段即時吐出來)、分頁(資料太多要分好幾次拿)這類寫起來繁瑣的事
- 做手機 App 用的那一類 SDK 範圍更大,連打包工具都包在裡面,後面另外講
同一件事,兩種寫法
直接看程式最有感。下面兩段做的是同一件事:請 Claude 回一句話。看不懂程式沒關係,比一下長度,再看註解寫了什麼就好。
先看不用 SDK、自己呼叫 API 的寫法。網址、金鑰放哪個標頭、API 版本、資料格式,都要照官方文件一個一個寫對:
const res = await fetch("https://api.anthropic.com/v1/messages", { method: "POST", headers: { "authorization": "Bearer " + process.env.ANTHROPIC_API_KEY, "anthropic-version": "2026-10-21", "content-type": "application/json", }, body: JSON.stringify({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "早安" }], }), }); if (!res.ok) throw new Error("失敗:" + res.status); // 要不要重試,得自己寫 const data = await res.json(); // 回覆可能分成好幾段,取出文字那段 console.log(data.content.find((b) => b.type === "text")?.text);
換成用 SDK 的寫法
同一個請求,改用 Claude 官方的 TypeScript SDK(用 JavaScript 寫的專案也是同一套)。先在專案裡執行一次 npm install @anthropic-ai/sdk 安裝,程式就變成這樣:
import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // 金鑰自動從環境變數 ANTHROPIC_API_KEY 讀 const msg = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "早安" }], }); // 回覆可能分成好幾段,取出文字那段 console.log(msg.content.find((b) => b.type === "text")?.text);
SDK 幫你處理掉的事
第二段短了一截,少掉的部分 SDK 替你做了。下面這張表是兩種寫法的分工:
- 帶上金鑰和版本:每個請求都要附金鑰和 API 版本,SDK 自動加上。金鑰從環境變數(放在部署平台後台、不寫進程式碼的設定值)讀,你的程式裡看不到它
- 出錯自動重試:連線失敗、請求太頻繁(429)、對方伺服器出錯(500 以上)這幾種,官方文件寫明預設會自動重試 2 次,每次間隔稍微拉長。我拿一台故意回錯誤的測試伺服器試過,讓它先回 429、再回 500,第三次才回成功,程式照樣拿到結果,重試的程式碼一行都沒寫
- 逾時:預設等 10 分鐘沒回應就放棄並丟出錯誤,程式不會一直卡在那裡
- 錯誤有名字:被限流會拿到一個叫
RateLimitError的錯誤,金鑰不對是AuthenticationError。要分開處理不同狀況時,看名字比去猜數字清楚 - 擋住危險用法:這套 SDK 預設不讓你在瀏覽器裡執行,因為那等於把金鑰交給每一個打開網頁的人。真的要開,得把一個名字就叫
dangerouslyAllowBrowser(危險地允許瀏覽器)的選項打開。金鑰為什麼不能放在網頁裡,可以看AI 幫我寫的程式,會不會把 API 金鑰外洩出去?
對方改版的時候,差別最明顯
上面那些自己寫也做得到,多花點時間而已。SDK 最省事的時候,是對方改規則的時候。
Claude 的 API 最近出了一個新版本,名字就叫 2026-10-21,拿掉了幾個舊參數。官方文件現在也把放金鑰的標頭改成以 Authorization 為主,原本的 x-api-key 改列為舊方式,但仍然支援。
我有兩套內部系統用的是 Claude SDK 的 0.78 版。把它跟最新的 1.12 版放在一起比,我寫的程式一模一樣,送出去的請求卻不一樣:
- 舊版 SDK 不會突然壞掉:Claude 官方承諾,同一個 API 版本既有的輸入、輸出欄位都會保留。所以那兩套系統到今天都還正常在跑
- 要用新版本,就升 SDK 的主版號:官方文件寫明,每個 SDK 主版號固定送一個 API 版本,TypeScript 版從 1.0.0 開始才送
2026-10-21 - 直接呼叫的人要自己追:版本標頭要自己改,金鑰放哪裡也要自己決定要不要跟著換
- 不管用哪一種,升級前都要讀改版說明:新版本拿掉的參數(例如
temperature),程式裡還留著的話會收到 400 錯誤,用 SDK 也一樣要自己刪
SDK 和 API 到底差在哪
很多人把這幾個詞混著用,整理成一張表:
- API 是對方開的規則:有沒有 SDK,API 都在那裡。AWS 的說明也寫,SDK 裡面可能就包含了 API
- SDK 是照規則操作的工具,而且跟程式語言綁在一起:換一種語言就要換一套。Claude 的官方 SDK 目前有 Python、TypeScript、C#、Go、Java、PHP、Ruby 七種
- 有 API 不一定有 SDK:沒有 SDK 的服務,就照 API 文件直接呼叫。LINE 的官方文件也寫,沒有提供 SDK 的程式語言,一樣可以使用它的功能
- 套件是發佈的形式:服務的 SDK 通常包成一個套件,用 npm 這類工具安裝。npm 是什麼,可以看npm 是什麼?
名字都叫 SDK,其實分兩種
SDK 這個詞用得很廣,大致分成兩種。升級時要花的力氣差很多:
- 串服務的 SDK:讓你的程式呼叫某一家的服務,Claude、AWS、LINE 的 SDK 都是這種。它在專案裡就是一個套件,拿掉換成自己寫也還做得到
- 做平台的 SDK:讓你做出某個平台上的 App,整個 App 建在它上面。例如用 React Native 做手機 App 常用的 Expo SDK,官方文件寫明每一版 Expo SDK 對應一個 React Native 版本,一年出三版
- AI 圈還有幾個名字裡帶 SDK 的,做的事又不一樣:Vercel 的 AI SDK 讓你用同一套寫法接不同家的 AI 模型。Claude Agent SDK 把 Claude Code 的代理迴圈和內建工具做成函式庫,讓你放進自己的程式(什麼是代理,可以看AI Agent 是什麼?)。MCP 的 SDK 用來做 MCP 伺服器和用戶端(見MCP 是什麼?)
- 聽到「這個要用某某 SDK」,先問一句:它是幫我串一家服務,還是整個 App 都建在它上面?
我自己的專案:有的裝,有的刻意不裝
四個實際例子:
- 數據分析工具,裝了三套官方 SDK:Claude、Google Analytics 的資料 API、Facebook 的行銷 API,各用各家的官方 SDK。三家的驗證方式各不相同,用官方 SDK 就不用一家一家研究怎麼帶憑證
- 官網的 LINE 電子名片,沒裝 SDK:LINE 有官方 SDK,但名片功能只用到兩支 API,一支回覆訊息、一支查官方帳號資訊。我直接呼叫,兩支加起來大約四十行。官網聯絡表單寄通知信也一樣,直接呼叫寄信服務的 API
- 寄信平台,刻意不裝 AWS 的 SDK:用 AWS 的寄信服務,每個請求都得照 AWS 的規則做簽章(用金鑰算出一串驗證碼附在請求上)。整個平台只用到 AWS 寄信服務的幾支 API,為此裝一整套 SDK,雲端函式的程式包會變大,所以我自己寫了簽章,大約一百行。代價也要講清楚:AWS 官方文件寫的是「除非有好理由,建議一律使用 SDK 或 CLI」,簽章出了錯只能自己除錯
- 手機 App 升 Expo SDK,不是改一個數字:一個內部用的手機 App 為了處理套件的安全警示,把 Expo SDK 從 56 升到 58,底下的 React Native 也跟著從 0.85 換到 0.88。平台型的 SDK 一升,App 本體就要重新打包、重新安裝。新版裝好之前還不能推線上的小更新,舊版 App 可能會收到它跑不動的程式
什麼時候用 SDK,什麼時候直接呼叫
照這張圖走一次:
- 有官方 SDK,就先用它:重試、逾時、錯誤分類、跟上改版,自己寫很容易漏掉其中一項
- 要做複雜簽章或驗證的,更要用:AWS 這種每個請求都要簽章的服務,官方明講建議用 SDK 或 CLI(命令列工具)。我的寄信平台是例外,而且是清楚知道代價才這樣做
- 只用一兩支、格式又簡單的 API,直接呼叫也合理:像我的 LINE 名片。只是重試和錯誤處理要記得自己補
- 沒有官方 SDK,就直接呼叫:網路上別人寫的非官方 SDK 可以參考,但它不是那家公司維護的,對方改版時不一定跟得上
裝 SDK 之前,先確認這四件事
AI 幫你挑 SDK 的時候,花一分鐘看這幾項:
- 是不是官方的:到服務商的官方文件找 SDK 頁面,照上面寫的套件名稱安裝,名字很像的不一定是同一家。有研究發現,寫程式的 AI 有時會推薦根本不存在的套件名稱。如果有人搶先用那個名字上架惡意套件,照著 AI 指令安裝的人就中招了
- 還有沒有人在維護:看最近一次更新是什麼時候。官方 SDK 通常更新得很勤,Claude 的 TypeScript SDK 在 npm 上已經發過兩百多個版本
- 版本號怎麼讀:多數套件照「主版號.次版號.修訂號」編號,例如 1.12.0。主版號變了,代表有不相容的改動。0 開頭的版本在規格上屬於開發初期,什麼都可能改
- 授權條款:開源的 SDK 都會寫明授權,例如 Claude 的 TypeScript SDK 用的是 Apache 2.0。公司產品要用,這一項要看
SDK 升版:最容易被忽略的成本
裝 SDK 等於把別人寫的程式放進你的專案。它會改版,也可能被發現漏洞。
我那兩套停在 0.78 版的系統就是例子。專案設定裡寫的是 ^0.78.0,前面那個 ^ 的意思是「可以自動升到相容的新版」。可是對 0 開頭的版本,npm 的規則很保守,只會升修訂號,連 0.79 都不會自動升,更別說 1.x。要升就得自己動手,照官方的改版說明一項一項改。
這樣的好處是不會在某天早上被自動升級弄壞。代價是 SDK 不會自己變新,要記得排時間升:
- 修訂號、次版號:通常照常升就好,修漏洞的版本更要升。GitHub 的 Dependabot 會自動開 PR 提醒,見網站放在 GitHub,有哪些免費的資安功能該打開?
- 主版號:先讀改版說明,測過再升。Claude 的 SDK 從 0.x 升到 1.x 時換了 API 版本,就有參數被拿掉
- 平台型 SDK:像 Expo 這種,升版要排進 App 的發版流程,連同重新打包、送審一起算時間
請 AI 幫你盤點專案用了哪些 SDK
把這段貼給你的 AI 程式助手,先看清楚專案裝了什麼,再決定要不要升級或整理:
請幫我盤點這個專案用到的所有外部服務,整理成表格: 1. 服務名稱,以及程式是用官方 SDK、非官方套件,還是直接呼叫 API 2. 用 SDK 的話,套件名稱、專案裡寫的版本、目前最新的版本 3. 目前版本和最新版本差在主版號、次版號還是修訂號 4. 這個套件是不是服務商官方發佈的(附上官方文件的 SDK 頁面連結,查不到就寫「未查到」,不要猜) 5. 如果要升到最新的主版號,官方改版說明提到哪些需要改程式的地方 先不要安裝、升級或修改任何東西,只要給我盤點結果。
三個常見的誤會
- 「SDK 就是 API」:API 是對方開的窗口和規則,SDK 是幫你使用窗口的工具。沒有 SDK,API 一樣能用
- 「用了 SDK,就不用看 API 文件」:SDK 幫你處理格式,但每個參數的意思、怎麼收費、有什麼限制,還是寫在 API 文件裡
- 「SDK 一定又肥又慢,自己寫比較好」:SDK 確實會讓專案多一些程式碼,值不值得要看你用到多少。只用一兩支 API 時自己寫可能更划算,會用到重試、串流、好幾種功能時,SDK 省下的時間通常更多
常見問題
SDK 要錢嗎?
官方 SDK 本身通常是免費的開源程式,例如 Claude 的 TypeScript SDK 用 Apache 2.0 授權公開在 GitHub 上。要付錢的是你透過它呼叫的服務。用 SDK 呼叫 Claude,跟直接呼叫 API 一樣按用量計費。
我不會寫程式,也需要懂 SDK 嗎?
不用會寫,但值得知道三件事:AI 要你裝的是不是官方 SDK、裝在哪個專案、版本號第一個數字是多少。這三件決定了日後出問題時好不好處理。可以用文中的盤點提示詞請 AI 列給你看。
一個專案可以同時用好幾套 SDK 嗎?
可以,很常見。我的數據分析工具就同時用了三家的官方 SDK。要注意的是每一套都要各自維護、各自升版,裝得越多,要顧的東西越多。
SDK 跟套件(package)有什麼不同?
套件是發佈和安裝的形式,SDK 講的是用途。服務的 SDK 通常包成一個套件,用 npm 之類的工具安裝,例如 Claude 的 TypeScript SDK 套件名稱是 @anthropic-ai/sdk。但套件不一定是 SDK,很多套件只是一個小工具。
沒有官方 SDK 的服務怎麼辦?
照官方 API 文件直接呼叫就可以。有些服務會提供 API 規格檔,可以用程式產生器自動產出呼叫的程式,LINE 的官方文件就提到 OpenAPI Generator 這類工具。網路上的非官方 SDK 可以參考,但要先看清楚是誰在維護。
SDK 要不要一直升到最新?
修訂號和次版號的更新通常照常升就好,修漏洞的版本更要升。主版號要先讀改版說明,排時間測過再升。舊版不一定會馬上壞,我停在 0.78 版的系統到今天都還能用,只是新的 API 版本和新功能就拿不到。
Claude Agent SDK 跟 Claude 的 SDK 是同一個東西嗎?
不是。Claude 的用戶端 SDK 讓你的程式呼叫 Claude API,每個請求和回應都由你自己處理。Claude Agent SDK 把 Claude Code 的代理迴圈、內建工具和權限控制做成函式庫,讓你在自己的程式裡跑一個會自己規劃、自己動手的代理。官方文件把它們列成不同的工具。
AI 叫我裝一個 SDK,怎麼確認它是對的?
到那個服務的官方網站,找開發者文件裡的 SDK 頁面,核對套件名稱是不是一字不差。名字對得上、而且是官方文件列出來的,就可以放心。對不上的話先別裝,請 AI 附上它的資料來源再說。
資料來源
每一筆都實際打開確認過。日期是該來源標示的發布日,這類規格會變動, 需要最新狀況請直接看原始出處。
- 01What is SDK?AWS 官方說明·2026-11-21官方一手
SDK 的定義「一組針對特定平台的開發工具」,以及 SDK 常見的內容:程式庫、除錯工具、範例程式、文件等。頁面沒有標發布日,日期為本文查證當日。
- 02What's the Difference Between SDK and API?AWS 官方說明·2026-11-21官方一手
API 是讓兩個軟體照既定規則溝通的機制,SDK 是建置軟體的工具組。SDK 針對特定程式語言或平台,SDK 裡可能包含 API。頁面沒有標發布日,日期為本文查證當日。
- 03SDKs, CLI, and librariesClaude 官方文件·2026-11-21官方一手
Claude 官方用戶端 SDK 有 Python、TypeScript、C#、Go、Java、PHP、Ruby 七種語言,內建串流、重試、錯誤處理。每個 SDK 主版號固定送一個 API 版本,要換 API 版本就升主版號。TypeScript 版最新為 1.12.0。Claude Agent SDK 與用戶端 SDK 是不同層級的工具。日期為本文查證當日。
- 04TypeScript SDKClaude 官方文件·2026-11-21官方一手
連線錯誤、408、409、429、500 以上預設自動重試 2 次並逐次拉長間隔。預設逾時 10 分鐘。各狀態碼對應的錯誤名稱(RateLimitError、AuthenticationError 等)。預設不能在瀏覽器執行,要開 dangerouslyAllowBrowser。SDK 自動送 anthropic-version 標頭,1.0.0 是第一個使用 2026-10-21 的版本。日期為本文查證當日。
- 05API versionsClaude 官方文件·2026-11-21官方一手
每個請求都要帶 anthropic-version 標頭,用 SDK 的話由 SDK 設定。同一個 API 版本會保留既有的輸入與輸出欄位。2026-10-21 版拿掉 temperature、top_p、top_k,送了會回 400。日期為本文查證當日。
- 06API overviewClaude 官方文件·2026-11-21官方一手
金鑰以 Authorization 標頭(Bearer)為主,x-api-key 列為舊方式但仍支援。SDK 會自動送出驗證、版本與內容格式標頭。⚠️ 「0.78 版送 x-api-key 與 2023-06-01、1.12 版改送 Authorization 與 2026-10-21」是我在本機檢查兩個版本的 SDK 原始碼、並攔下 1.12 版實際送出的請求確認的,官方文件沒有逐版列出。日期為本文查證當日。
- 07Agent SDK overviewClaude Code 官方文件·2026-11-21官方一手
Claude Agent SDK 提供跟 Claude Code 相同的工具、代理迴圈與脈絡管理,可用 Python 和 TypeScript 寫進自己的程式。官方對照表把它與直接呼叫 API 的用戶端 SDK 分開列。日期為本文查證當日。
- 08AWS Signature Version 4 for API requestsAWS 官方文件·2026-11-21官方一手
用 AWS SDK 或 CLI 時會自動簽章,可以跳過簽章流程。官方原文「除非有好理由,建議一律使用 SDK 或 CLI」。自己寫程式送請求時才需要自己簽。頁面沒有標發布日,日期為本文查證當日。
- 09LINE Messaging API SDKsLINE Developers 官方文件·2026-11-21官方一手
LINE 提供 Java、PHP、Python、Node.js、Go、Ruby 的官方 SDK。沒有提供 SDK 的程式語言一樣可以使用 LINE 平台的功能,並提到 OpenAPI Generator 等程式產生工具。頁面沒有標發布日,日期為本文查證當日。
- 10Reference:SDK versionsExpo 官方文件·2026-11-21官方一手
每一版 Expo SDK 對應一個 React Native 版本(SDK 56 對 0.85、SDK 58 對 0.88),新版每年發佈三次。日期為本文查證當日。
- 11Runtime versionsExpo 官方文件·2026-11-02官方一手
線上更新必須跟 App 打包時的原生程式相容。原生程式有改動時,要先出新的打包版本才能推更新,不相容的更新可能在舊版 App 上出錯。
- 12Semantic Versioning 2.0.0semver.org·2026-11-21官方一手
版本號「主版號.次版號.修訂號」的意思:不相容的改動升主版號、相容的新功能升次版號、相容的修正升修訂號。0.y.z 屬於開發初期,任何東西都可能改。日期為本文查證當日。
- 13node-semver:Caret Rangesnpm(GitHub)·2026-11-21官方一手
版本範圍前面的 ^ 允許「不動到最左邊非零數字」的更新。1.x 以上可以升次版號與修訂號,0.x 只升修訂號,例如 ^0.2.3 不會升到 0.3.0。日期為本文查證當日。
- 14AI SDK IntroductionVercel 官方文件·2026-11-21官方一手
AI SDK 是 Vercel 的 TypeScript 工具組,把不同 AI 模型供應商的串接方式統一成同一套寫法。日期為本文查證當日。
- 15SDKsModel Context Protocol 官方文件·2026-11-21官方一手
MCP 官方 SDK 用來建立 MCP 伺服器與用戶端,提供 TypeScript、Python 等多種語言。日期為本文查證當日。
- 16We Have a Package for You! A Comprehensive Analysis of Package Hallucinations by Code Generating LLMsSpracklen 等人,USENIX Security 2025(arXiv 預印本)·2024-06-12
寫程式的大型語言模型會推薦或引用不存在的套件,研究者把它歸為一種新的套件混淆攻擊:攻擊者可以用模型反覆編出來的名字上架惡意套件。這是學術研究,不是廠商文件。日期為第一版投稿日。