· wrangler / cloudflare / workers

Wrangler 3 — đánh giá CLI mới của Cloudflare Workers

Nâng cấp từ Wrangler 2 ngay. Local dev giờ chạy trong runtime workerd thực, fidelity cao hơn, vòng lặp phản hồi nhanh hơn. Dành một tiếng là xong.

Bởi

2.151 từ · 11 phút đọc

Hãy nâng cấp từ Wrangler 2. Bản viết lại v3 mang đến một thứ thực sự quan trọng: wrangler dev giờ chạy Worker của bạn ngay trên máy trong runtime workerd thực — thay vì mô phỏng trong Node.js. Vòng lặp phản hồi chặt hơn, fidelity cao hơn rõ rệt. Wrangler 4 hiện là phiên bản stable (phát hành tháng 3/2025), nhưng v3 là nơi sự chuyển dịch nền tảng diễn ra — hiểu v3 là điều kiện để dùng cả hai.

Bài viết này dành cho ai

Dành cho các developer đang dùng Wrangler 2 và đang cân nhắc có nên nâng cấp không, cũng như những ai đang đánh giá Workers tooling cho dự án mới. Nếu bạn bắt đầu dự án mới ngay hôm nay, hãy đi thẳng lên v4 — nhưng đọc bài này để hiểu điều gì đã thay đổi và tại sao tooling lại như vậy.

Cách chúng tôi kiểm tra

Wrangler 3.x được đánh giá dựa trên release notes gắn phiên bản, migration guide chính thức v2→v3, và changelog GitHub của workers-sdk. Chúng tôi không chạy benchmark riêng. Các nguồn chính thức của Cloudflare chỉ đưa ra nhận xét định tính về hiệu năng của workerd so với Miniflare 2, và chúng tôi sẽ không thay thế bằng những con số tự bịa.

Bản viết lại thực sự đáng kể

Wrangler 3.0.0 ra mắt ngày 17 tháng 5 năm 2023. Thay đổi nổi bật không phải là đổi tên lệnh hay thêm flag mới — mà là thứ chạy code của bạn trong quá trình phát triển.

Trong Wrangler 2, wrangler dev mặc định gửi Worker của bạn lên mạng Cloudflare. Chế độ local có tồn tại nhưng chạy Miniflare 2: một bản tái triển khai bằng JavaScript của Workers runtime, hàng chục nghìn dòng code cố gắng mô phỏng hành vi nền tảng trong Node.js. Hữu ích đấy. Nhưng vẫn là mô phỏng, mà mô phỏng thì hay lệch.

Wrangler 3 lật ngược mặc định và thay thế bộ mô phỏng. wrangler dev giờ chạy local theo mặc định, bên trong Miniflare 3, vốn nhúng trực tiếp runtime workerd open-source — chính cái C++ engine mà Cloudflare dùng trong production. Bạn không mô phỏng Workers nữa. Bạn đang chạy Workers thật.

Hệ quả thực tế: hành vi CPU, compatibility flags, và mô hình thực thi module giờ khớp với production theo mặc định. Các storage binding (KV, R2, D1) vẫn được mô phỏng local khi chạy offline, nhưng bản thân runtime thì không. Một tập hợp các lỗi kiểu “chạy được local, lỗi trên production” mà Miniflare 2 có thể che giấu sẽ biến mất.

Cài đặt và migration từ v2 lên v3

Cài đặt hoặc nâng cấp:

npm install -g wrangler@3

Kiểm tra phiên bản:

wrangler --version

Migration guide v2→v3 bao gồm toàn bộ danh sách breaking changes. Những thứ dễ vướng nhất:

wrangler publish nay là wrangler deploy. Đổi tên ở v3.0.0 để đồng nhất với dashboard. wrangler publish được giữ lại như alias deprecated trong suốt v3 và bị xóa hẳn ở v4. Nếu CI script của bạn đang hardcode wrangler publish, hãy cập nhật ngay.

--local và --experimental-local đã bị xóa. Trong v2, chế độ local phải chọn thủ công qua các flag này. Trong v3, local là mặc định và các flag đó không còn nữa. Nếu script của bạn truyền --local, hãy xóa flag đó. Nếu chúng phụ thuộc vào hành vi remote-by-default của wrangler dev, hãy thêm --remote tường minh.

CLI độc lập của Miniflare không còn nữa. Nếu bạn từng chạy miniflare trực tiếp, hãy chuyển sang npx wrangler dev. Repository Miniflare trên GitHub đã được archive vào ngày 13 tháng 3 năm 2025 — sẽ không có thêm bản release độc lập nào.

