Cloudflare生產工作流之:Wrangler開發指南

第一部分：基礎概念與初始設置

在Cloudflare開發生態系統中，wrangler佔有核心地位。今天我們來學習和了解一下wrangler這款常用工具。涉及:wrangler的安裝、配置和驗證wrangler，可以用來操作Workers（計算）、D1（數據庫）、 R2（對象存儲）和KV等。

1.1 Cloudflare 開發者生態系統簡介

Cloudflare的開發者平台圍繞其無服務器（Serverless）計算服務構建，其核心支柱包括：Workers（計算）、D1（數據庫）和 R2（對象存儲）。這個平台旨在讓開發者能夠將應用程序部署到 Cloudflare 的全球網絡上，使其更接近終端用戶，從而實現極致的性能和低延遲。

在這一生態系統中，wrangler 扮演着不可或缺的角色。它是一個功能強大的命令行界面（CLI）工具，是連接開發者本地環境與 Cloudflare 全球網絡的橋樑。無論是構建新的 Worker、管理數據庫模式，還是上傳靜態資源，wrangler 都是用於編排、測試和部署這些服務的首選工具。對於任何希望在 Cloudflare 平台上構建應用的團隊來說，精通 wrangler 是邁向高效開發和運維的第一步。

1.2 Wrangler 安裝與環境配置

在開始使用 wrangler 之前，必須確保開發環境滿足特定的系統要求。這包括受支持的Node.js 版本（Current、Active、Maintenance）和操作系統（macOS 13.5+、Windows 11、支持 glib 2.35+ 的 Linux 發行版）。

官方強烈推薦將 wrangler 作為每個項目的本地開發依賴項（devDependency）進行安裝，而不是全局安裝。這種做法具有顯著優勢：

• 版本一致性：通過將 wrangler 版本鎖定在項目的 package.json 文件中，可以確保團隊中的每位成員以及 CI/CD 環境都使用完全相同的工具版本，從而消除因版本不匹配導致的“在我機器上可以運行”的典型問題。

• 項目隔離：避免了不同項目可能依賴不同 wrangler 版本而產生的全局衝突。

• 可復現的構建：為創建可靠且可復現的構建環境奠定了基礎。

安裝命令如下：

npm i -D wrangler@latest

當wrangler 在項目本地安裝後，所有命令都需要通過 npx 來執行，例如 npx wrangler dev。這種從全局安裝向本地安裝的轉變，反映了JavaScript 生態系統中開發最佳實踐的成熟，即傾向於項目依賴的封裝和隔離，這對於專業的 DevOps 流程至關重要。

備選安裝方法（供參考）

儘管不作為首選，但在某些特定場景下，其他安裝方法也可能適用：

• 全局 NPM 安裝：npm i -g @cloudflare/wrangler。

• Homebrew (macOS)：brew install cloudflare-wrangler。

• Cargo (Rust)：cargo install wrangler，這種方法尤其適用於基於 ARM 的系統。

驗證安裝

無論採用何種安裝方式，都可以通過以下命令來檢查 wrangler 的版本，以確認安裝成功：

npx wrangler --version

1.3 身份驗證：將 Wrangler 連接到您的 Cloudflare 賬户

wrangler提供了多種身份驗證機制，以適應從本地交互式開發到全自動 CI/CD 流水的不同需求。

wrangler login 是現代化、安全且官方推薦的身份驗證方法。它通過啓動一個 OAuth 2.0 流程，自動打開瀏覽器，引導用戶登錄其 Cloudflare 賬户並授予 wrangler 必要的權限。授權成功後，一個具備適當權限的 API 令牌會自動存儲在本地配置文件中，供後續命令使用。這個流程對開發者極為友好，且無需手動處理敏感的 API 密鑰。

驗證身份：

wrangler whoami

執行 wrangler login 後，運行 wrangler whoami 是一個關鍵的驗證步驟。該命令會顯示當前已驗證的用戶信息和賬户詳情，為開發者提供了即時反饋，確認本地 CLI 已成功連接到正確的 Cloudflare 賬户。

較舊的方法：wrangler config (API 密鑰)

wrangler config 是一種較舊的驗證方法，它要求用戶手動提供 Cloudflare 賬户郵箱和全局 API 密鑰（Global API Key）。由於全局 API 密鑰擁有賬户範圍內的廣泛權限，這種方法存在較大的安全風險，因此官方已不推薦使用。瞭解此方法主要是為了兼容舊有項目或文檔。

高級身份驗證：CI/CD 與無頭環境

在自動化環境（如 CI/CD 流水線）中，無法進行交互式登錄。此時，必須採用非交互式的驗證方式。標準做法是使用環境變量 CLOUDFLARE_API_TOKEN。開發者可以在 Cloudflare 儀表盤中創建一個具有精確範圍權限（例如，僅“編輯 Workers”）的 API 令牌，然後將此令牌作為機密信息存儲在 CI/CD 系統的環境變量中。

