For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/modules/config.md (or send Accept: text/markdown).

環境與配置

整個工作區唯一的已驗證模式。

詢問本指南

進行一項配置更改並檢查它

從正在執行的 Web 應用程式開始。在編輯器中開啟apps/web/.env.local；如果不存在，請使用 Web 教程將 .env.example 複製到那裡。對於無害的首次檢查，請找到 EMAIL_PROVIDER=local 並將其保留在本地。此設定將產品電子郵件傳送到本地預覽而不是真正的收件箱。不要將 KEY=value 線貼上到終端中。

對於您啟用的每項服務，請遵循該提供商的設定指南，僅替換指定值，儲存檔案，使用 Ctrl + C 停止 Web 伺服器，然後使用以下命令重新啟動。如果驗證指定了丟失的金鑰，請重新開啟此檔案並將該金鑰與提供程式指南進行比較。僅對資料庫遷移使用的值保持 root .env 同步；單獨複製它不會配置 Next.js。

corepack pnpm --filter @supastack/web dev

從環境示例開始

根目錄的 .env.example 是配置清單。共享校驗在 packages/config。把選定的應用環境與供應商模式放在一起審閱；本地介面並不等於生產憑證策略。

無憑證的參考模式要求 local/test 應用配置與 fake/本地供應商。選擇生產供應商會改變執行要求。

讓金鑰留在 API 之後

認證金鑰、資料庫憑證、供應商金鑰、Stripe 金鑰與 Trigger 憑證都屬於服務端。絕不要給它們加 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 字首。安裝過程中不要列印它們，也不要把它們放進錯誤響應。

瀏覽器只拿到公開配置與允許的模型別名。工作區歸屬、許可權決策、預算與供應商選擇都由服務端強制執行。

先用再信：檢查變更

通過現有的 config 包校驗配置，並執行相關的確定性測試。準備好驗證真實整合時，再走單獨 opt-in 的供應商冒煙路徑。

corepack pnpm test
corepack pnpm check
corepack pnpm build

安裝與配置

packages/config 是唯一解析 process.env 的地方:zod 模式產出型別化的 ServerConfig 和 PublicConfig,提供商選擇以 kinds 表達 —— providers.ai、providers.billing、providers.email、providers.jobs、providers.storage 各自解析為一個命名的介面卡及其必填欄位。

啟用提供商會使其憑據成為必填:開啟社交登入、s3 儲存 kind 或 resend 郵件 kind 會讓啟動失敗並指出缺失的變數,而不是之後在執行時出現意外。

STORAGE_PROVIDER=s3
STORAGE_BUCKET=kit
STORAGE_ENDPOINT=https://s3.example
STORAGE_PUBLIC_BASE_URL=https://cdn.example
# → config rejects the env if a required field is missing

實現流程

在伺服器邊界通過 parseServerConfig 讀取配置,並將型別化的值向內傳遞 —— 不要在功能程式碼中觸碰 process.env。公共配置是一個單獨的、刻意保持小巧的物件,可以安全地序列化給客戶端。

產品專屬的 env 屬於消費產品自己的模式。不要為單個產品的需求而膨脹套件模式。

驗證與排障

更改模式後執行 config 包測試,並確認缺失的必填變數會在錯誤中指明自身。本地能解析但生產中不能解析的 env 通常意味著一個未檔案化的必填欄位。