Claude Code 整理環境設定：分清變數清單、密鑰同部署環境

有齊變數名，唔代表連緊啱嘅環境

本機有設定、測試環境漏咗一項，程式就可能只喺部署後出錯。另一種更難察覺嘅情況係：變數齊晒，但測試環境誤用正式資料庫。

要分清兩份資料：程式需要邊啲設定，同每個環境實際用乜值。.env.example 適合前者，唔係密鑰庫。

1. 清單寫名稱、用途同要求

# 必填；只供伺服器使用；各環境分開提供
DATABASE_URL=

# 必填；只供伺服器使用；從團隊密鑰管理渠道取得
ANTHROPIC_API_KEY=

# 可選；公開功能開關，唔可以包含機密
NEXT_PUBLIC_FEATURE_PREVIEW=false

真值唔放入範例、Git、對話或者執行記錄。就算只印密鑰頭幾個字亦未必有必要，報告用「存在／缺少／未驗證」已經足夠。

如果程式已有設定驗證模組，就以該模組同清單同步維護，唔好另造一套會互相矛盾嘅 required 規則。啟動時驗證格式同必要項目，錯誤訊息只講名稱，唔回顯值。

2. 先盤點，唔自動同步真值

讀取 .env.example、設定驗證模組同程式內使用環境變數嘅位置。

唔好讀取或輸出 .env.local、密鑰值及連線字串。列出名稱、用途、係咪必填、伺服器或瀏覽器使用，以及缺少文件嘅項目。

分開「名稱清單一致」同「值或連線已驗證」。暫時唔改本機、部署平台或密鑰管理系統。

遠端清單要核對專案同環境範圍，亦要睇有冇分支覆寫。Vercel 嘅 Preview 並唔天然等於你團隊叫做 staging 嗰個環境；先對照實際設定同官方環境變數文件。

3. 新增同更新要分開處理

加新變數時，先更新名稱清單、用途同程式驗證。由已授權嘅人透過密鑰管理器或者平台提供值，唔好要求對方將正式密鑰貼入 prompt。

更新已有值亦唔好簡單「先刪後加」。中途失敗可能令設定消失。先查平台支援嘅更新方法，記錄變更範圍，再按平台要求重新部署或者重啟，最後核對程式實際用到新設定。

Claude 可以幫你產生操作清單同核對缺漏；真正寫入、輪換或撤銷密鑰，應另外明確指定。

4. 缺漏檢查唔等於值正確

可以喺 CI 比較需要嘅名稱同允許取得嘅遠端 metadata，但唔好為咗檢查而拉晒解密值落檔案。來自外部 PR 嘅程式同設定，亦唔應獲得正式憑證。

要確認環境冇接錯，可以用隔離測試帳戶、受控健康端點或平台環境識別去驗證。單靠資料庫主機名似 staging，或者 API key 有某個前綴，唔足以證明所有服務都用緊測試環境。

檢查失敗時分清：欠變數、無權取得清單、平台 API 失敗、值未驗證。唔好全部顯示成綠剔或者一律當缺漏。

多個 App 同密鑰輪換

Monorepo 每個 App 只取得自己需要嘅設定。重點係資料流向：伺服器程式可以需要機密，瀏覽器產物唔可以包含機密。資料夾叫 web 唔代表入面所有程式都只喺瀏覽器執行。

輪換時間按供應商、風險同團隊政策決定，唔係所有密鑰一律每季換。如果懷疑外洩，就用既定應變程序處理；例行輪換則要安排新舊憑證交接，核對新值已生效先撤銷舊值。唔支援重疊憑證嘅服務，要另外計劃切換窗口。

本機檔案可以係由密鑰管理器產生嘅副本，但覆寫前仍要交代本機自訂設定點處理。備份密鑰檔本身亦係機密，唔好為咗「有得復原」而到處複製。