Vercel：Git 中沒有 .env 時的環境變數設定

本指南適用於已託管在 Vercel 上的專案。您需要有權存取專案設定，並了解應用程式會讀取哪些變數。以下範例適用於 Next.js；其他框架的變數名稱無法自動沿用。本指南根據官方文件編寫，尚未在實際帳戶上測試。

Ailoot 實用資訊請參閱文件。

為什麼不需要將 .env 加入 Git#

環境變數是應用程式從原始碼之外接收的一項設定，包含名稱和值。例如，SERVICE_API_KEY這個名稱可讓程式存取外部服務的金鑰值。請勿在本指南、與代理程式的對話或儲存庫中放入金鑰本身。

Next.js 可以從本機.env*檔案載入變數。不過，本機檔案與 Vercel 中的專案設定是兩個不同的位置。如果檔案沒有推送至儲存庫，就必須另外在託管平台設定這些值。標準的create-next-app範本會將.env檔案加入.gitignore；Next.js 文件也提醒，幾乎不應將這些檔案推送至儲存庫。

如果您仍不確定哪些內容可以存放在原始碼檔案中，請先參閱使用 AI 建置的專案安全性檢查。本指南處理的是更具體的問題：如何為特定的 Vercel 部署設定組態。

首先，確認應用程式在哪裡讀取變數#

輸入任何值之前，請先列出名稱，不要列出密鑰本身。每個名稱都需要確認三件事：它會用在哪個環境、讀取變數的程式碼在哪裡執行，以及何時需要這個值。

Development環境供本機開發使用。Preview用於預覽部署，Production則是主要的已發布版本。Preview 可以為特定 Git 分支設定值：這些設定會以相同名稱覆寫一般的 Preview 設定。

在 Next.js 專案中，未加上NEXT_PUBLIC_的變數預設可在伺服器上使用。加上NEXT_PUBLIC_前綴後，該值可以嵌入傳送至瀏覽器的 JavaScript。這適用於明確公開的設定，例如非密鑰的版本標籤，但不適用於私密 API 金鑰。即使沒有這個前綴，應用程式程式碼也不得手動將密鑰傳回用戶端。

如果您尚未辨識出使用的框架，請要求代理程式根據專案檔案判斷。Astro 與 Next.js 的比較可協助您了解兩者差異；NEXT_PUBLIC_規則並不適用於所有 React 應用程式。

託管設定是使用 AI 代理程式開發應用程式時會涉及的工作之一。

如何在 Vercel 專案中新增變數#

請自行在官方控制面板中執行這些步驟。不要將真正的金鑰交給代理程式代填表單，也不要附上包含金鑰值的螢幕截圖。

1. 開啟 Vercel 控制面板，選取正確的專案。不要只依據儲存庫名稱是否相符來判斷；請確認您設定的是預計要開啟的應用程式。
2. 在專案設定側邊欄前往Environment Variables。
3. 在Name欄位輸入應用程式會讀取的名稱，例如SERVICE_API_KEY。這只是名稱範例；如果程式碼預期的是其他名稱，請使用其完全相同的拼法。
4. 在Value欄位輸入憑證儲存處中的值。請勿將它放入原始碼、聊天內容或驗證記錄中。
5. 選取需要此設定的環境。使用Preview檢查預覽版本，使用Production檢查主要版本。不要自動將同一個密鑰指派給所有環境。
6. 如果 Preview 設定適用於特定分支，請檢查所選分支，以及是否有相同名稱的覆寫設定。
7. 按一下Save。

Vercel 專案變數在建置期間以及伺服器端 Vercel Functions 執行時都可以使用。不過，值可以在 Vercel 內使用，不代表可以傳送至瀏覽器：這取決於應用程式程式碼和框架規則。

為什麼儲存後需要新的部署#

儲存變數不會變更現有部署。Vercel 文件要求重新部署專案，新的設定才會套用至您使用的版本。

透過 Git 工作時，您可以將提交推送至Production Branch指定的分支，建立新的 Production 部署；推送至其他分支則可建立 Preview 部署。不要假設主要分支一定是main：請檢查專案設定。這應該是正常且已商定的專案發布流程，不要將密鑰檔案加入提交。

啟動部署後，請等候建置完成，然後開啟新部署的 URL。記錄該 URL、環境和分支。如果您檢查的是某個舊部署的 URL，就不會看到新的設定。

Next.js 還有另一項條件：像process.env.NEXT_PUBLIC_RELEASE_LABEL這樣的參照會在執行next build時替換成其值。建置完成後，該值便固定下來。若不重新建置，只變更設定不會改寫已傳送的用戶端 JavaScript。

如何在不暴露金鑰的情況下檢查結果#

先使用安全範例：名稱為NEXT_PUBLIC_RELEASE_LABEL、值為preview-check，且明確不含密鑰的標籤。這些只是名稱和文字範例，並不是金鑰，也不是在此處實際執行的測試。如果 Next.js 應用程式透過process.env.NEXT_PUBLIC_RELEASE_LABEL直接讀取此變數，重新建置後便可在介面中預期的位置顯示該標籤。這項檢查只能確認公開設定已成功傳入。

私密金鑰必須以不同方式檢查。不要輸出其值、部分內容、長度或整個process.env。不要建立會回傳變數內容的公開 URL。首先只檢查伺服器上該設定是「存在／不存在」，接著另行檢查使用該服務的應用程式函式。設定存在不代表金鑰有效或具備所需權限。

您可以在不包含密鑰的情況下記錄結果：

• 專案、環境和分支與設定時所選的項目相符；
• 您檢查的是儲存變數後建立的新部署 URL；
• 建置已完成，且所需的應用程式函式已使用安全的測試資料執行；
• 密鑰沒有暴露在瀏覽器、API 回應、記錄或對話中。

如果函式會處理付款、傳送訊息或執行其他會造成影響的操作，請使用服務指定的測試模式。檢查設定本身並不代表已授權執行實際操作。

如果值仍是 undefined，該檢查什麼#

undefined表示在該存取位置沒有取得值。請依序檢查名稱、環境和版本，不要一次變更所有設定。

確認名稱、環境和新版本後，如果函式仍發生錯誤，這並不能證明變數是原因。請調查特定的伺服器端程式碼錯誤，不要公開包含密鑰的診斷資料。本指南不保證能解決所有 HTTP 500 回應。

遷移至自己的伺服器需要不同的程序：請參閱使用 Coolify 部署專案的指南。Vercel 的按鈕名稱和設定步驟不適用於該流程。

前往 Ailoot。