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

> 環境變數、Development／Preview／Production、新部署，以及如何在 Next.js 中安全檢查金鑰而不將密鑰傳送至瀏覽器。

Source: https://ailoot.ai/blog/zh-hant-tw/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/zh-hant-tw/vercel-environment-variables/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-5834389902760cc2f923caab0f53ee3e11657b6149e578f1b00a9922a7f572cf


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="本節重點">

重點

如果包含密鑰的`.env`檔案不在 Git 中，請在 Vercel 專案的**Environment Variables**區段新增所需變數。選取環境、儲存設定，並建立新的部署：已部署的版本不會變更。在 Next.js 中，請勿在密鑰前加上`NEXT_PUBLIC_`前綴：建置期間，其值會被包含在瀏覽器程式碼中。

</div>

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



[Ailoot 實用資訊請參閱文件](https://ailoot.ai/docs/)。

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

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

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

如果您仍不確定哪些內容可以存放在原始碼檔案中，請先參閱[使用 AI 建置的專案安全性檢查](https://ailoot.ai/blog/zh-hant-tw/vibe-coding-security/)。本指南處理的是更具體的問題：如何為特定的 Vercel 部署設定組態。

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

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

| 檢查項目 | 可能的選項 | 為何重要 |
|----|----|----|
| Vercel 環境 | Development、Preview、Production | 設定必須套用至您要檢查的版本 |
| 讀取位置 | 伺服器或瀏覽器 | 私密金鑰不得包含在用戶端程式碼中 |
| 讀取時機 | 建置時或伺服器函式執行時 | 在 Next.js 中，公開值會在建置時固定 |

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

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

如果您尚未辨識出使用的框架，請要求代理程式根據專案檔案判斷。[Astro 與 Next.js 的比較](https://ailoot.ai/blog/zh-hant-tw/astro-vs-nextjs-for-ai-built-sites/)可協助您了解兩者差異；`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`直接讀取此變數，重新建置後便可在介面中預期的位置顯示該標籤。這項檢查只能確認公開設定已成功傳入。

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

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

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

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

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

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

| 症狀 | 檢查項目 |
|----|----|
| 本機運作正常，但 Preview 無法運作 | 專案的 Preview 設定中是否存在該名稱；是否選取了不同的分支 |
| Preview 運作正常，但 Production 無法運作 | 該名稱是否已設定於 Production；儲存後是否已建立新的主要版本 |
| 某個 Preview 分支的行為不同 | 是否有相同名稱的值設定給該分支並覆寫一般設定 |
| 伺服器看得到變數，但瀏覽器看不到 | 在 Next.js 中，對非公開變數而言這是預期行為；不要將私密金鑰移至瀏覽器 |
| 公開的 Next.js 標籤仍顯示舊值 | 是否已使用所需的值進行新建置；您開啟的 URL 是否屬於該部署 |
| 公開名稱正確，但替換沒有作用 | 程式碼是否以`process.env[varName]`動態讀取；Next.js 不會將這類參照內嵌替換 |

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

遷移至自己的伺服器需要不同的程序：請參閱[使用 Coolify 部署專案的指南](https://ailoot.ai/blog/zh-hant-tw/coolify-claude-code-deploy/)。Vercel 的按鈕名稱和設定步驟不適用於該流程。

<div class="section" role="doc-bibliography" aria-label="來源">

### 來源

- [Vercel 環境變數](https://vercel.com/docs/environment-variables)
- [新增及管理 Vercel 環境變數](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Next.js 環境變數](https://nextjs.org/docs/app/guides/environment-variables)

</div>





[前往 Ailoot](https://ailoot.ai/)。

## 常見問題：Vercel：Git 中沒有 .env 時的環境變數設定

### 在 Vercel 儲存變數後，為什麼仍是 undefined？

檢查專案、環境及分支特定範圍，再建立新部署。既有部署不會只因保存新設定就取得該變數。

### 能加 NEXT_PUBLIC_ 讓 Next.js app 讀到機密嗎？

不要對機密使用此前綴，因為建置時值會寫入瀏覽器程式碼。請留在伺服器端，驗證存在即可，不要印出金鑰。


## Ailoot · 公司及其專案組合

Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。

公司及其專案組合：數百萬客戶，每月銷售額達數十億。

Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。