在 Replit Deployments 中設定生產級環境變數、持久化 PostgreSQL 資料庫與自訂網域名稱

將 Web 應用程式從原型設計交付至具備生產就緒水準的線上服務，必須依託三大核心基礎架構支柱：安全隔離的敏感憑證管理、高可用且具備持久性的關聯式資料庫，以及具備自動化加密憑證的自訂獨立網域。在 Replit 生態體系中，此項發布與運維作業核心圍繞在 Replit Deployments（在編輯器中呈現為 Publishing 發布工具）。Replit 將容器算力排程、無伺服器 PostgreSQL、金鑰儲存與自動化 DNS/TLS 憑證管理深度整合在同一條交付管線之中。

本篇指南將詳細剖析如何在 Replit Deployments 中正確設定生產環境變數（Deployment Secrets）、掛載持久化 PostgreSQL 資料庫並解決 SSL 連線問題，以及綁定自訂網域名稱並維持長效自動憑證續期。

1. 選擇合適的生產部署架構模型

在配置資料庫與金鑰前，首要步驟是在編輯器中開啟 Publishing（發布）工具，並於 Adjust settings（調整設定）中選擇最符合專案負載的部署類型：

• Autoscale（自動彈性擴縮，推薦 Web 應用與 API 使用）： 生產 Web 應用的預設推薦架構。容器會隨著造訪流量高峰自動增加執行個體，並在流量閒置時自動縮容至零，極大化節省雲端算力支出。極為適合以 Node.js/Express、Next.js、FastAPI、Django 或 Ruby on Rails 構建的全端專案。
• Reserved VM（專用保留虛擬機）： 配置固定規格的獨立虛擬機器，維持全天候不中斷持續運作，具備可預測的月費制成本與獨立運算資源。適用於需要維持持久 WebSocket 長連線、背景工作佇列（如 Celery/BullMQ）或常駐型機器人服務。
• Static（純靜態網站）： 透過全球邊緣節點快取分發前端檔案（HTML/CSS/JS），不包含後端執行環境，亦無法直接連線資料庫或讀取動態環境變數。

對於絕大多數需要處理業務資料庫與保護第三方 API 金鑰的商用系統，Autoscale 或 Reserved VM 是標準選擇。

2. 管理生產環境變數與 Secrets 安全隔離

線上系統中最致命的安全漏洞往往來自憑證外洩，或是開發環境與生產環境的金鑰互相污染。Replit 在設計上將變數生命週期劃分為兩個嚴格隔離的層級：Development Secrets（開發機密） 與 Deployment Secrets（部署機密）。

理解雙層隔離架構

• 開發機密（Development Secrets）： 在 Replit 專案編輯器左側的 Secrets 工具（鎖頭圖示）中設定。這些環境變數僅在開發工作區的編程、即時測試與預覽環境中生效。
• 部署機密（Deployment Secrets）： 僅在發布建置與正式生產容器執行階段注入。雖然首次發布時 Replit 會自動將工作區變數複製到部署設定中，但後續在編輯器工作區中所修改或新增的開發變數，絕不會自動同步至已在線上運作的部署實例。

生產變數配置步驟

1. 區分敏感機密與一般設定： 梳理第三方服務憑證（如 Stripe 金鑰、OpenAI API Key、OAuth Client Secret）。敏感資料必須儲存於 Secrets 中（享有待機 AES-256 加密與傳輸中 TLS 防護）；非敏感設定（如 LOG_LEVEL=info 或公開 CDN 網址）則歸入 Configurations 區塊。
2. 於發布設定中配置 Deployment Secrets： 開啟 Publishing 工具，點選 Adjust settings，進入 Deployment secrets 區塊，核對並填入生產環境專用的金鑰數值。
3. 重新觸發發布（Re-publish）： 更新部署機密後，必須再次點擊 Publish 重新發布，以促使系統建置新容器鏡像並掛載最新生產變數。

於應用程式碼中存取環境變數

Replit 會將設定的金鑰作為標準環境變數注入執行環境中，切勿在版本控制系統中硬編碼預設憑證。

Node.js / TypeScript 範例：

const stripeSecret = process.env.STRIPE_SECRET_KEY;
if (!stripeSecret) {
  throw new Error("生產環境中缺少必要的 STRIPE_SECRET_KEY 變數");
}

