Cloudflare 站台部署筆記

這篇文章整理一套適合小型網站、工具站與文件站的 Cloudflare 部署流程。內容從網域申請、靜態網站上線、自訂網域、寄信服務、API Worker，一路延伸到 Cloudflare Tunnels 串接家中私有伺服器，目標是把前台、API 與內部服務放進同一套可維護的架構裡。

如果你手上有一個已經可以正常建置的前端專案，並且希望：

• 使用自己的正式網域，而不是平台預設網址
• 讓主站、工具站、文件站共用同一個主網域
• 以 Cloudflare Pages 部署靜態站台
• 以 Cloudflare Workers 提供 API 能力
• 以 Resend 實作網站寄信功能
• 以 Cloudflare Tunnels 安全連回家中私有 API

那麼這篇文章可以作為一份完整的實作筆記。

流程總覽

如果你想先掌握整體順序，可以先看這個版本的部署流程：

1. 申請主網域，規劃主站、工具站與 API 的子網域
2. 在本機完成前端專案 build
3. 將靜態網站部署到 Cloudflare Pages
4. 綁定自訂網域與 www
5. 在 Resend 完成寄件網域驗證並申請 API Key
6. 建立 Cloudflare Worker，作為前端與外部服務之間的後端入口
7. 將 API Key 與其他敏感設定寫入 Cloudflare Secrets
8. 如果 Worker 需要呼叫家中的私有 API，再使用 Cloudflare Tunnels 建立安全連線

這個順序的核心原則是：先讓公開站台穩定上線，再補上後端能力，最後才處理私有服務的對接。這樣在排查問題時，會比較容易知道問題是出在前端部署、DNS、Worker 還是 Tunnel。

架構概念

在開始操作之前，先把整體架構想清楚會比較容易。本文對應的部署模型大致如下：

• wan-shi-wu.com：主站
• info.wan-shi-wu.com：文件站或教學站
• json.wan-shi-wu.com：工具站
• api.wan-shi-wu.com：Cloudflare Worker 或 API 入口

這種做法的好處是，所有服務都掛在同一個主網域底下，品牌識別一致，DNS 管理集中，也方便在後續把不同服務拆成獨立站台與獨立部署流程。

如果用責任來區分，可以再進一步拆成三層：

• 前端展示層：由 Cloudflare Pages 提供靜態頁面
• 邊緣邏輯層：由 Cloudflare Workers 處理寄信、驗證、轉送與 API 組裝
• 私有服務層：由家中的私有伺服器提供內部 API，再透過 Tunnel 受控對外

這種分層方式的好處是，每一層都可以獨立調整與替換。例如你可以只更新前端頁面，而不影響 Worker；也可以只調整私有 API，而不需要重部署整個公開站台。

部署前準備

正式部署之前，建議先完成以下檢查：

• 專案可以在本機正常 build
• 網域已經申請完成，或已確定要使用的網域名稱
• 前端與 API 的網址規劃已經先想好
• 若有寄信需求，已規劃好寄件網域
• 若有私有後端需求，已確定要透過 Tunnel 對接的服務與 port

此外，建議在正式上線前先確認這幾個實務細節：

• 正式網域與測試網域是否已區分清楚
• 前端是否有寫死本機網址，例如 localhost
• Worker 需要的第三方憑證是否都已申請完成
• 若使用 Docker Compose，container service name 與 port 是否已固定
• 若站台會處理表單或登入資訊，是否已有基本的驗證與 rate limit 設計

如果前端專案是以 Vite 建置，至少要先確認：

npm install
npm run build

只要本機 build 無法穩定完成，後續部署到 Cloudflare 時通常只會放大問題，而不會解決問題。

第 1 步：申請自己的網域

真正要讓網站長期對外提供服務，第一件事通常不是先部署程式，而是先準備一個自己的網域。沒有正式網域，站台雖然可以暫時使用平台提供的預設網址上線，但在品牌識別、SEO、子網域規劃與後續搬遷彈性上都會受到限制。

對多站台架構而言，主網域本身就是整體入口。先把主網域規劃好，後續不論是主站、文件站、工具站，還是獨立 API，都能用一致的命名方式整理。

在 Cloudflare 搜尋並申請自己的網域。點擊圖片可放大檢視。

常見命名方式例如：

