為什麼本機可以跑，上線卻失敗？一次搞懂環境變數與正式環境

「我在本機明明測過，按鈕可以點、資料也能存，為什麼一上線就壞了？」

這幾乎是每個用 Vibe Coding 做產品的人都會遇到的時刻。

你可能花了一個晚上把功能做完，在自己的電腦上看起來一切正常；部署後，卻發現登入失敗、表單送不出去、付款沒有反應，或畫面乾脆是一片空白。

先別急著懷疑自己，也不一定是 AI 把程式寫壞了。更常見的原因是：你的本機和正式環境，其實不是同一個世界。

它們可能使用不同的網址、不同的資料庫、不同的金鑰、不同的權限，甚至不同版本的程式套件。本機能跑，只代表它在你目前這台電腦、這組設定下能跑；不代表它已經準備好交給所有使用者。

先用一個比喻理解：本機是你的廚房，正式環境是餐廳

在自己的廚房做菜時，你知道鹽放在哪、瓦斯怎麼開、哪些食材在冰箱裡。

正式開餐廳後，廚房變大了，但你得重新確認：

• 食材有沒有送到？

• 瓦斯有沒有接好？

• 每個人是否有權限進廚房？

• 菜單上的品項，是否真的都供應得出來？

• 顧客點餐後，訂單會不會送到廚房？

本機環境就是你熟悉的廚房；正式環境則是使用者真正會進入的餐廳。

兩邊的程式碼可能相同，但設定與條件不同。部署的工作，就是把這些條件補齊。

最容易搞混的三件事

1. 本機網址和正式網址不同

你在電腦上看到的網站，可能是：

http://localhost:3000

正式網站則可能是：

https://your-product.com

許多服務會認得網址。例如登入、第三方 API、付款服務或 Email 驗證，常需要先登記「允許從哪個網址呼叫」。

如果服務只認得本機網址，正式網站的請求就可能被拒絕。

你可以把它理解成門禁系統：你原本登記的是「公司內部入口」，但使用者是從「大門」進來。地址不同，門自然打不開。

2. 本機有設定，正式環境沒有

這是最多人遇到的原因。

本機通常會有一個設定檔，裡面放著資料庫連線、API 金鑰、第三方服務密碼等資訊。這些內容不該直接寫死在程式裡，因此常被放進「環境變數」。

例如：

DATABASE_URL=
OPENAI_API_KEY=
PAYMENT_SECRET_KEY=
NEXT_PUBLIC_APP_URL=

你的電腦知道這些值，因為你已經設定過；但部署平台不會自動知道。

如果沒有把必要的環境變數填進正式環境，常見結果包括：

• 網站畫面能開，但資料讀不到。

• 登入按鈕沒有反應。

• 表單送出後出現錯誤。

• AI 功能無法回覆。

• 付款、寄信或通知失敗。

3. 本機資料和正式資料不是同一份

你在本機測試時，可能使用的是測試資料庫，裡面已有你建立過的帳號、範例內容和假訂單。

正式環境可能連到另一個全新的資料庫，裡面什麼都沒有；也可能根本還沒有成功連線。

因此，「我本機看得到資料」不能證明正式站也讀得到。你要驗證的是：正式網站能不能新增、讀取、更新，並在重新登入後仍正確顯示資料。

環境變數到底是什麼？

環境變數可以把它想成：不應公開、但程式必須知道的設定小紙條。

程式碼告訴系統「我要連資料庫」；環境變數則告訴它「資料庫在哪裡、用什麼密碼連」。

它特別適合放這類資訊：

• API Key

• 資料庫連線網址

• 第三方服務的密鑰

• 正式網站網址

• Email 寄信設定

• 付款服務設定

• 開關功能的設定值

反過來說，以下資訊不該放進環境變數，也不該被寫進前端：

• 使用者密碼

• 個資內容

• 不該公開的管理者權限

• 只限伺服器使用的金鑰