Python 範例：

import os

stripe_secret = os.environ.get("STRIPE_SECRET_KEY")
if not stripe_secret:
    raise RuntimeError("生產環境中缺少必要的 STRIPE_SECRET_KEY 變數")

注意： 僅用於工作區預覽的系統專屬變數（例如 REPLIT_DEV_DOMAIN）在生產容器中並不存在。若業務邏輯需要回傳或跳轉網址，請使用已綁定的自訂網域或設定自訂環境變數。

3. 持久化 PostgreSQL 資料庫配置與生產避坑

Replit 專案原生內建了代管 PostgreSQL 服務，但其在開發環境與生產環境中的底層架構存在顯著差異。

架構對比：開發庫（Helium）與生產庫（Neon）

• 開發環境資料庫（Helium 架構）： 託管於 Replit 本地基礎設施，緊鄰工作區運作。提供極低存取延遲與 20 GB 儲存上限。Helium 內部網路不支援 SSL 握手連線，便於本地迅速除錯。
• 生產環境資料庫（Neon 無伺服器架構）： 當應用程式發布時，Replit 會自動佈署獨立的無伺服器 PostgreSQL（由 Neon 提供技術底層）。該資料庫在連續 5 分鐘無查詢時會自動進入休眠以節省運算成本，接收到新請求時能瞬間喚醒，且強制要求客戶端啟用 SSL/TLS 加密連線。

DATABASE_URL 自動注入機制

Replit 會自動維護專案中的 DATABASE_URL 變數：

• 切勿在 Deployment Secrets 中手動覆寫 DATABASE_URL 為開發庫連線字串。發布時，系統會自動將隔離的生產資料庫連線字串綁定至該變數。
• 傳統的離散環境變數（PGHOST、PGPORT、PGUSER、PGPASSWORD）已被 Replit 廢棄，所有主流 ORM（如 Prisma、Drizzle、TypeORM）或底層驅動（如 pg）皆應直接解析單一的 DATABASE_URL。

解決生產環境 SSL 握手失敗的關鍵模式

許多開發者在本地測試正常，但在發布後遭遇 The server does not support SSL connections 錯誤，正是因為驅動強制開啓或關閉了 SSL。正確實作方式是根據 NODE_ENV 執行環境條件式判定：

Node.js（pg 連線池）：

import { Pool } from "pg";

const isProduction = process.env.NODE_ENV === "production";

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: isProduction ? { rejectUnauthorized: false } : false,
});

Drizzle ORM 設定範例：

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: process.env.NODE_ENV === "production" ? { rejectUnauthorized: false } : false,
});

export const db = drizzle(pool);

應對流量高峰：啟用連線池（Connection Pooling）

在 Autoscale 彈性擴縮模式下，流量突增會瞬間拉起多個應用程式複本。如果每個容器都與 PostgreSQL 建立無限制的直連，將迅速耗盡資料庫最大連線數（max_connections）。

1. 前往 Replit 的 Database 工具，檢視生產資料庫設定。
2. Neon 生產資料庫提供連線池端點，其主機名稱帶有 -pooler 後綴（例如 ep-xyz-pooler.region.neon.tech）。
3. 一般高頻業務查詢應指向連線池端點以復用資源；對於需要工作階段等級鎖定的結構遷移（Migration）作業，則維持直連連線。

安全資料結構遷移與 Deployment Previews

進行資料庫結構變更（例如刪除欄位、更動資料型態或新增非空約束欄位）時：

• 使用 Replit 的 Deployment Previews（部署預覽） 功能，在完全隔離的複本環境中驗證遷移腳本，確認業務流程無誤後再套用至正式生產。
• 當生產資料庫自休眠中喚醒時會產生微量延遲，應用程式的開機啟動與資料庫連線重試逾時應設定合理的緩衝期（如 5 至 10 秒）。

4. 綁定自訂網域名稱與長效 TLS/SSL 憑證管理

部署後的專案預設擁有 *.replit.app 子網域。若要打造專業商業品牌與穩定的網路信任度，配置自訂獨立網域（包含 Apex 根網域與子網域）是必備程序。

Replit 透過 DNS 驗證機制全自動完成 Let's Encrypt / Google Trust TLS/SSL 憑證的申請與週期性續約。若 DNS 解析紀錄配置不當或被意外刪除，將導致憑證自動續簽失敗。