• wan-shi-wu.com：主站
• info.wan-shi-wu.com：文件站
• qrcode.wan-shi-wu.com：QRCode 工具
• json.wan-shi-wu.com：JSON 工具
• invoice.wan-shi-wu.com：發票工具

在規劃子網域時，建議一開始就保留清楚的職責邊界，不要讓同一個子網域同時承載太多不同用途。舉例來說，前端頁面與 API 最好不要共用同一個網址，這樣在做 CORS、快取策略、憑證管理與後續除錯時都會輕鬆很多。

如果直接在 Cloudflare 申請網域，實務上有幾個很明顯的優點：

• 網域註冊與 DNS 管理集中在同一個平台
• 後續接 Pages、Workers、Redirect Rules、SSL 時流程更順
• 多子網域架構更容易管理
• 排查問題時，不需要在註冊商與 CDN 之間來回切換
• 未來擴充新站台或新服務時，維運成本更低

第 2 步：部署純前端網站

當前端網站開發完成之後，先在本機完成正式編譯，確認要部署的靜態檔案可以正常產出。這一步的重點是先排除建置問題，不要等到丟上平台之後才發現 build 失敗。

如果專案使用 Vite：

npm run build

編譯完成後，登入 Cloudflare 後台，進入 Compute -> Workers & Pages，建立一個新的 application。對 Cloudflare 而言，這個 application 就是你的站台專案，後續會由它負責站台部署、版本更新與網域綁定。

前端專案編譯完成後，到 Cloudflare 的 Compute -> Workers & Pages 建立新的 application。點擊圖片可放大檢視。

如果這次部署的是整個純前端網站，而且你已經在本機完成 build，那麼可以直接選擇 Upload your static files。這種方式適合單純部署靜態網站，不一定要先串接 Git 倉庫。

通常要上傳的會是 dist 資料夾，也就是 npm run build 之後的輸出結果。Cloudflare 會把其中的 HTML、CSS、JavaScript 與其他靜態資源，作為完整網站內容來部署。

因為是部署整個純前端網站，所以選擇 Upload your static files，將編譯完成的資料夾拖入並進行 Deploy。點擊圖片可放大檢視。

部署完成後，Cloudflare 會先提供一個預設網址。建議先用這個網址確認首頁、資源載入、按鈕與路由行為都正常，再進一步綁定正式網域。

如果未來這個站台會長期維護，實務上仍然建議在第二階段改成串接 Git 倉庫自動部署。手動上傳靜態檔適合前期驗證、單次上線或快速修補，但當更新頻率變高之後，透過 Git 觸發 build 與 deploy 會更容易追蹤版本，也比較不容易漏掉檔案。

第 3 步：設定自訂網域與 www

站台部署成功之後，Cloudflare 會先分配一個 Workers Subdomain，這個網址通常也會被稱為 Preview URL 或 workers.dev 網址。它的用途是讓你在正式掛網域之前，先完成第一輪功能驗證。

部署成功後，Cloudflare 會先提供一組 Workers Subdomain，也就是常說的 Preview URL 或 workers.dev 網址。點擊圖片可放大檢視。

預覽網址適合拿來確認：

• 首頁是否正常開啟
• 圖片與靜態資源是否載入成功
• 站內頁面切換是否正常
• 手機版與桌面版畫面是否可用

確認沒問題後，再把站台綁到自己的正式網域。做法是進入該 worker 或 application，切換到 Settings 頁籤，點擊右上角的 Add，然後在 Custom domain 輸入你想綁定的子網域，例如 info.wan-shi-wu.com 或 json.wan-shi-wu.com。

進入 worker 的 Settings 頁籤後，點擊右上角 Add，並在 Custom domain 輸入剛剛申請的子網域。點擊圖片可放大檢視。

完成後，Cloudflare 會協助你把這個自訂網域綁定到目前的站台上。

如果你希望使用者輸入 www 開頭時也能順利進站，就還要補一筆 www 的 DNS 設定。做法是回到 Cloudflare 的 Domains -> Overview，點進你的網域，再進入左側的 DNS -> Records，新增一筆 CNAME：

• Name：www
• Target：你的主網域，例如 wan-shi-wu.com

請特別確認右側的橘色 Proxied 已經開啟。只有在 Proxy 生效的情況下，這筆 DNS 記錄才會真正走 Cloudflare 的代理層，連帶獲得 HTTPS、快取與基本安全防護。

