你會在大概第三篇教學裡遇到它。通常是這樣一句話：「把你的 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（點檔案）