Đó là toàn bộ những điểm dễ vấp. Migration không đau nếu bạn đọc guide trước khi bắt đầu.

Local dev: wrangler dev và --remote

# Chạy Worker trên máy trong workerd — không cần tài khoản Cloudflare cho usage cơ bản
wrangler dev

# Chạy trên mạng live của Cloudflare — dùng thông tin xác thực tài khoản của bạn
wrangler dev --remote

Mô hình local-by-default có hai tác động thực tế.

Bạn có thể phát triển mà không cần tài khoản Cloudflare. Với các Worker không cần authenticated binding, wrangler dev hoàn toàn offline. Iteration nhanh hơn, không rate limit, không có request lẫy sang môi trường production.

Bạn có hành vi runtime thật, không phải polyfill. Compatibility flags, CPU limits, và mô hình thực thi module hoạt động đúng như trên edge của Cloudflare.

Những gì local mode không giải quyết được: khoảng cách tích hợp ở cấp service. D1 local so với remote có thể lộ ra sự chênh lệch schema. Các edge case của Durable Objects và Service bindings gọi đến các Worker khác có thể hoạt động khác biệt khi dùng --remote. Kinh nghiệm chung: phát triển local, kiểm tra với --remote trước khi deploy bất kỳ thứ gì đụng đến trạng thái production.

Deploy: wrangler deploy

wrangler deploy

Không có gì mới phức tạp. Đây là wrangler publish với tên mới. Lệnh này xác thực, bundle Worker bằng esbuild, và deploy lên mạng Cloudflare.

Pages integration có mặt từ v3.45.0. Bạn giờ có thể dùng wrangler config file cho dự án Cloudflare Pages, giúp thống nhất cấu hình giữa Workers và Pages Functions. Lưu ý rằng các key dành riêng cho Workers như main không áp dụng trong ngữ cảnh Pages — hai config schema có phần giao nhau nhưng không giống nhau hoàn toàn. Đọc tài liệu wrangler config cho Pages Functions trước khi chuyển Workers config sang dự án Pages.

Để xem ví dụ thực tế về deploy Workers với D1 và Stripe webhooks, xem Cách deploy Cloudflare Worker với D1 + Stripe Webhooks.

Các sub-command mới

Wrangler 3 đưa D1, R2, Queues và nhiều tính năng khác vào CLI như là công dân hạng nhất.

D1 — serverless SQL

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "<your-database-id>"
wrangler d1 create my-database
wrangler d1 execute my-database --local --command "CREATE TABLE posts (id INTEGER PRIMARY KEY, title TEXT)"
wrangler d1 migrations apply my-database

Để đánh giá chi tiết về mức độ sẵn sàng production của D1, xem Cloudflare D1 năm 2026: đã sẵn sàng cho production chưa?.

R2 — object storage

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"
wrangler r2 bucket create my-bucket
wrangler r2 object put my-bucket/key --file ./local-file.txt

Cảnh báo cho v4: trong Wrangler 4, các lệnh wrangler r2 mặc định chạy ở local mode. Thêm --remote khi nhắm vào production API. Các automation script phụ thuộc vào hành vi v3 sẽ âm thầm thao tác trên local store trong v4 nếu thiếu flag này.

KV — key-value storage

[[kv_namespaces]]
binding = "KV"
id = "<your-namespace-id>"
wrangler kv namespace create MY_KV
wrangler kv key put --namespace-id=<id> foo bar

Thay đổi cú pháp ở v3.60.0: cú pháp dấu hai chấm (wrangler kv:namespace) bị deprecated, nhường chỗ cho cú pháp khoảng trắng (wrangler kv namespace). Dạng dấu hai chấm sẽ bị xóa trong một phiên bản major tương lai. Nếu script của bạn dùng cú pháp cũ, hãy cập nhật — đã có nhiều GitHub issue trong repo workers-sdk báo cáo CI bị gãy vì thay đổi này.

Cảnh báo v4 tương tự như R2: các lệnh data mặc định chạy local trong v4. Thêm --remote khi làm việc với production.

Queues

[[queues.producers]]
binding = "MY_QUEUE"
queue = "my-queue"

[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
wrangler queues create my-queue
wrangler queues list

Định dạng cấu hình

Wrangler 3 hỗ trợ ba định dạng cấu hình: wrangler.toml (mặc định của v2), wrangler.json, và wrangler.jsonc. Hỗ trợ JSON và JSONC có từ v3.91.0. Cloudflare hiện khuyên dùng wrangler.jsonc cho dự án mới.

Mọi config đều cần ba trường bắt buộc dù dùng định dạng nào:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23"
}

