Cloudflare Workers SDK: CLI Wrangler & Bộ Công Cụ
/workers-sdk
Cloudflare Workers SDK là bộ công cụ chính thức để build, test, và deploy Cloudflare Workers, xoay quanh Wrangler CLI. Nó gộp phần khởi tạo dự án, một trình giả lập chạy local, và công cụ deploy vào một monorepo duy nhất theo giấy phép Apache-2.0. Hãy dùng nếu bạn đã build trên nền tảng Cloudflare và muốn một CLI duy nhất cho cả workflow; bỏ qua nếu bạn không có kế hoạch chạy workload trên edge của Cloudflare.
Cloudflare Workers SDK Là Gì?
Cloudflare Workers SDK là nơi trên GitHub chứa Wrangler, công cụ dòng lệnh dùng để build, test, và publish Cloudflare Workers. Monorepo này còn chứa create-cloudflare (C3) để khởi tạo dự án mới, Miniflare để giả lập Workers ở local, và pages-shared, phần code dùng chung giữa Wrangler và Cloudflare Pages. Cloudflare cấp phép toàn bộ toolchain theo Apache-2.0, và bản thân repository được viết chủ yếu bằng TypeScript.
Các Công Cụ Chính Trong Cloudflare Workers SDK
- ✓Wrangler — CLI bạn dùng để build, develop, và publish Workers ngay từ dòng lệnh; tài liệu ở developers.cloudflare.com/workers/wrangler/.
- ✓create-cloudflare (C3) — một CLI riêng tập trung vào việc khởi tạo một app hoàn toàn mới và đưa nó lên Cloudflare, tài liệu ở pages/get-started/c3.
- ✓Miniflare — package cho phép bạn chạy và test Workers ngay trên máy mình, xây trên workerd theo README, trước khi động vào production.
- ✓chrome-devtools-patches — bản fork DevTools riêng của Cloudflare, chỉnh sửa riêng để inspect Workers đang chạy local hoặc đã deploy.
- ✓pages-shared — code nội bộ dùng chung giữa Wrangler và Cloudflare Pages, không phải thứ bạn tự install hay gọi trực tiếp.
- ✓Beta packages — được tạo tự động bởi tool pkg.pr.new sau mỗi commit vào nhánh main, cho phép bạn lấy một fix chưa release trước khi nó thành bản npm chính thức.
Trường Hợp Sử Dụng Cloudflare Workers
- •Khởi tạo một dự án Cloudflare Workers mới chỉ bằng một lệnh (npm create cloudflare@latest) thay vì tự ghép config bằng tay.
- •Test một Worker ngay trên máy với Miniflare, được README mô tả là xây trên workerd, trước khi đưa bất cứ thứ gì lên production.
- •Debug một Worker đang chạy local hoặc đã deploy bằng chrome-devtools-patches, bản fork DevTools riêng của Cloudflare làm cho việc này.
- •Thử một fix chưa release của Wrangler hay Miniflare sớm qua các beta package từ pkg.pr.new, trước khi có bản npm chính thức tiếp theo.
- •Build trên Cloudflare Pages song song với Workers, nơi pages-shared giữ hành vi của Wrangler và Pages đồng bộ với nhau.
Bắt Đầu Với Cloudflare Workers
Quick Start trong README chỉ gồm một lệnh: chạy `npm create cloudflare@latest` (hoặc tương đương với pnpm/yarn: `pnpm create cloudflare@latest` / `yarn create cloudflare@latest`) để khởi tạo một dự án mới. Từ đó, Cloudflare dẫn tới một guide Getting Started riêng trên developers.cloudflare.com cho hướng dẫn đầy đủ. Mỗi package riêng lẻ — wrangler, create-cloudflare, miniflare — cũng có link tài liệu riêng trong package directory của repo. Việc install Wrangler độc lập, ngoài lệnh khởi tạo đó, không được README của repo này mô tả rõ.
Phát Triển Và Kiểm Thử Workers
Việc phát triển và test ở local chạy qua Miniflare, mà README nói là xây trên workerd. Ngoài chi tiết kiến trúc đó, README không đi vào các lệnh Wrangler dùng hàng ngày — khởi động dev server, deploy, xem log — ngay trong bài; nó dẫn sang tài liệu Workers bên ngoài và trang docs riêng của Wrangler, nên cách dùng lệnh cụ thể không được mô tả rõ trong chính README của repo này.
Điểm mạnh
- ✓Một monorepo bao trọn phần khởi tạo dự án (create-cloudflare/C3), test local (Miniflare), và CLI deploy (Wrangler) thay vì ba project được maintain riêng lẻ.
- ✓Miniflare chạy trên workerd, theo README, nên việc test local có một engine thật đứng sau thay vì một mock server chung chung.
- ✓Beta package được publish sau mỗi commit qua pkg.pr.new, nên bạn có thể lấy một fix chưa release mà không cần chờ bản npm chính thức.
- ✓Giấy phép Apache-2.0 cùng quy trình CONTRIBUTING.md công khai, một server Discord, và GitHub Discussions để hỗ trợ.
- ✓chrome-devtools-patches cho bạn một bản DevTools chỉnh riêng để inspect Workers, không chỉ là devtools trình duyệt thông thường trỏ vào một Worker.
Những Điều Cần Cân Nhắc Khi Phát Triển Cloudflare Workers
- △README chỉ ghi rõ một lệnh khởi tạo duy nhất (npm create cloudflare@latest) ngay trong bài; cách dùng Wrangler hàng ngày và chi tiết install được đẩy sang tài liệu bên ngoài của Cloudflare thay vì nằm ở đây.
- △Chạy một Worker ở production cần có tài khoản Cloudflare (có gói free) — bản thân SDK là mã nguồn mở, nhưng nền tảng nó deploy lên không phải thứ bạn tự host được từ repo này.
- △Bản beta qua pkg.pr.new được README nêu rõ là không phù hợp để dùng ổn định — hợp để test một fix chưa release, không hợp để ghim một dự án vào.
- △Không có số phiên bản hay roadmap nào trong các dữ kiện có ở đây, nên không có mốc thời gian phát hành nào được ghi lại.
- △Toolchain được chia thành năm package (wrangler, create-cloudflare, miniflare, chrome-devtools-patches, pages-shared) mỗi cái có link tài liệu riêng, nên không có một trang tham chiếu thống nhất — bạn phải tra qua lại nhiều nơi.
Lựa Chọn Thay Thế Cho Edge Serverless
Câu Hỏi Thường Gặp Về Cloudflare Workers SDK
Cloudflare Workers SDK tồn tại để gom công cụ build, test, và deploy Cloudflare Workers vào một repository, trung tâm nhất là Wrangler, CLI mà Cloudflare xây cho việc đó.
Việc phát triển và test ở local được hỗ trợ — Cloudflare Workers SDK có Miniflare, một trình giả lập mà README mô tả là xây trên workerd, để bạn thử trước khi deploy bất cứ thứ gì.
Monorepo Cloudflare Workers SDK gồm Wrangler (CLI để build và publish Workers), create-cloudflare/C3 (khởi tạo dự án), Miniflare (test local), chrome-devtools-patches (bản fork DevTools để inspect Workers), và pages-shared (code dùng chung giữa Wrangler và Cloudflare Pages).
Cloudflare Workers SDK dùng giấy phép Apache-2.0, như được ghi trên repository GitHub của nó.
Chạy `npm create cloudflare@latest` (hoặc tương đương pnpm/yarn) — đó là lệnh Quick Start mà README của Cloudflare Workers SDK đưa ra để khởi tạo một dự án mới.
README không liệt kê hết mọi ngôn ngữ được hỗ trợ, nhưng các GitHub topic của repo có javascript và wasm, còn bản thân Cloudflare Workers SDK được viết chủ yếu bằng TypeScript — ngoài JavaScript, TypeScript, và WebAssembly, phần hỗ trợ ngôn ngữ khác không được nêu rõ ở đây.
Vấn đề Cloudflare Workers SDK giải quyết
Xây dựng cho edge của Cloudflare gồm nhiều bước riêng biệt — khởi tạo một Worker mới, chạy nó ở local gần giống môi trường thật, rồi deploy — và làm việc đó bằng các tool rời rạc của bên thứ ba chính là khoảng trống mà repo này lấp đầy bằng cách gom Wrangler, create-cloudflare, và Miniflare vào một chỗ. Cloudflare đóng khung cả repository quanh một tool duy nhất, Wrangler, CLI riêng của họ cho Workers, thay vì phát hành một framework serverless đa dụng — nên vấn đề nó thực sự giải quyết hẹp hơn: cho dev Workers một toolchain chính chủ thay vì phải tự ghép các tool cộng đồng quanh nền tảng Cloudflare.
Ai nên dùng — và ai nên bỏ qua
Hãy thử Cloudflare Workers SDK nếu bạn đang build trên Cloudflare Workers và muốn có Wrangler, C3, và Miniflare trong cùng một chỗ thay vì tự đi tìm từng tool riêng — nó hợp lý ngay khi bạn đã gắn với mạng edge của Cloudflare. Bỏ qua nếu bạn không deploy lên Cloudflare: bề mặt CLI của Wrangler được xây quanh nền tảng Cloudflare, còn trình giả lập local của Miniflare mô phỏng workerd, không phải một môi trường serverless chung chung, nên SDK này không mang sang cloud khác được.
Repo liên quan
Vẫn đang phân vân về workers-sdk?
Một cú bấm sẽ gửi câu hỏi kèm trang này cho AI — xem AI nói gì về workers-sdk.