進入 Domains -> Overview 後，在 DNS -> Records 新增一筆 CNAME，讓 www 指向你的主網域，並確認橘色 Proxied 已開啟。點擊圖片可放大檢視。

完成後建議再檢查：

• 主網域是否正確指向主站
• www 是否可以正常進站
• 各子網域是否指向正確站台
• HTTPS 憑證是否已正常簽發

如果你的站台同時有主站、文件站與 API，這一步也建議順手確認：

• 前端是否真的呼叫到正式 API 網域，而不是 preview URL
• www 是否需要導向裸網域，或反過來統一到 www
• 是否存在重複內容網址，避免 SEO 上產生兩個可索引入口

第 4 步：使用 Resend 建立網站寄信能力

如果網站需要聯絡表單、通知信、自動回覆信或交易郵件，那就需要一套穩定的郵件服務。本文示範使用 Resend，原因是它對 Cloudflare Worker 這類架構相對友善，對小型網站來說上手成本也低。

使用 Resend 的優點包括：

• 後台介面清楚，流程容易理解
• 與自有網域整合方便，可使用自己的網域寄信
• API 設計簡單，適合快速串接表單與通知流程
• 文件完整，對開發者友善
• 免費方案通常足以支撐初期開發與驗證

對 Cloudflare 架構來說，Resend 還有一個實務上的優勢：它很適合讓 Worker 直接以 API 方式發信，不需要另外維護傳統 SMTP 帳號、SMTP port 與郵件 relay 設定，整體串接與維運負擔會低很多。

第一步先登入 Resend，將自己的網域加入系統，作為後續寄信功能的寄件網域。

先登入 Resend，將自己的網域加入，作為後續網站寄信功能使用的寄件網域。點擊圖片可放大檢視。

剛加入網域時，Status 通常會是未驗證，這是正常現象，代表 Resend 尚未確認你是否擁有該網域的管理權限。

接著可以點選 Auto config，讓 Resend 自動把驗證需要的 DNS 記錄註冊到 Cloudflare。這樣可以避免手動逐筆設定 DNS，降低設定錯誤率，也能加快驗證速度。

如果 Auto config 成功，你回到 Cloudflare 的 DNS 設定畫面時，通常會看到 Resend 自動建立的三筆 record。

Auto config 成功後，可以在 Cloudflare 的 domain DNS 中看到 Resend 自動建立的三筆 record。點擊圖片可放大檢視。

此時回到 Resend 後台，網域的 Status 應該會變成 Verified。只有在驗證完成之後，這個網域才正式具備寄信資格。

最後再申請一組 API Key，讓程式可以實際呼叫 Resend API 發送郵件。建立金鑰時，本文情境可直接選擇 Full access permission。產生出來的 token 請先妥善保存，後續在 Cloudflare 設定 secret 時會用到。

如果是正式環境，建議再補一個習慣：把測試用與正式用的寄件流程分開管理。至少要能區分哪一組 key 用在開發、哪一組 key 用在正式站台，避免測試信與正式信混用同一套憑證。

建立 Resend API Key 時選擇 Full access permission，並把產生的 token 先記錄下來，後續設定環境變數時會使用。點擊圖片可放大檢視。

第 5 步：建立具備 API 能力的 Cloudflare Worker

純前端網站無法安全保存第三方服務金鑰，因此只要你需要寄信、驗證、資料轉送或其他伺服器端邏輯，就應該額外建立一個 Cloudflare Worker 作為後端入口。

你可以把 Worker 理解成部署在 Cloudflare 邊緣網路上的輕量後端服務。前端只需要把資料送給 Worker，由 Worker 再去呼叫 Resend 或其他後端服務，這樣可以有效避免敏感資訊暴露在瀏覽器端。

建立 Worker 時，因為這裡的目標是提供 API 能力，所以可以直接選擇 Select a template，快速建立一個可編輯的 Worker 專案。

建立新的 Cloudflare Worker 時，因為需要具備 API 能力，所以這裡選擇 Select a template。點擊圖片可放大檢視。

接著編寫程式，讓 Worker 代替前端呼叫 Resend API 並發送郵件。這樣的責任切分有兩個好處：

• 前端不需要持有第三方服務金鑰
• 驗證、權限與錯誤處理可以集中在 Worker 端管理

實務上，Worker 也很適合作為 API 邊界層，負責做這些事情：

