設定自定義域名

安裝與配置

在執行任何步驟之前，請閱讀開始之前 和終端基礎知識。這些說明假設您在 VS Code 中開啟了完整的 supastack monorepo；它的根 package.json 標記儲存庫根。在 pnpm 命令中，工作區包是應用程式或共享程式碼資料夾；在產品中，工作空間是團隊的資料容器和安全邊界。 corepack pnpm --filter ... 從 monorepo 選擇一個包，同時從其根執行命令。如果您僅開啟同步的移動或桌面資料夾，則它不包含 Web 後端、Docker 設定或根指令碼：從此 monorepo 或可訪問的託管伺服器執行後端，並使用平臺資料夾自己的指令碼。環境變數是儲存在本地 .env 檔案或託管儀錶板中的命名設定；更改後重新啟動相關應用程式，並將伺服器機密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1. 開啟 apps/web/.env.local 並使用 CUSTOM_DOMAINS_PROVIDER=local 預覽沒有 DNS 更改的域螢幕。

2. 對於真實的客戶主機名，請使用您自己的區域、僅限於該區域的 API 令牌以及 CNAME 目標配置 Cloudflare for SaaS；在 Web 主機上輸入僅用於伺服器的值，而不是在瀏覽器中輸入。

3. 使用 corepack pnpm --filter @supastack/web dev 執行 Web，並以工作區所有者/管理員身份開啟設定 → 域。預期：本地介面卡立即啟用測試域； Cloudflare 介面卡等待顯示的 DNS 記錄。

將 CUSTOM_DOMAINS_PROVIDER=cloudflare 設定為 CLOUDFLARE_API_TOKEN、CLOUDFLARE_ZONE_ID 和 CUSTOM_DOMAIN_CNAME_TARGET。 API 令牌需要 SSL 和證書：區域的編輯許可權（自定義主機名 API 位於 /zones/{zone_id}/custom_hostnames 下）。 CNAME 目標是 Cloudflare 區域中的主機名（例如customers.example.com），可解析為您部署的應用程式。

在區域中新增一條 DNS 記錄，將 CNAME 目標指向您的源（Cloudflare 中 SaaS 術語的後備源）。 Cloudflare 為每個自定義主機名頒發一個 DCV TXT 記錄以及一個可選的所有權 TXT 記錄；設定螢幕向客戶準確顯示要建立哪些記錄。

對於本地開發，請使用 CUSTOM_DOMAINS_PROVIDER=local，它將每個主機名標記為立即與目標客戶處於活動狀態。localhost。 CUSTOM_DOMAINS_PROVIDER=off（預設值）隱藏該部分的控制元件。

CUSTOM_DOMAINS_PROVIDER=cloudflare
CLOUDFLARE_API_TOKEN=cf_token_with_ssl_edit
CLOUDFLARE_ZONE_ID=zone_id
CUSTOM_DOMAIN_CNAME_TARGET=customers.example.com

要複製的命令

按照註釋檢視命令在哪個資料夾中執行。如果標記了兩個終端，請開啟兩個終端視窗，並在使用第二個命令時保持第一個命令執行。

corepack pnpm --filter @supastack/web dev

實現流程

工作區所有者和管理員在“設定”→“域”下管理域（每個工作區五個）。客戶將其主機名的 CNAME 記錄指向 CNAME 目標，新增顯示的 TXT 記錄以進行所有權和證書驗證，然後按重新整理狀態。一旦 Cloudflare 報告主機名處於活動狀態，它就會成為該部署上的身份驗證的可信來源，並且工作區名稱/徽標會成為該主機名上應用程式鑲邊的品牌。

大多數 DNS 提供商的 Apex（根）域不能是 CNAME — 客戶應使用 Portal.example.com 等子域或具有 CNAME 扁平化功能的提供商。 Cookie 的範圍僅限於每個主機，因此客戶域是單獨的登入；跨自定義域的單點登入超出了範圍。

驗證與排障

如果 Cloudflare 保持待處理狀態，請將客戶的 CNAME 和 TXT 記錄與域卡上顯示的確切值進行比較，並留出 DNS 時間進行更新。當 DNS 提供商無法展平根域 CNAME 時，請使用子域。如果選單不存在，請檢查該功能是否已啟用以及登入使用者是否是工作區所有者或管理員。

長時間等待通常意味著客戶的 CNAME 丟失或仍在傳播 - 重新檢查域卡上顯示的 DNS 記錄。移動或失敗狀態意味著 Cloudflare 無法再解析該區域的主機名；刪除並重新新增它。驗證資料儲存為提供程式 JSON，因此未來的 Cloudflare 驗證形狀不需要更改架構。