一個很重要的原則是：只要使用者能在瀏覽器裡看見，它就不再是秘密。

所以即使你的開發框架允許某些變數被前端讀取，也要先確認那組值本來就可以公開。

上線後壞掉時，先從這 5 個地方檢查

1. 部署平台的環境變數有沒有補齊？

先列出本機使用的變數，再到部署平台逐一核對。

你不需要直接分享金鑰內容；只要確認：

• 變數名稱是否完全一致？

• 正式環境是否有設定？

• 值是否貼完整？

• 設定後是否有重新部署？

少打一個底線、漏掉一個字母，系統就會把它視為不同變數。

2. 正式網址有沒有登記到第三方服務？

如果你使用登入、付款、資料庫、Email、AI API 或其他外部服務，查看它們的後台設定：

• 是否有加入正式網站網址？

• Redirect URL 是否仍指向 localhost？

• Webhook 或 Callback URL 是否正確？

• 是否仍在測試模式？

這一項特別容易出現在 Google 登入、GitHub 登入、Stripe 付款、Email 驗證與 OAuth 串接。

3. 你連的是測試資料庫，還是正式資料庫？

確認正式環境連到哪一個資料庫，以及資料表是否已建立。

如果你新增了欄位、修改了資料結構，別忘了正式資料庫也需要同步更新。否則畫面雖然發布了，資料庫卻還停在舊版本。

4. 錯誤訊息真正說了什麼？

不要只看「網站壞了」。打開部署平台的 Logs，找第一個真正的錯誤訊息。

常見關鍵字包括：

• Missing environment variable

• Unauthorized

• CORS

• Database connection failed

• Invalid API key

• Build failed

你可以把錯誤訊息連同相關程式碼貼給 AI，請它協助翻譯與提出排查順序；但不要直接把完整金鑰或個資貼進對話。

5. 正式環境是否需要重新部署？

許多平台在新增或修改環境變數後，不會自動套用到已經發布的版本。

所以你改完設定後，記得重新部署，再重新測一次核心流程。

一套非工程師也能執行的排查順序

當產品在正式環境出錯時，先照這個順序，不要同時亂改很多地方：

1. 重現問題：確認是哪一頁、哪個按鈕、哪個帳號會出錯。
2. 看 Logs：找到第一個明確錯誤，而不是猜原因。
3. 對照本機與正式環境：網址、環境變數、資料庫、第三方設定。
4. 一次只改一項：改完重新部署，再測同一條流程。
5. 記錄結果：哪個設定造成問題、怎麼修好，寫回你的部署 SOP。

這樣做雖然不如「再叫 AI 重寫一次」來得痛快，但更快找到真正原因，也不會因為同時改太多而失去線索。

上線前必備檢查表

【網址與登入】
□ 正式網址可正常開啟
□ 登入、登出、重新登入都能完成
□ Redirect URL 與 Callback URL 已加入正式網址

【環境變數】
□ 本機使用的必要變數已列清楚
□ 正式環境已補齊相同名稱的變數
□ 金鑰沒有被放進前端或公開程式碼
□ 修改設定後已重新部署

【資料與第三方服務】
□ 正式資料庫已連線並完成必要結構更新
□ 可新增、讀取、修改測試資料
□ Email、付款、通知等外部服務已實測
□ 測試模式與正式模式設定正確

【出錯後】
□ 知道在哪裡查看 Logs
□ 保留上一個可用版本
□ 有測試帳號與核心流程可重新驗證

把「部署」當成產品的一部分

Vibe Coding 讓你更快完成產品的第一版，但它不會自動替你處理所有正式環境的差異。

真正成熟的做法不是從此不出錯，而是每次出錯後，都能把排查方式留下來。第一次你可能花兩小時才發現少了一個 API Key；下一次，你的部署檢查表會在發布前就提醒你。

本機成功，是一個很好的開始。正式環境成功，才代表你的產品真的走到了使用者面前。