Wrangler 入門:安裝、login、建專案、dev 與 deploy | Cloudflare 完整教學

前面十篇,我們把 Worker 這顆運算核心從裡到外拆了個透徹——但那些程式碼要怎麼真正「跑起來、上線」?靠的就是 Cloudflare 的官方命令列工具:Wrangler。這一篇是 CF-2 部署工具系列的開篇,我們從零帶你走一遍:如何安裝 Wrangler、用 wrangler login 登入帳號、用 npm create cloudflare(C3)建立專案、認識專案結構、用 wrangler dev 本地開發、用 wrangler deploy 一鍵部署到邊緣,再帶你熟悉 tail、whoami、versions 等常用指令,以及 Wrangler v3/v4 的版本差異。讀完這篇,你就能把前面學的一切,變成活生生跑在 Cloudflare 邊緣網路上的服務。

前言

上一篇《Bindings 與 Node.js 相容》,我們把一路用到的 env 徹底拆開——搞懂了 Binding 如何宣告式地把 KV、R2、D1 等資源「注入」進 Worker,也釐清了環境變數、Secrets、Binding 三者的界線。到此,CF-1 運算核心告一段落:你已經知道 Worker「怎麼寫、怎麼連接資源」。

但寫好的程式碼躺在你的硬碟裡,對世界毫無意義。它得經過開發 → 測試 → 部署這條路,才能真正跑在 Cloudflare 全球邊緣、被使用者存取。而串起這整條路的工具,就是本篇的主角——Wrangler。

先給一句話定義:Wrangler 是 Cloudflare Developer Platform 的官方命令列工具(Command-Line Interface,CLI)。它覆蓋 Worker 的完整生命週期——從建立專案、本地開發、測試,到部署上線、觀測日誌、版本管理,一支指令列工具全包。 你在終端機打 wrangler dev 就能本地開發、打 wrangler deploy 就能一鍵上線,不必碰任何複雜的伺服器設定。

打個比方:如果 Worker 是你要交付的「貨物」,那 Wrangler 就是一套完整的「物流系統」——它幫你打包(bundle 你的程式碼)、驗貨(本地模擬執行)、貼標(綁定資源、設定環境)、發貨(部署到全球邊緣),還能追蹤包裹(即時日誌)與召回退貨(版本回滾)。你只要專心把貨(程式碼)做好,運送流程交給 Wrangler。

這種「一支 CLI 打通開發到上線」的體驗,正是 Cloudflare 開發者平台好用的關鍵之一。讀完本篇,你會掌握:

• 安裝與認證——如何把 Wrangler 裝進專案(而非全域)、用 wrangler login 登入、wrangler whoami 確認身份
• 建立專案與專案結構——用 npm create cloudflare(C3)一鍵生成專案,認識 wrangler.jsonc、src/index.ts、package.json 各自的角色
• 本地開發與部署——wrangler dev 在本機用 Miniflare 模擬開發、wrangler deploy 打包上傳到邊緣
• 常用指令與版本——wrangler tail 看即時日誌、wrangler versions 管理版本、以及 Wrangler v3/v4 的差異

核心概念

Wrangler 在開發流程中的角色

先看 Wrangler 站在整個開發流程的哪個位置。一個 Worker 從無到上線,大致走過這幾個階段,而 Wrangler 幾乎每一步都插得上手:

   建立           開發            部署           營運
 ┌───────┐    ┌─────────┐    ┌──────────┐   ┌──────────┐
 │ C3    │───►│ dev     │───►│ deploy   │──►│ tail     │
 │(建專案)│    │(本地模擬)│    │(上傳邊緣)│   │(看日誌)  │
 └───────┘    └─────────┘    └──────────┘   └──────────┘
                  ▲                              │
                  └──────────── 修 bug ◄─────────┘

不需要背下所有指令,先建立一張「地圖」——知道哪個階段用哪支指令,細節之後查表即可。以下是入門階段最常用的指令總覽:

運作原理:本地模擬 vs 遠端邊緣

理解 Wrangler,關鍵要抓住一個分野:「本地」與「遠端」。

• 本地開發(wrangler dev):Wrangler 底層用 Miniflare——一個在你本機模擬 Workers 執行環境的引擎(由 Cloudflare 官方維護)。它讓你不必每次改一行程式就上傳雲端,而是在 localhost 直接跑、直接看結果。KV、R2、D1 等資源也在本機用 .wrangler/state/ 目錄模擬,速度快、免費、不碰線上。
• 遠端部署(wrangler deploy):當你確定要上線,Wrangler 會把你的程式碼**打包(bundle)**成 Cloudflare 能執行的格式,連同 wrangler.jsonc 裡宣告的所有綁定,上傳到 Cloudflare 的全球邊緣網路。從此,真實使用者的請求就會被路由到你的 Worker。