wrangler會自動檢測並使用此環境變量進行驗證。

這種上下文相關的身份驗證策略是專業開發的核心：

● 交互式開發會話：應使用 wrangler login，以獲得最佳的安全性和用戶體驗。

● 自動化系統：必須使用通過 CLOUDFLARE_API_TOKEN 環境變量提供的範圍受限的 API 令牌，以確保安全性和非交互性。

對於更復雜的遠程開發環境（如在遠程服務器或容器中開發），社區也探索出了通過 curl 手動完成 OAuth 回調的方法，以應對 wrangler login 無法直接打開本地瀏覽器的挑戰。

第二部分：核心開發與部署工作流

本部分將引導用戶完成一個標準 Cloudflare Worker 項目從創建、本地開發到最終部署的全過程。

2.1 項目初始化與結構

使用 create-cloudflare-cli (C3) 創建項目

開始一個新項目的最主要方式是使用 create-cloudflare-cli (C3)，這是一個官方提供的腳手架工具，能夠快速生成項目模板。執行以下命令即可啓動：

npm create cloudflare@latest

在交互式設置過程中，C3 會引導用戶完成一系列選擇，例如選擇 "Hello World"模板、開發語言（JavaScript 或 TypeScript）以及是否初始化 Git 倉庫等。

C3 會生成一個結構清晰的項目目錄，其中包含以下關鍵文件：

wrangler.toml/wrangler.jsonc：項目的核心配置文件，定義了Worker 的名稱、入口點、兼容性日期、路由和資源綁定等。
src/index.ts(或.js)：Worker 的代碼入口文件。
package.json：管理項目依賴，包括本地安裝的wrangler。
.git/：如果選擇，則會初始化為Git倉庫。

備選方案：wrangler init

對於已有的項目目錄，如果只想在其中添加 wrangler 的配置文件，可以使用 wrangler init 命令。它只會在當前目錄創建一個 wrangler.toml 文件，而不會生成完整的項目腳手架。

2.2 使用 wrangler dev 進行本地開發

wrangler dev 是本地開發流程中的核心命令。它會啓動一個本地開發服務器，該服務器能夠高度仿真 Cloudflare Workers 的真實運行環境，從而實現快速的開發和測試。

該服務器最關鍵的特性之一是實時重載（Live Reloading）。當開發者修改並保存代碼文件時，本地服務器會自動重新加載 Worker，立即反映出代碼變更，極大地縮短了開發反饋週期。

默認情況下，本地 Worker 可以通過 http://localhost:8787 訪問。此外，wrangler dev 會自動為 D1、R2、KV 等資源創建本地的、基於文件的模擬實現。這意味着開發者可以在完全離線的環境中進行全棧開發，而無需在早期階段連接到遠程的生產或預演資源。

2.3 使用 wrangler deploy 進行部署

當本地開發和測試完成後，wrangler deploy 命令用於將 Worker 發佈到 Cloudflare 的全球網絡上 。

默認情況下，該命令會根據 wrangler.toml 文件中的頂級配置進行部署。然而，在專業的開發流程中，通常會定義多個環境（例如，staging 和 production）。通過使用 --env 標誌，可以將 Worker 部署到指定的環境，例如 npx wrangler deploy --env production。

部署成功後，wrangler 會在終端輸出 Worker 的公共訪問 URL，通常是 *.workers.dev 子域或開發者配置的自定義路由。

表 1：核心命令快速參考

為了便於快速查閲，下表總結了本部分介紹的最核心的 wrangler 命令。

第三部分：精通 wrangler.toml 配置

wrangler.toml（或 wrangler.jsonc）是所有 wrangler 管理的項目的聲明式“事實來源”（source of truth）。深入理解其配置選項是掌握 Cloudflare 開發的關鍵。

3.1 配置文件結構解析

wrangler同時支持 TOML (wrangler.toml) 和 JSONC (wrangler.jsonc) 格式，其中 JSONC 是新項目的推薦格式。

一些最重要的頂級配置項包括：

name：Worker腳本的名稱。
main：指向Worker入口文件的路徑，例如./src/index.ts
compatibility_date：這是一個至關重要的設置，它將Worker的運行時環境鎖定到特定版本的Workers API。這確保了向後兼容性，防止因平台API更新而導致現有代碼中斷。
account_id：發佈Worker 所需的Cloudflare 賬户ID

路由配置

可以通過 workers_dev = true 啓用默認的 *.workers.dev 子域，或者通過 route 字段將 Worker 綁定到自定義域上的特定路由模式。

3.2 資源綁定：平台的連接組織