自訂網域設定實務流程

步驟一：在 Replit 發布工具中新增網域

1. 開啟 Publishing 工具，切換至 Domains 標籤頁。
2. 輸入您所擁有的自訂網域名稱（例如 example.com）。
3. 系統將列出對應的 A 紀錄 IPv4 位址與專屬的 TXT 驗證字串。

步驟二：至 DNS 代管商新增解析紀錄

登入您的網域註冊商或 DNS 控制台（如 Cloudflare、Namecheap、GoDaddy、AWS Route 53），設定以下解析紀錄：

步驟三：避免常見 DNS 致命錯誤

• 務必永久保留 TXT 驗證紀錄： 這是許多維運人員最常犯的錯誤——誤以為 TXT 紀錄只需用於首次驗證，通過後便從 DNS 面板中刪除。千萬不能刪除！ Replit 仰賴此 replit-verify=... 紀錄在每隔 60 至 90 天自動執行 ACME DNS-01 憑證續約。一旦記錄消失，續約將靜默失敗，當舊憑證過期時瀏覽器將直接彈出不安全警告。
• 移除衝突舊紀錄： 務必刪除根網域下殘留的其他 A 紀錄與所有 AAAA（IPv6）紀錄。多餘的 AAAA 紀錄會干擾 Replit 邊緣閘道的憑證簽發與流量轉發。
• 關閉 Cloudflare 橘色雲朵代理： 若使用 Cloudflare 管理 DNS，務必將 Proxy 狀態切換為 DNS only（僅限 DNS，灰色雲朵）。外層代理會攔截驗證握手，阻礙 Replit 節點獲取有效 SSL 憑證。

子網域設定與 www 規範化重新導向

在 Replit 路由架構中，根網域與子網域為獨立實體：

• 綁定根網域 example.com 不會自動支援 www.example.com。
• 若希望同時支援兩種存取方式，必須在 Domains 標籤頁中將 www.example.com 作為獨立項目新增，並取得其專屬的 A 紀錄與以 www 為主機名稱的 TXT 驗證紀錄。
• 在 DNS 代管商處設定 301 永久重新導向（將 www 導向根網域，或由根網域導向 www），確保 SEO 權重集中並避免重複內容收錄。

5. 生產上線檢查清單

在正式將終端使用者流量切換至 Replit 部署前，請完成以下全方位驗證：

1. 環境變數安全檢核：
   • 檢查 Publishing → Adjust settings → Deployment secrets，確認生產所須之 API Key 與設定項完整無缺。
   • 確認程式庫與設定檔中完全杜絕硬編碼之測試敏感金鑰。
   • 變更設定後確實執行了一次 Re-publish（重新發布）。
2. 資料庫連線穩定度驗證：
   • 確認資料庫驅動程式已依據 NODE_ENV === "production" 條件式啟用 SSL 連線。
   • 確認應用程式依託系統注入之 DATABASE_URL，無任何手動覆寫。
   • 驗證容器重啟與自動擴展時，資料庫連線能正常復用且無逾時異常。
3. 網域與安全性狀態：
   • Replit 控制台內的已綁定網域皆顯示綠色 Verified（已驗證） 標記。
   • 確認 DNS 控制台內已妥善永久保存 replit-verify 的 TXT 紀錄。
   • 透過各類瀏覽器測試，確認全站皆能以有效 HTTPS 正常載入。
4. 監控與地域配置：
   • 啓用 Publishing 面板中的 Monitoring tools（監控工具），在服務異常或 HTTP 錯誤率上升時能即刻收到警報通知。
   • 確認部署地域（Deployment geography）鄰近目標使用者（注意：一旦發布即鎖定區域，日後若需遷移須透過 Remix 專案進行）。

透過落實開發與生產環境的變數分離、撰寫環境自適應的資料庫 SSL 連線邏輯，並確保 DNS 驗證紀錄長久有效，開發團隊即可在 Replit Deployments 上構築出兼具擴充彈性、資安合規與高可用性的商用級 Web 應用系統。

參考資料

• Publishing - Replit
• Secrets - Replit
• Development and production databases - Replit
• Custom Domains - Replit
• Deployment types - Replit