• 驗證前端送來的欄位格式
• 補上 API 所需的 headers 或授權資訊
• 控制可呼叫的上游服務範圍
• 統一回傳錯誤格式，避免前端直接暴露上游錯誤細節

在程式碼中，先使用變數代替剛剛申請到的 Resend API Key，不要把真正的金鑰直接寫死在原始碼裡。這是基本的安全實務，能避免金鑰進入 Git 倉庫，或在部署後意外外漏。

編寫 Worker 程式時，先用變數代替 Resend API Key，避免把機敏資料直接寫進程式碼。點擊圖片可放大檢視。

Worker 建立完成後，Cloudflare 也會分配一組 workers.dev 子網域。不過正式環境通常不建議直接使用預設網址，而是會替它綁定一個自己的 Custom domain，例如 api.wan-shi-wu.com。

這也正好反映出 Cloudflare 多子網域架構的優勢。只要你已經擁有主網域，就可以在同一個網域底下規劃不同職責的子網域：

• wan-shi-wu.com：主站
• info.wan-shi-wu.com：文件站
• json.wan-shi-wu.com：工具站
• api.wan-shi-wu.com：API 服務

當自訂網域綁定完成之後，再到 Worker 的 Variables and Secrets，把程式中使用的 API Key 變數，設定成你在 Resend 申請到的那組金鑰。這樣 Worker 在執行時就能安全取得憑證，並代替網站向 Resend 發送郵件。

在 Worker 的 Variables and Secrets 中，將程式裡使用的 API Key 變數設成 Resend 申請到的 key，讓 Worker 能安全取得寄信憑證。點擊圖片可放大檢視。

第 6 步：使用 Cloudflare Tunnels 連回私有 API

如果 Worker 需要呼叫外部 API，而這個 API 是架設在自己家中的私有伺服器裡，那麼 Cloudflare Tunnels 會是很適合的解法。

這種情境常見於：

• 某些服務暫時不想搬到公有雲
• 私有 API 需要存取家中內網資源
• 想保留既有伺服器，但又希望被 Cloudflare 上的 Worker 呼叫

這種架構特別適合以下類型的服務：

• 必須放在內網才能運作的 API
• 需要存取本地 NAS、資料庫或其他內部設備的服務
• 不希望直接暴露在公網上的管理後台或轉換服務

使用 Tunnel 的核心價值在於：你不需要暴露家中的公網 IP，也不需要透過路由器設定 port forward。私有 API 仍然可以維持在內網環境中，而 Cloudflare 會透過安全連線替你把流量導進來。

首先，在 Cloudflare 的 Tunnels 介面建立一條新的 tunnel，並取得系統提供的 token。剛建立完成時，Status 通常還不會是 Healthy，因為本地端的 tunnel service 還沒有真正啟動。

先在 Cloudflare 建立一條 Tunnel 並取得 token。剛建立完成時，Status 通常尚未變成 Healthy。點擊圖片可放大檢視。

接著回到自己的私有伺服器。如果 API 是透過 container 執行，例如 Docker Compose 中的一個 API service，那麼很適合讓 tunnel service 也加入同一個 container network。這樣 tunnel service 就能直接透過容器內部的 service name 與 port 連到 API，而不需要把服務直接對外公開。

實作上，可以把 tunnel service 視為另一個常駐容器，啟動時帶入剛剛取得的 token，讓它主動向 Cloudflare 建立連線。當連線成功後，回到 Cloudflare 後台查看，你就會看到 tunnel 的狀態已經變成 Healthy。

在私有伺服器中使用剛取得的 token 啟動 tunnel service，成功連線後，Cloudflare 上對應 tunnel 的 Status 就會變成 Healthy。點擊圖片可放大檢視。

接下來的關鍵問題是：Worker 要如何透過這條 tunnel 呼叫私服中的 API？

做法是點擊 tunnel 名稱，切換到 Routes 頁籤，新增一條 route rule。設定時：

• Destination：填入你網域底下的一個子網域，例如 api.wan-shi-wu.com
• Service：填入私服中 API 對應的 container service 名稱與 port

完成之後，Cloudflare 就會把打到這個子網域的請求，自動轉送到 tunnel 後方的私有 API。如此一來，Worker 只需要呼叫正式網域，就能安全存取家中伺服器裡的服務，而不需要知道內網 IP，也不需要讓主機直接暴露在外網。