綁定（Bindings） 是 Cloudflare 平台的一個核心概念。它是一種機制，用於授權 Worker 與其他 Cloudflare 資源（如 D1 數據庫、R2 存儲桶、KV 命名空間等）進行交互。至關重要的是，綁定不僅僅是包含密鑰的環境變量；它們是被注入到 Worker 的 env 參數中的實時對象，為訪問這些資源提供了一個直接、經過身份驗證的 API。

D1 數據庫綁定

要將一個 D1 數據庫綁定到 Worker，需要在 wrangler.toml 中進行如下配置，指定一個 binding 名稱（在代碼中使用的變量名）、database_name 和 database_id。

[[d1_databases]]
binding = "DB"# 在代碼中通過 env.DB 訪問
database_name = "my-production-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

R2存儲桶綁定

綁定 R2 存儲桶的語法類似，需要一個 binding 名稱和 bucket_name。

[[r2_buckets]]
binding = "MY_BUCKET"# 在代碼中通過 env.MY_BUCKET 訪問
bucket_name = "my-asset-bucket"

3.3管理環境與密鑰

環境 ([env.*])

wrangler.toml支持通過 [env.staging]、[env.production] 等節來為不同的部署環境定義不同的配置。

配置繼承規則

環境會繼承頂級的配置項，但也可以覆蓋它們。這裏存在一個極其重要的設計決策：綁定（bindings）和變量（vars）是不可繼承的。這意味着每個環境都必須顯式地定義其所需的綁定和變量。這種設計並非不便，而是一項關鍵的安全特性。它強制要求開發者為每個環境進行明確的配置，從而從根本上防止了因配置疏忽（例如，開發環境意外回退使用生產數據庫）而導致的數據污染或泄露。這種設計強制實現了環境之間的嚴格隔離，是 DevOps 最佳實踐的體現。

密鑰管理

對於 API 密鑰等敏感數據，絕不應以明文形式存儲在 wrangler.toml 中。正確的做法是使用 wrangler secret 命令集（put, delete, list）。通過 npx wrangler secret put <KEY_NAME> 添加的密鑰會被加密存儲，並在運行時作為環境變量注入到 Worker 中，從而實現了安全的密鑰管理。

第四部分：Cloudflare 服務的實用工作流（用戶核心請求）

本部分提供了用戶在遷移過程中最需要的具體、可直接使用的命令序列，涵蓋 D1 數據庫、R2 存儲和Workers 的管理。

4.1 管理 Cloudflare D1 數據庫

wrangler提供了一套完整的 d1 子命令，用於管理 D1 數據庫的整個生命週期。

數據庫生命週期管理

● 創建新數據庫：npx wrangler d1 create <DATABASE_NAME>

● 列出已有數據庫：npx wrangler d1 list

● 獲取數據庫信息：npx wrangler d1 info <DATABASE_NAME>

● 刪除數據庫：npx wrangler d1 delete <DATABASE_NAME>

模式遷移：DevOps 工作流

在生產環境中，直接執行 SQL 語句來修改數據庫模式是不可靠且難以追蹤的。正確的方式是使用遷移（Migrations），它允許以版本控制的方式管理數據庫模式的演變。

● 第一步：創建遷移文件
執行 

 npx wrangler d1 migrations create <DATABASE_NAME> <MIGRATION_MESSAGE>

例如 

npx wrangler d1 migrations create my-db create_users_table

這會在項目的 migrations/ 目錄下生成一個新的 .sql 文件，開發者可以在其中編寫 DDL 語句。

● 第二步：列出待處理的遷移
使用 npx wrangler d1 migrations list <DATABASE_NAME> 可以查看哪些遷移尚未被應用。

● 第三步：應用遷移
這是最關鍵的一步，wrangler 允許分別對本地和遠程數據庫應用遷移：

應用於本地開發數據庫：

npx wrangler d1 migrations apply <DATABASE_NAME> --local

應用於遠程生產數據庫：

npx wrangler d1 migrations apply <DATABASE_NAME> --remote

直接執行 SQL 查詢（用於調試）

在開發或調試過程中，有時需要直接對數據庫執行查詢：

從文件執行：

npx wrangler d1 execute <DATABASE_NAME> --file=./query.sql●

 直接執行命令：

npx wrangler d1 execute <DATABASE_NAME> --command="SELECT * FROM users;"

在執行這些命令時，必須清晰地使用--local 和 --remote 標誌來指定操作目標，以防對生產數據造成意外更改。

4.2 管理 Cloudflare R2 對象存儲

wrangler的 r2 命令集用於管理存儲桶和其中的對象。

存儲桶操作

● 創建新存儲桶：

npx wrangler r2 bucket create <BUCKET_NAME>

● 列出已有存儲桶：

npx wrangler r2 bucket list

● 刪除存儲桶：

npx wrangler r2 bucket delete <BUCKET_NAME>