Trường main chỉ tùy chọn đối với các Worker chỉ phục vụ static assets. compatibility_date kiểm soát hành vi API nền tảng mà Worker của bạn nhận — hãy đặt về ngày bạn kiểm tra lần cuối, không phải ngày trong tương lai.

Một lưu ý: tài liệu Cloudflare ghi rằng một số tính năng mới hơn chỉ có trong dự án dùng JSON/JSONC config, nhưng không liệt kê cụ thể những tính năng nào. Hãy đối chiếu với configuration reference khi bạn cần một tính năng cụ thể.

Những điểm hạn chế trong trải nghiệm phát triển

Ghi nhận thẳng thắn những gì chưa hoạt động mượt.

Edge case trong module resolution. Wrangler bundle bằng esbuild. Các package có conditional exports theo môi trường có thể gây lỗi bundle local mà không xuất hiện trong dự án Node.js thông thường. Nếu Worker của bạn import một dependency và bundle bị lỗi, hãy kiểm tra conditional exports trước khi kết luận đó là bug của Wrangler.

Local/remote parity chưa hoàn chỉnh. Runtime workerd có độ chính xác cao cho phần thực thi. Nhưng storage thì không: D1 local so với remote có thể lộ ra sự chênh lệch schema, và các edge case của Durable Objects đã từng lọt qua test local rồi mới phát sinh trên production. Với bất kỳ thứ gì có trạng thái, hãy validate với --remote trước khi deploy.

Thay đổi cú pháp KV phá CI một cách im lặng. Các script dùng cú pháp kv:namespace không phải lúc nào cũng báo lỗi rõ ràng ở các phiên bản minor đầu của v3 — rồi cú pháp đó ngừng hoạt động. Nếu script của bạn có wrangler kv:, hãy grep và thay thế trước khi nâng cấp.

Nhầm lẫn Pages config. Các developer chuyển Workers config sang dự án Pages thường xuyên gặp lỗi từ các key không được hỗ trợ. Hai schema trông giống nhau nhưng khác nhau ở các trường quan trọng, và thông báo lỗi không phải lúc nào cũng chỉ rõ key nào gây ra vấn đề.

Wrangler 4 — những gì đã thay đổi

Wrangler 4.0.0 ra mắt ngày 13 tháng 3 năm 2025 và hiện là phiên bản stable. Đây là một major version nhỏ hơn nhiều so với v2→v3. Những thay đổi quan trọng với người dùng v3 hiện tại:

  • Các lệnh wrangler kv và wrangler r2 mặc định chạy local mode trong v4. Mọi automation nhắm vào production phải thêm --remote.
  • getBindingsProxy() bị xóa — dùng getPlatformProxy() thay thế.
  • wrangler publish bị xóa hoàn toàn (alias deprecated từ v3).
  • esbuild nâng từ 0.17 lên 0.24 — kiểm tra sự khác biệt trong hành vi bundle nếu bạn pin phiên bản esbuild.

Xem migration guide v3→v4 để có danh sách đầy đủ trước khi nâng cấp. Phiên bản Node.js tối thiểu cho v4 chưa được xác nhận tại thời điểm viết bài — hãy kiểm tra trực tiếp nếu bạn đang chạy môi trường Node bị ràng buộc phiên bản.

Kết luận

Hãy migrate từ v2 ngay. Vòng lặp dev local-by-default với workerd là cải tiến đáng kể. Các breaking change — đổi tên lệnh, xóa flag — có thật nhưng hoàn toàn mang tính cơ học. Dành một tiếng đọc migration guide là xong.

Bắt đầu dự án mới? Đi thẳng lên v4. Mọi thứ từ v3 đều được giữ lại. Lý do duy nhất để pin v3 là nếu một dependency chưa tương thích với phiên bản esbuild hoặc các API bị xóa trong v4.

Đang chạy automation KV hoặc R2 trong CI? Thêm --remote trước khi nâng lên v4. Đây là thay đổi duy nhất âm thầm làm thay đổi hành vi production mà không có runtime error — các CI script hoạt động tốt với production trong v3 sẽ âm thầm thao tác trên local store trong v4 nếu thiếu flag này.

Bộ công cụ giờ khớp với nền tảng mà nó deploy lên. Đáng đánh đổi bằng một lần migration.

Nếu bạn đang cân nhắc Workers so với các edge platform khác, Cloudflare Workers vs Vercel Functions: So sánh 2026 phân tích các yếu tố quyết định.

Tài liệu tham khảo