這裡有一個很重要的觀念：對 Worker 而言，它看到的是一個正式網域，例如 api.wan-shi-wu.com；至於這個網域背後是直接掛在 Cloudflare 上的服務，還是經由 Tunnel 轉送到家中私服，應該由基礎設施層處理，而不是讓前端或 Worker 去關心內部拓樸。這樣整體系統會更容易維護。

在 Tunnel 的 Routes 頁籤新增 route rule，將子網域導向私服中的 API container service 與 port，讓 Worker 能直接透過該子網域呼叫內部 API。點擊圖片可放大檢視。

第 7 步：設定環境變數與 Secrets

當站台或 Worker 需要使用 API base URL、token、secret 或第三方服務金鑰時，建議一律放在 Cloudflare 的環境變數或 secrets 裡，而不是直接寫進前端程式碼。

常見的設定值例如：

• RESEND_API_KEY
• INVOICE_WORKER_ACCESS
• VITE_API_BASE_URL

使用時請特別區分兩類資料：

• 可公開的前端設定值：例如公開 API Base URL
• 不可公開的機敏資料：例如 API key、token、secret

前者可以作為一般環境變數使用，後者則應該放進 secrets，避免被打包進瀏覽器端或出現在版本控制紀錄中。

如果你的專案同時有 Pages、Workers 與私有 API，建議統一整理一份變數命名規範。例如：

• VITE_ 開頭：只給前端使用的公開設定
• WORKER_ 或服務名稱開頭：只給 Worker 使用的私密設定
• 第三方服務名稱直接命名：例如 RESEND_API_KEY

命名規範越早建立，之後擴充服務時越不容易混亂。

服務呼叫鏈總結

整理到這裡，可以把整體呼叫鏈理解成下面這條路徑：

1. 使用者打開掛在 Cloudflare Pages 上的前端網站
2. 前端表單或操作事件送出請求到 api.your-domain.com
3. 這個網址對應到 Cloudflare Worker
4. Worker 依需求決定：
   • 直接呼叫 Resend 發信
   • 或透過 Tunnel 對接家中私有 API
5. Worker 再把處理結果回傳給前端

這種架構的好處是，公開網站、邊緣 API 與私有服務之間有明確分工，安全性、擴充性與可維護性都會比把所有功能塞在單一站台裡更好。

部署後檢查清單

站台部署完成後，建議至少做一次完整巡檢：

• 首頁是否能正常開啟
• 站內路由重新整理是否正常
• 圖片與靜態資源是否載入成功
• 子站是否都能連到正確網域
• API 請求是否有 CORS、驗證或 header 問題
• 表單與寄信流程是否正常
• 手機版與桌面版畫面是否都可用

如果有接入 Google Ads、Search Console 或其他外部服務，也建議同步確認：

• 網站不是空頁或錯誤頁
• 站台說明與用途清楚
• 隱私權政策與使用條款可正常存取
• 聯絡方式與基本資訊完整

常見問題

Build 成功，但網站打開是空白

優先檢查以下幾項：

• Vite 的 base 設定是否正確
• 靜態資源路徑是否寫死
• Router 是否需要 history fallback
• 部署輸出目錄是否設錯

API 在本機可用，但部署後失敗

常見原因包括：

• API 網址仍指向本機環境
• CORS 白名單未加入正式網域
• Worker secret 尚未設定
• 上游 API 沒有接受必要的 header
• Tunnel route 或自訂網域尚未正確生效

同一個網域下有多個工具站，怎麼管理比較好？

建議把每個工具拆成獨立站台與子網域。這樣做的好處是部署清楚、回滾容易，問題隔離也更乾淨。例如：

• main：主站首頁與導覽
• qrcode：QRCode 工具
• json：JSON 工具
• invoice/front：發票前端
• invoice/api：發票 API
• info：文件與教學站

小結

Cloudflare 很適合拿來管理小型網站與多子網域工具站。它的優勢不只是站台部署快，更重要的是能把網域、DNS、靜態站台、Worker、Tunnel 與安全設定整合到同一套平台上。

如果你先把下列幾件事規劃清楚：

• 網域與子網域命名
• 前端與 API 的職責分工
• 寄信與第三方服務的憑證管理
• 私有服務與 Tunnel 的連線方式

那麼後續的部署、維護與擴充成本通常都會低很多。這也是 Cloudflare 特別適合工具站與中小型專案的原因。