一句話總結兩者關係:dev 是「在本機演練」,deploy 是「正式登台」。 日常開發你會待在 dev 裡反覆迭代,直到滿意才 deploy。

關鍵術語

進入實作前,先釐清幾個會反覆出現的名詞:

• C3(create-cloudflare):官方的專案鷹架工具,透過 npm create cloudflare@latest 呼叫。它會互動式問你要用哪種範本、要不要 TypeScript、要不要立刻部署,然後生成一個開箱即用的專案。
• Miniflare:Wrangler 本地開發背後的模擬引擎,讓 wrangler dev 能在你本機重現接近真實的 Workers 環境。
• wrangler.jsonc:Worker 的設定檔(JSON with Comments,可寫註解)。Worker 名稱、入口檔、compatibility_date、所有綁定都寫在這裡。本篇先認識它的存在與必填欄位,完整設定會在下一篇專章詳談。
• compatibility_date:相容性日期,決定你的 Worker 執行在哪個版本的 Workers runtime 上。這是 wrangler.jsonc 的必填欄位,C3 建立專案時會自動填好。

實作範例

概念齊了,我們動手走一遍從安裝到上線的完整流程。以下指令在 macOS、Linux、Windows(建議用 PowerShell 或 WSL)皆適用,唯一前提是先裝好 Node.js(建議 18 以上)。

步驟一:認識兩種安裝方式

Wrangler 是一個 npm 套件,有兩種裝法。先講結論:優先選「專案本地安裝」。

# 方式 A(推薦):安裝到專案的 devDependencies
npm install -D wrangler@latest

# 方式 B(不推薦):全域安裝
npm install -g wrangler@latest

為什麼推薦本地安裝?因為 Wrangler 更新頻繁,把版本鎖進專案的 package.json,才能確保你、隊友、CI/CD 三方用的是同一版,避免「在我電腦上好好的」這種災難。本地安裝後,用 npx 前綴呼叫即可:

# npx 會自動找到專案本地那一版 Wrangler 來執行
npx wrangler --version
# 應輸出 4.x.x(或你安裝的版本)

好消息是:如果你用下一步的 C3 建立專案,Wrangler 會自動被裝進專案裡,你根本不用手動執行上面的安裝指令。 這一步的重點只是讓你理解「Wrangler 是專案的相依套件」這件事。

步驟二:登入 Cloudflare 帳號

要部署,得先讓 Wrangler 知道你是誰。執行:

npx wrangler login

這會自動開啟瀏覽器,引導你用 Cloudflare 帳號完成 OAuth 授權。授權成功後,token 會存在本地,之後所有指令都自動帶著這個身份——不用每次都登入。

隨時可以確認目前登入狀態:

npx wrangler whoami
# 會顯示你登入的 email、Account 名稱與 Account ID

需要切換帳號或登出時:

npx wrangler logout

提醒:wrangler login 是給「人」在本機用的互動式登入。在沒有瀏覽器的 CI/CD 環境(如 GitHub Actions),要改用 API Token——把 CLOUDFLARE_API_TOKEN 與 CLOUDFLARE_ACCOUNT_ID 設成環境變數即可。這部分我們在後續的 CI/CD 專章會詳談。

步驟三:用 C3 建立專案

最推薦的建立方式是官方的 C3(create-cloudflare)。一行指令,互動式引導:

npm create cloudflare@latest my-worker

執行後,C3 會問你幾個問題,例如:

• 要建立哪種應用?(選 Hello World Worker 最單純)
• 要用 TypeScript 還是 JavaScript?(建議 TypeScript)
• 要不要用 git 初始化?
• 要不要立刻部署?(初次可先選「否」,等下手動 deploy)

如果你想跳過互動、直接建立一個最單純的 Hello World Worker,可以帶參數:

# 直接建立 hello-world 範本、不用互動選單
npm create cloudflare@latest my-worker -- --type=hello-world

C3 會自動幫你:安裝 Wrangler、生成範本程式碼、建好 wrangler.jsonc、產生 TypeScript 型別、安裝相依套件。完成後進入專案目錄:

cd my-worker

步驟四:認識專案結構

打開專案,你會看到大致如下的結構(以 TypeScript 的 Hello World 為例):

