什麼是環境變數與機密資訊？白話指南

環境變數是一個有名稱的設定，例如 DATABASE_URL 或 STRIPE_SECRET_KEY，在應用程式執行時交給它，而不是寫死在程式碼中。機密資訊則是值必須保持私密的環境變數：API 金鑰、密碼、簽章金鑰。把這些值放在程式碼之外，代表你不必改程式就能更換它們，測試與真實客戶可以使用不同的值，而且分享或發布程式碼時也不會洩漏。

為什麼使用 AI 建置時這很重要

只要你的應用程式要與其他服務有實際互動，例如收款、寄送電子郵件、呼叫 AI 模型，就需要金鑰。AI 應用程式建置工具經常會要求你提供這些金鑰，而金鑰最後放在哪裡，決定了你的應用程式安不安全。

AI 建置的應用程式常見兩種出錯方式：

• 把金鑰貼進聊天或程式碼裡。 它就會留在聊天紀錄、專案檔案，以及任何匯出或儲存庫中。任何看到它的人都能用你的帳號。
• 在瀏覽器中使用金鑰。 如果呼叫 Stripe 或 OpenAI 的程式碼是在頁面中執行，金鑰就會送到每位訪客那裡。確實有人會檢查，而自動掃描工具也會不斷搜尋外洩的金鑰。

了解環境變數，才能發現這兩種問題，並要求修正。

日常生活的比喻：飯店保險箱

你的應用程式程式碼就像飯店房間，訪客（以及清潔人員，還有任何你給了房卡的人）都會進出。你不會把護照放在桌上。

環境變數就像房內的保險箱。房間知道保險箱的存在，也知道需要時如何打開，但護照不會隨意擺放。如果你換到另一個房間，例如從測試環境換到正式網站，你只要在那個房間的保險箱放入另一本護照，而不必重新裝潢。

運作方式

你的程式碼引用的是一個名稱，而不是一個值。在伺服器端的 JavaScript 中，寫法像是 process.env.STRIPE_SECRET_KEY。應用程式啟動時，它所執行的平台會把這個名稱對應的值填入。在平台設定中更改這個值，然後重新啟動或重新部署，應用程式就會使用新的值，不需要修改程式碼。

這些值存放的位置，取決於應用程式的執行環境：

公開設定與機密變數

並非每個環境變數都是機密。把它們分成兩類會有幫助：

網頁框架會把這個區分明確寫出來。在 Vite 中，只有名稱以 VITE_ 開頭的變數會被納入瀏覽器程式碼；在 Next.js 中，前綴是 NEXT_PUBLIC_。這是一項安全機制：帶有這些前綴的內容，最後都會出現在每位訪客下載的檔案中，所以機密資訊絕對不能加上這些前綴。

實例：AI 摘要按鈕

你想要一個「摘要此筆記」按鈕，它會呼叫 AI 模型。

不安全的做法： 按鈕的程式碼在瀏覽器中執行，直接呼叫 AI 服務商，並把 API 金鑰寫在程式碼裡。它在預覽中能正常運作。但這也代表任何人都能打開瀏覽器的開發者工具，複製這把金鑰，然後用你的帳號產生大筆費用。

安全的做法：

1. 你在 AI 服務商那裡建立金鑰，並在專案設定中把它存為名為 OPENAI_API_KEY（或類似名稱）的機密。
2. 後端新增一個路由 POST /api/summarise，它讀取 process.env.OPENAI_API_KEY，檢查使用者是否已登入，然後呼叫服務商。
3. 按鈕呼叫的是你的路由，而不是服務商。瀏覽器永遠看不到金鑰。
4. 你把同一個機密加到已發布應用程式的設定中，並重新部署，讓正式網站也有這個值。

這種模式，也就是瀏覽器呼叫你的伺服器、由伺服器保管金鑰並呼叫服務，適用於付款、電子郵件、地圖，以及其他所有付費的 API。使用 LLM API 指南會更深入介紹 AI 的情況。

關鍵術語

• .env 檔案： 本機開發時使用的文字檔，每行是 名稱=值。請把它列入 .gitignore，避免被提交。
• .env.example： 一份只有名稱、沒有實際值的範本，會提交到專案中，讓其他人知道需要設定哪些變數。
• 輪替（Rotate）： 用新的機密取代舊的，並撤銷舊的。
• 範圍 / 權限： 許多服務商允許你建立只能執行特定操作的金鑰。只能寄送電子郵件的金鑰，比什麼都能做的金鑰風險低。
• 測試金鑰與正式金鑰： Stripe 等服務商會分別提供測試用與真實收款用的金鑰。上線前請使用測試金鑰。
• 簽章密鑰（Signing secret）： 用來確認訊息（例如 Webhook）確實來自寄件方的密鑰。

常見錯誤與誤解

• 「我的儲存庫是私密的，所以放金鑰沒關係。」 私密儲存庫仍會被分享、分支、匯出，並複製到筆記型電腦上。金鑰仍然不該放在那裡。如果你把專案連接到 GitHub，請確認沒有包含 .env 檔案。
• 「我刪掉了，所以它不見了。」 Git 會保留歷史紀錄，聊天紀錄也會保留訊息。只要金鑰曾經外洩，就應該輪替它。
• 在機密上加上公開前綴。 VITE_OPENAI_KEY 會把你的金鑰放進瀏覽器的打包檔中。
• 忘記重新部署。 在設定中更改變數，通常要等應用程式重新啟動或重新發布後才會生效。
• 所有地方都用同一把金鑰。 為測試與正式環境、以及每個應用程式分別建立金鑰，才能在不影響其他服務的情況下撤銷其中一把。
• 沒有花費上限。 對於付費 API，請在服務商的後台設定預算或用量上限，以防金鑰外洩。

該向你的 AI 建置工具要求什麼

• 「從名為 STRIPE_SECRET_KEY 的環境變數讀取 Stripe 私密金鑰，且只在伺服器端使用。」
• 「確認沒有任何機密用在客戶端程式碼中，也沒有加上 VITE_ 或 NEXT_PUBLIC_ 前綴。」
• 「建立一個 .env.example，列出應用程式需要的每個變數但不含實際值，並確認 .env 已被 git 忽略。」
• 「檢查建置後的前端檔案，找出任何看起來像 API 金鑰的字串。」

我們的AI 建置應用程式安全檢查清單，也涵蓋了上線前值得執行的其他檢查，包括機密資訊。

Mythex 上的機密資訊

在 Mythex 中，機密是專案環境變數，會同時注入預覽沙盒與你已發布的應用程式。你可以在專案設定 → Secrets 中新增，也可以在聊天中輸入 /secrets。當代理需要金鑰時，會在聊天中顯示機密卡片，因此值會進入表單欄位，而不會出現在對話紀錄裡。如果你要更改正式應用程式的機密，請重新發布，部署才會套用。匯出專案時不會包含機密，匯入的 .env 檔案也會被移除，你需要在設定中重新加入。請參閱文件中的環境變數與機密資訊，以及聊天中的機密資訊。

常見問題