單文件上傳

上傳單個文件是 r2 命令的基本功能。使用 put 子命令即可完成：

npx wrangler r2 object put <BUCKET_NAME>/<OBJECT_KEY> --file=./path/to/local/file.jpg

可以通過 --content-type 等標誌來設置對象的元數據。

R2目錄和批量上傳

一個常見的需求是上傳整個目錄的靜態資源。wrangler 目前沒有提供一個原生的遞歸上傳命令。為了解決這個問題，可以編寫一個簡單的 Shell 腳本來遍歷本地目錄並逐個上傳文件。

另一種解決方案:cloudflare 兼容亞馬遜 S3 API的使用方式，可以用工具批量上傳、下載、刪除。

下面的小工具，支持cloudflare 的S3 API，可以把文件批量上傳到R2。

https://github.com/808cn163/S3FileManager

用戶界面如下:

4.3 更新與管理已部署的 Workers

更新代碼與配置

更新一個已部署的 Worker 非常簡單。只需在本地修改代碼或 wrangler.toml 配置文件，然後重新執行 npx wrangler deploy 即可。wrangler 會自動處理新版本的上傳和部署過程。

查看實時日誌

對於已部署的 Worker，npx wrangler tail 是一個極其有用的實時調試工具。它能夠將 Worker 的日誌（包括 console.log 的輸出和運行時異常）實時流式傳輸到開發者的終端，從而能夠快速診斷生產環境中的問題。

表 2：D1 和 R2 命令標誌（本地 vs. 遠程）

下表清晰地對比了在 D1 和 R2 命令中 --local和 --remote 標誌的作用，這對於防止在生產環境中發生誤操作至關重要。

第五部分：綜合與戰略建議

本部分將報告從技術手冊提升為戰略指南，幫助用戶將 wrangler 融入更廣泛的專業實踐中。

5.1 將 Wrangler 集成到 CI/CD流水線

身份驗證

在CI/CD 環境中，應始終使用範圍受限的 CLOUDFLARE_API_TOKEN，並將其作為環境變量（例如，GitHub Actions 的 secrets）注入到流水線中。

示例工作流 (GitHub Actions)

下面是一個典型的 .github/workflows/deploy.yml 文件示例，展示了在推送到主分支時自動部署 Worker 的流程：

name:DeployWorker
on:
  push:
    branches:
      -main
  jobs:
    deploy:
      runs-on:ubuntu-latest    
        name:Deploy    
        steps:    
           -uses:actions/checkout@v3      
           -name:UseNode.js        
              uses:actions/setup-node@v3       
                 with:        
                   node-version:'18'    
                 -name:Installdependencies      
                   run:npmci   
                 -name:Runtests      
                   run:npmtest   
                 -name:DeploytoCloudflare      
                   run:npxwranglerdeploy--envproduction       
                    env:CLOUDFLARE_API_TOKEN:${{secrets.CLOUDFLARE_API_TOKEN}}

5.2 常見問題排查

• 身份驗證錯誤：“You are not logged in.” -> 運行 npx wrangler login 或檢查 CLOUDFLARE_API_TOKEN 環境變量是否設置正確。

• 配置錯誤：“Could not find wrangler.toml” -> 確保在項目根目錄下運行命令。

• 綁定錯誤：“env.DB is undefined” -> 檢查 wrangler.toml 文件，確保在當前使用的環境中正確配置了該綁定。

• 部署錯誤 (523)：首次部署到 *.workers.dev 子域後，DNS 可能需要一分鐘左右的時間來傳播，短暫的 523 錯誤是正常現象。

5.3 核心要點總結

wrangler CLI 是 Cloudflare 開發者平台的核心工具。掌握其工作流是成功遷移和構建應用的關鍵。核心原則包括：

1. 本地優先開發：使用 wrangler dev 進行快速、高保真的本地開發和測試。

2. 配置即代碼：將 wrangler.toml 作為項目的唯一事實來源，進行版本控制和管理。

3. 安全自動化：通過範圍受限的 API 令牌和環境變量實現安全的 CI/CD 流程。

4. 清晰的工作流：為 D1、R2 等不同資源採用專用的、清晰的管理命令和流程。

建議：對於準備遷移的團隊，建議採取循序漸進的策略。

選擇一個規模較小、非關鍵的業務模塊進行遷移，以熟悉整個開發、配置和部署流程。從項目一開始，就應該在 wrangler.toml 中建立獨立的 staging 和 production 環境，這是確保未來可擴展性和穩定性的基石。

wrangler 不僅僅是一個工具，它代表了一種在 Cloudflare 平台上進行現代化、高效和可擴展的無服務器開發的實踐基礎。通過深入掌握它，您的團隊將能夠充分利用 Cloudflare 全球網絡的強大能力。