my-worker/
├── src/
│   └── index.ts              # Worker 入口:你的程式碼寫在這
├── wrangler.jsonc            # Wrangler 設定檔:名稱、入口、綁定都在這
├── package.json              # npm 相依(含 wrangler)與 scripts
├── tsconfig.json             # TypeScript 設定
├── worker-configuration.d.ts # wrangler types 自動生成的型別
└── .gitignore                # 已幫你排除 .wrangler/ 等

三個最關鍵的檔案:

• src/index.ts——你的 Worker 本體。C3 生成的預設內容大概長這樣:

// src/index.ts —— C3 生成的 Hello World Worker
export default {
  async fetch(request, env, ctx): Promise<Response> {
    return new Response("Hello World!");
  },
} satisfies ExportedHandler<Env>;

• wrangler.jsonc——Worker 的設定檔,C3 會幫你填好必填欄位:

// wrangler.jsonc —— C3 生成的最小設定
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",              // Worker 名稱(kebab-case)
  "main": "src/index.ts",           // 入口檔案
  "compatibility_date": "2026-08-01" // 相容性日期(必填)
}

• package.json——注意 wrangler 就列在 devDependencies 裡(這正是「本地安裝」),而且 C3 通常會幫你加好方便的 scripts:

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "cf-typegen": "wrangler types"
  },
  "devDependencies": {
    "wrangler": "^4.0.0"
  }
}

有了 scripts,你甚至可以直接 npm run dev / npm run deploy,更省事。

步驟五:本地開發 wrangler dev

在專案目錄下啟動本地開發伺服器:

npx wrangler dev

Wrangler 會用 Miniflare 起一個本地服務,終端機會顯示類似:

⛅️ wrangler 4.x.x
-------------------
Ready on http://localhost:8787

打開瀏覽器或用 curl 存取,就能看到你的 Worker 回應:

curl http://localhost:8787
# 輸出:Hello World!

現在試著改一下 src/index.ts,把回應改成別的字串、存檔——wrangler dev 會自動重載,重新整理瀏覽器就看到新結果,不用重啟。幾個常用旗標:

# 自訂埠號(預設 8787)
npx wrangler dev --port 3000

# 切到遠端模式:連到真正的 Cloudflare preview 執行
# (適合測試本地無法模擬的資源,例如 Workers AI)
npx wrangler dev --remote

# 測試 Cron 排程:啟動後可 curl /__scheduled 手動觸發
npx wrangler dev --test-scheduled

開發時要按 Ctrl+C 才能停止伺服器。

步驟六:部署上線 wrangler deploy

開發滿意了,一行指令部署到 Cloudflare 全球邊緣:

npx wrangler deploy

Wrangler 會打包程式碼、上傳,終端機會顯示部署結果與網址:

Total Upload: 1.23 KiB / gzip: 0.61 KiB
Deployed my-worker triggers:
  https://my-worker.<你的帳號>.workers.dev

點開那個 workers.dev 網址,你的 Worker 就正式跑在邊緣、對全世界可存取了。部署前若想先驗證設定而不真的上線,可以先乾跑:

# Dry Run:驗證設定與打包,但不實際部署
npx wrangler deploy --dry-run

步驟七:看即時日誌 wrangler tail

上線後,想看生產環境的即時請求與 console.log,用 tail:

# 串流當前 Worker 的即時日誌
npx wrangler tail

# 只看發生錯誤的請求
npx wrangler tail --status error

# 搜尋 console.log 內容中含特定字串的請求
npx wrangler tail --search "TypeError"

執行後保持連線,每有一個請求打到你的 Worker,日誌就即時滾出來——線上除錯時極其好用。

補充:C3 vs wrangler init

你可能在舊教學看過 wrangler init。它也能初始化專案,但官方現已推薦用 C3(npm create cloudflare),因為 C3 提供更豐富的範本(Hono、Next.js 等框架)與更完整的引導。新專案一律優先用 C3。

常見錯誤與最佳實踐

坑一:全域安裝 Wrangler,導致多專案版本打架。

有人圖方便 npm install -g wrangler,結果電腦上所有專案共用同一版。Wrangler 更新頻繁,一旦全域版本升級,某個舊專案可能就跟著壞掉;更糟的是你、隊友、CI 各用各的版本,同一份程式碼行為不一致,除錯到懷疑人生。正確做法:一律專案本地安裝(npm install -D wrangler@latest,或直接用 C3 建立專案),把版本鎖進 package.json 與 lockfile,呼叫時用 npx wrangler。這樣才能保證三方環境一致。

坑二:在 CI/CD 裡想用 wrangler login,卡死。

