API Key 是什麼：它同時是你的身分和你的錢包（Chinese original）

你會在大概第三篇教學裡遇到它。通常是這樣一句話：「把你的 API key 填進設定檔」或「執行 export ...」。

如果你不知道那是什麼，你會有兩種反應：一種是直接關掉分頁（這是本站觀察到最常見的流失點），另一種是照著做、把一串字貼進某個地方，然後在一個月後收到一張你看不懂的帳單。

這篇要讓你有第三種反應：知道它是什麼、知道它該放哪、知道放錯的代價。

定義先講完：API key 是一串字，讓遠端服務知道「這個請求是你發的，帳單算你的」。 見 API Key。

它是身分與錢包的同一把鑰匙。這就是它跟一般「帳號密碼」不一樣的地方 —— 一般密碼只證明你是你，API key 還允許持有人花你的錢、以你的名義發請求。

它長什麼樣

一串很長的隨機字元，通常有一個供應商自己的前綴，例如 sk- 開頭。不同供應商的前綴與長度都不一樣，不要靠形狀去認它。

認它的正確方式是看它從哪裡來：你登入某個供應商的控制台（console）、找到「API keys」或「金鑰」那一頁、按「建立」之後拿到的那一串字，就是。

有三件事值得先知道：

它通常只完整顯示一次。 很多供應商的頁面在你建立之後只給你看一次，之後只顯示前幾碼與後幾碼。當下沒存下來，就只能作廢重發。
它沒有到期日，除非你設。 一把三年前建立的 key，如果沒人作廢它，今天還能用。
它可以有很多把。 正確的用法是給不同用途發不同的 key（一個給本機測試、一個給正式環境），這樣其中一把出事時，你作廢它不會把所有東西一起弄壞。

它該放在哪裡

答案只有一個：環境變數，或一個不會被提交的設定檔。 見環境變數與 .env。

理由是：程式需要讀到它，但它不該出現在任何會被別人看到、被上傳、被記錄下來的地方。環境變數正是為此設計的 —— 它存在程式外面，由執行環境在啟動時遞給程式。

不要放的四個地方

放這裡	會發生什麼
寫死在程式碼裡	你遲早會把程式碼推上 GitHub。爬蟲在幾分鐘內就會掃到並拿去用
貼進聊天視窗問 AI「這個錯誤怎麼辦」	那把 key 進了一家第三方公司的系統，而且你收不回來
截圖貼到論壇或社群	圖片裡的字串一樣會被讀出來，而且你以為自己只截了「一半」
提交進 git	光刪掉那個檔案沒有用，它還在歷史裡。任何能 clone 這個 repo 的人都拿得到

第三項特別值得說：錯誤訊息常常會把環境變數的內容印出來，因為它出現在指令參數裡。所以截圖錯誤訊息之前，先看一眼裡面有沒有一長串隨機字元。這件事在怎麼讀一則錯誤訊息的步驟六裡也提過。

步驟

步驟一：從官方控制台建立一把

到你要用的那個供應商的官方網站，登入，找 API keys／金鑰管理頁，建立一把。

注意你進的是不是官方網址。 「免費 API key」「代儲值」「鏡像站」這類搜尋結果是釣魚的高發區，而一把 key 背後連著的是付款方式。

建立的時候如果它問你要不要限制這把 key 的權限或額度上限，要。這是成本失控時唯一的事前防線。

步驟二：放進環境變數

確切的變數名字由你要用的那個工具的文件規定 —— 照它的文件抄，不要猜。 形狀是這樣：

macOS／Linux（bash、zsh）：

export 工具指定的變數名="sk-xxxxxxxxxxxxxxxx"

Windows PowerShell：

$env:工具指定的變數名 = "sk-xxxxxxxxxxxxxxxx"

這個寫法只在當前這個視窗有效，關掉就沒了。 這是刻意的：測試的時候用這個最安全，因為它不會留在任何檔案裡。

要長期有效，寫進 shell 的設定檔（~/.zshrc 或 ~/.bashrc），或放進專案的 .env 檔。兩種做法都在五分鐘設置你的 LLM 開發環境裡有完整步驟，這篇不重複。

步驟三：確認 `.env` 不會被提交

如果你用了 .env 檔，同一個專案裡必須有一個 .gitignore，裡面有一行 .env。

確認方式：

cat .gitignore
git check-ignore .env

