環境變數同 Secrets 係咩？淺白指南

環境變數係一個有名字嘅設定，例如 DATABASE_URL 或者 STRIPE_SECRET_KEY，喺你個應用程式運行時交俾佢，而唔係寫落代碼入面。Secret 係一個必須保密嘅環境變數，例如 API 密鑰、密碼或者簽署密鑰。將呢啲值放喺代碼以外，你就可以唔使改代碼都更換佢哋，測試同真正客戶用唔同嘅值，亦都可以避免你分享或者公開代碼時洩露出去。

用 AI 建構時點解咁重要

一旦你嘅應用程式要同另一個服務做嘢，例如收款、發電郵、調用 AI 模型，就需要用到密鑰。AI 應用程式建構工具經常要求你提供呢啲密鑰，而密鑰最後放喺邊，就決定咗你嘅應用程式安唔安全。

AI 建構嘅應用程式通常有兩樣嘢經常出錯：

• 密鑰被貼入聊天或者代碼。 咁樣佢就會留喺聊天記錄、項目檔案，同任何匯出或者代碼倉庫入面。見到嘅人都可以用你嘅帳戶。
• 密鑰喺瀏覽器入面使用。 如果呼叫 Stripe 或者 OpenAI 嘅代碼喺頁面入面運行，密鑰就會送去每位訪客。真係有人會睇，而且自動掃描器一直都喺搵暴露嘅密鑰。

明白環境變數，你就可以認出呢兩樣問題，亦都可以要求修正。

日常比喻：酒店保險箱

你個應用程式嘅代碼好似酒店房間。賓客（以及清潔人員，以及任何你俾咗門匙卡嘅人）都會行過。你唔會將護照放喺書枱上面。

環境變數就好似房間入面嘅保險箱。房間知道有個保險箱，亦知道需要時點樣打開，但護照並唔係隨便擺住。如果你由測試設定搬去真正嘅網站，你只需要喺嗰個房間嘅保險箱放一本唔同嘅護照，而唔使重新裝修。

運作方式

你嘅代碼係引用一個名字，而唔係一個值。喺伺服器上面嘅 JavaScript，寫法好似 process.env.STRIPE_SECRET_KEY。應用程式啟動時，佢運行嘅平台會將嗰個名字對應嘅值填入。喺平台設定度改咗個值，然後重新啟動或者重新部署，應用程式就會用新嘅值，唔使改代碼。

值嘅來源視乎應用程式喺邊度運行：

公開變數定係 secret 變數

唔係每個環境變數都係 secret。可以將佢哋分成兩類：

網頁框架會明確咁樣分開。Vite 入面，只有以 VITE_ 開頭嘅變數會被放入瀏覽器代碼；Next.js 就用 NEXT_PUBLIC_ 做前綴。咁樣係一種保護設計：凡係有呢啲前綴嘅嘢，最後都會放入每位訪客都會下載嘅檔案，所以 secret 絕對唔可以加呢啲前綴。

實際例子：AI 摘要按鈕

你想要一個「摘要呢則筆記」按鈕，佢會調用 AI 模型。

唔安全嘅做法： 按鈕嘅代碼喺瀏覽器入面運行，直接用寫死喺代碼度嘅 API 密鑰去叫 AI 供應商。喺預覽度會正常運作。但咁樣任何人都可以打開瀏覽器嘅開發者工具，複製個密鑰，然後用你嘅帳戶消費。

安全嘅做法：

1. 你喺 AI 供應商嗰度開一條密鑰，然後喺項目設定入面儲存為名叫 OPENAI_API_KEY（或者類似名稱）嘅 secret。
2. 後端有一條路由 POST /api/summarise，佢會讀取 process.env.OPENAI_API_KEY，檢查用戶有冇登入，然後去叫供應商。
3. 按鈕叫嘅係你嘅路由，而唔係供應商。瀏覽器永遠睇唔到密鑰。
4. 你喺已發佈應用程式嘅設定度加入同一個 secret，然後重新部署，令正式網站都有呢個值。

呢個模式（瀏覽器叫你嘅伺服器，伺服器持有密鑰再去叫服務）適用於收款、電郵、地圖同所有其他付費 API。使用 LLM API 指南會更深入咁講 AI 嘅情況。

重點名詞

• .env 檔案： 本地開發用嘅文字檔，每行係 名稱=值。喺 .gitignore 入面列明，咁就唔會被 commit。
• .env.example： 一份淨係有名稱、冇真正值嘅副本，會 commit，等其他人知道要設定邊啲變數。
• 輪換（rotate）： 用新嘅 secret 取代舊嘅，並撤銷舊嘅。
• 範圍／權限（scope）： 好多供應商容許你開一條只可以做特定嘢嘅密鑰。一條只可以發電郵嘅密鑰，會比一條可以做晒所有嘢嘅密鑰危險性低。
• 測試 vs 正式密鑰： Stripe 等供應商會為測試同真正收款分別提供密鑰。上線之前用測試密鑰。
• 簽署密鑰（signing secret）： 用嚟檢查某個訊息（例如 webhook）係咪真係由發送方發出嘅 secret。

常見錯誤同誤解

• 「我個 repository 係私人嘅，所以入面有密鑰冇問題。」 私人 repository 都會被分享、fork、匯出同複製到手提電腦。密鑰依然唔應該放喺嗰度。如果你將項目連接到 GitHub，要確認冇包含 .env 檔案。
• 「我已經刪咗，所以冇嘢啦。」 Git 會保留歷史記錄，聊天記錄亦會保留訊息。如果一條密鑰曾經洩露，就要輪換佢。
• 喺 secret 前面加咗公開前綴。 VITE_OPENAI_KEY 會將你嘅密鑰放入瀏覽器 bundle。
• 忘記重新部署。 喺設定度改咗變數，通常要等應用程式重新啟動或者再次發佈先會生效。
• 所有嘢都用同一條密鑰。 測試同正式分開，每個應用程式各用一條，咁樣就可以撤銷其中一條，而唔會影響其他嘅。
• 冇消費上限。 對於付費 API，喺供應商嘅後台設定預算或者上限，以防密鑰洩露。

向你嘅 AI 建構工具要求咩

• 「由名叫 STRIPE_SECRET_KEY 嘅環境變數讀取 Stripe secret 密鑰。只喺伺服器使用。」
• 「確保冇任何 secret 用喺客戶端代碼，亦冇俾佢加 VITE_ / NEXT_PUBLIC_ 前綴。」
• 「建立一個 .env.example，列出應用程式需要嘅每個變數，但唔好有值，並確保 .env 被 git 忽略。」
• 「檢查已建構嘅前端檔案，睇有冇任何似 API 密鑰嘅字串。」

我哋嘅 AI 建構應用程式安全檢查清單 會同其他上線前要檢查嘅項目一齊講 secrets。

Mythex 上嘅 Secrets

喺 Mythex，secrets 係項目嘅環境變數，會注入預覽沙盒同你已發佈嘅應用程式。你可以喺 項目設定 → Secrets 度加入，或者喺聊天入面用 /secrets。當 agent 需要密鑰時，會喺聊天中顯示一張 secrets 卡，所以個值會輸入到表單欄位，而唔會留喺訊息紀錄入面。如果你改咗正式應用程式嘅 secret，要重新發佈，部署先會用到新值。項目匯出會剔除 secrets，匯入嘅 .env 檔案會被清走，你要喺設定度重新加入。詳情請睇文件嘅環境變數同 secrets，以及聊天中嘅 secrets。

常見問題