wrangler login 會開瀏覽器等你點授權——但 GitHub Actions、GitLab CI 這類環境沒有瀏覽器、沒有人,指令會卡住或直接失敗。正確做法:CI/CD 一律改用 API Token 的非互動式認證。在 Cloudflare Dashboard 建立一個只授予「Edit Cloudflare Workers」權限的 Token(最小權限原則),把它與 Account ID 存進 CI 的 Secrets、設成環境變數 CLOUDFLARE_API_TOKEN 與 CLOUDFLARE_ACCOUNT_ID,Wrangler 就會自動用它認證。切記:Token 絕不能寫死在程式碼或 commit 進版控,並要定期輪換。

坑三:忘了設或亂設 compatibility_date。

compatibility_date 決定你的 Worker 跑在哪個版本的 runtime 上,是 wrangler.jsonc 的必填欄位。有人手動建專案時漏填,部署直接報錯;也有人把它設成很舊的日期,結果用不到新功能、或行為和預期不符。正確做法:用 C3 建立專案會自動填好一個近期日期;若手動維護,把它設在近 30 天內、需要新功能時再往前推。改動它前,務必了解該日期對應哪些 runtime 行為變化(官方文件有對照表)。

坑四:command not found: wrangler。

直接打 wrangler dev 卻報找不到指令——多半是你只做了本地安裝、卻沒加 npx。本地安裝的 Wrangler 不在全域 PATH 裡,必須用 npx wrangler <指令> 呼叫,或透過 package.json 的 scripts(npm run dev)執行。正確做法:養成 npx wrangler ... 的習慣,或善用 C3 幫你設好的 npm run dev / npm run deploy。

坑五:dev 與 deploy 分不清,以為 dev 就上線了。

有人在 wrangler dev 跑得好好的,以為服務已經上線,結果外面根本連不到。記住那條分野:wrangler dev 只在你本機 localhost 跑,程式碼完全沒上線、外界存取不到;要讓真實使用者能存取,必須執行 wrangler deploy 把 Worker 上傳到邊緣。開發用 dev、上線用 deploy,一個對內、一個對外。

最佳實踐小結: 記四條——Wrangler 一律專案本地安裝、用 npx 呼叫;本機開發用 login、CI/CD 用 API Token;新專案一律用 C3 建立、compatibility_date 保持近期;dev 是本地演練、deploy 才是正式上線。守住這四條,你的部署流程就穩了。

小結

上一篇《Bindings 與 Node.js 相容》,我們拆解了 env 與 Bindings,為 CF-1 運算核心收尾——你已經知道 Worker 怎麼寫、怎麼連接資源。這一篇,我們正式踏進 CF-2 部署工具的世界,認識了把程式碼變成線上服務的官方 CLI——Wrangler:

• Wrangler 的角色——覆蓋 Worker 完整生命週期的官方 CLI,從建專案、本地開發、部署,到看日誌、管版本,一支工具全包;它站在開發流程「建立 → 開發 → 部署 → 營運」的每一環。
• 安裝與認證——優先專案本地安裝(npm install -D wrangler@latest)並用 npx 呼叫,避免版本打架;本機用 wrangler login 開瀏覽器登入、wrangler whoami 確認身份,CI/CD 則改用 API Token。
• 建立專案與結構——用 C3(npm create cloudflare@latest)一鍵生成專案;三個關鍵檔案是 src/index.ts(Worker 本體)、wrangler.jsonc(設定檔)、package.json(相依與 scripts)。
• 開發與部署——wrangler dev 用 Miniflare 在本機 localhost 模擬開發(改存自動重載),wrangler deploy 打包上傳到全球邊緣;dev 對內演練、deploy 對外上線。
• 常用指令與版本——wrangler tail 看即時日誌、wrangler versions list 列版本;Wrangler v4 是當前主流,設定檔以 wrangler.jsonc(取代舊版 TOML)為主。

我們已經能用 wrangler deploy 把 Worker 送上邊緣了。但你一定注意到了:那個決定 Worker 名稱、入口、綁定與相容性的 wrangler.jsonc,我們只匆匆帶過。下一篇《wrangler.jsonc 設定》,就要把這份設定檔徹底拆開——name、main、compatibility_date 三大必填欄位、vars、各種綁定鍵、env 多環境設定,一次講清楚,讓你能隨心所欲地設定自己的 Worker。

想先一睹官方 Wrangler 的完整指令清單,可以隨時參考 Cloudflare 官方 Wrangler 指令文件。部署工具的第一課已就緒,我們下一篇《wrangler.jsonc 設定》見。