第二條如果印出 .env，代表 git 會忽略它；什麼都沒印，代表它會被提交。

.env 是以一個點開頭的隱藏檔，一般的 ls 看不到它，要用 ls -la。這個「看不到」的特性讓很多人以為它不存在，於是漏掉檢查。

步驟四：驗證它真的被讀到了

不要猜。直接問環境：

echo $工具指定的變數名          # macOS / Linux

$env:工具指定的變數名           # Windows PowerShell

預期輸出：印出你剛才放進去的那一串。

如果印出來是空的，最常見的原因不是「你設錯了」，而是：

你在 A 視窗 export，卻在 B 視窗跑程式。環境變數不跨視窗。
你寫進了 ~/.bashrc，但你的 shell 是 zsh（它讀 ~/.zshrc）。
你寫進了設定檔，但沒有開新視窗 —— 設定檔只在 shell 啟動時讀一次。見 Config File（設定檔）。

印出來之後記得把視窗捲回去，或按 Ctrl + L 清屏。 你的 key 現在正明文顯示在畫面上，而你接下來可能會截圖。

步驟五：知道洩漏了怎麼辦

先講代價，因為這決定了你該有多緊張。

一把洩漏的 API key，別人可以用它：

花你的錢。 這是最直接的一項。API 是按用量計費的，見 AI 到底要花多少錢。洩漏的 key 被拿去跑大量請求，是很常見的事。
以你的名義發請求。 那些請求的用量紀錄掛在你的帳號上。
讀取你有權限讀的東西。 有些供應商的 key 不只呼叫模型，還能讀你的檔案、你的專案、你的帳單資訊。

發現洩漏，做這三件事，按這個順序：

立刻到控制台把那一把 key 作廢（revoke / delete）。 不是改名字，是作廢。
建一把新的，更新到你要用的地方。
去看用量與帳單頁面，確認在你作廢之前有沒有你不認得的用量。 有的話聯絡供應商支援。

然後要接受一件事：作廢之前那段時間，那把 key 是敞開的。 你無法知道它被用了多少。所以正確的態度不是「小心一點就好」，而是從一開始就讓它沒有機會出現在會被分享的地方。

如果它被提交進過 git：光刪檔案、光作廢 key 還不夠，你的 repo 歷史裡還有它。作廢 key 是必要的那一步；把歷史清乾淨是另一件事，而且如果那個 repo 曾經公開過，你應該假設它已經被掃到了。

你什麼時候根本不需要 API key

這件事多數教學不會告訴你，而它讓很多人白緊張了一場。

如果你用的工具有圖形介面、而且是用帳號登入的，你通常不需要自己處理 API key。 你在工具裡登入，工具自己保管憑證。例如：

網頁版的對話工具（ChatGPT、Claude 這類）—— 你登入就好，沒有 key 要填
掃碼登入的辦公 Agent，例如 WorkBuddy、豆包工作
用帳號登入的 AI IDE，例如 Cursor、Trae

你會在什麼時候遇到 key：當你要用命令列工具、要自己寫程式呼叫模型、或要幫一個工具「自帶模型」而不是用它內建的額度時。

還有一個新手一定會混淆的點，值得單獨講：

「我已經訂閱了那個網頁版」不等於「我有 API 額度」。 很多供應商把這兩件事分成兩套計費 —— 一套是給人在介面上用的訂閱，一套是給程式呼叫的用量計費。這一點你必須在自己的帳單頁面確認，本站不替任何供應商斷言它們的方案怎麼組合。

一條紀律

範例裡一律寫 sk-xxxxxxxx。

這不只是本站的寫法。你自己寫筆記、寫內部文件、截圖、問問題的時候，也應該用同一個佔位符。養成這個習慣之後，你就不需要在每一次分享之前臨時檢查「這裡面有沒有我的真 key」—— 因為它從來不會出現在那裡。

下一步

環境變數與 .env 的完整設定步驟：五分鐘設置你的 LLM 開發環境
第一次用它發出一個請求：第一次呼叫 LLM API
這把 key 會怎麼燒錢：AI 到底要花多少錢
貼出去的東西到底去了哪裡：我的資料安全嗎
錯誤訊息裡出現 key 時怎麼辦：怎麼讀一則錯誤訊息
詞條：API Key、環境變數與 .env、Config File（設定檔）、Dotfile（點檔案）