Tạo và Deploy Cloudflare Pages Đầu Tiên với Wrangler CLI

Sau khi tạo xong tài khoản Cloudflare, bước tiếp theo thú vị nhất chính là đưa trang web đầu tiên của bạn lên mạng internet toàn cầu. Cloudflare Pages là nền tảng JAMstack và fullstack serverless cho phép bạn lưu trữ website với tốc độ siêu nhanh nhờ mạng lưới CDN hơn 300 thành phố trên thế giới.

Thay vì phải thao tác thủ công kéo thả file trên giao diện Web Dashboard, sử dụng Wrangler CLI (công cụ dòng lệnh chính thức của Cloudflare) mang lại trải nghiệm lập trình mượt mà, tự động hóa và dễ dàng tích hợp vào quy trình CI/CD.

Bài viết này sẽ hướng dẫn bạn từ bước cài đặt công cụ, giải thích bản chất hệ thống cho đến khi trang web đầu tiên hoạt động thực tế.

1. Bản chất hoạt động (ELI5): Chiếc Máy Bay và Trạm Trung Chuyển Toàn Cầu#

Hãy tưởng tượng trang web của bạn như một cuốn truyện tranh:

• Cách truyền thống (Máy chủ đơn lẻ - Single Server): Bạn chỉ in 1 cuốn sách và để ở Hà Nội. Ai ở New York hay Tokyo muốn đọc đều phải bắt chuyến bay dài đến Hà Nội để xem -> Tải trang rất chậm và máy chủ dễ quá tải.
• Cloudflare Pages: Wrangler CLI giống như một chiếc máy bay chở hàng tốc độ cao. Khi bạn gõ wrangler pages deploy, nó sẽ copy cuốn truyện tranh của bạn và nhân bản đến hơn 300 trạm bưu cục (Edge Data Centers) khắp thế giới.
• Người dùng truy cập: Bạn bè ở Tokyo sẽ lấy sách từ trạm Tokyo, bạn bè ở California sẽ lấy sách từ trạm San Jose. Tốc độ tải về chỉ mất vài mili-giây và hoàn toàn miễn phí!

flowchart TD
    A["💻 Máy tính của bạn<br/>(Local Project)"] -->|1. npx wrangler pages deploy| B["⚡ Cloudflare Global Network"]
    B --> C["🌏 Edge Node Tokyo"]
    B --> D["🌏 Edge Node Frankfurt"]
    B --> E["🌏 Edge Node Singapore"]
    B --> F["🌏 Edge Node San Jose"]
    
    User1["👤 Khách ở Nhật"] -->|Tải siêu tốc| C
    User2["👤 Khách ở Đức"] -->|Tải siêu tốc| D
    User3["👤 Khách ở Mỹ"] -->|Tải siêu tốc| F

2. Vấn đề và Giải pháp#

Vấn đề thường gặp khi bắt đầu#

1. Cài đặt sai phiên bản: Cài đặt package cũ @cloudflare/wrangler (Wrangler v1) thay vì phiên bản hiện đại wrangler (v3+), gây ra lỗi xung đột lệnh.
2. Cài đặt Global: Cài đặt Wrangler ở mức hệ thống (npm install -g) dễ gây lệch phiên bản giữa các dự án khác nhau hoặc xung đột quyền hạn máy tính (permission issues).
3. Quy trình deploy thủ công: Tốn thời gian đăng nhập dashboard, kéo file nén zip, khó đồng bộ code.

Giải pháp#

• Cài đặt Wrangler cục bộ (Local Project Dependency) hoặc chạy trực tiếp bằng npx.
• Sử dụng công cụ C3 (create-cloudflare) để khởi tạo tự động hoặc tự tạo thư mục chứa file HTML/JS tĩnh.
• Xác thực tài khoản nhanh chóng chỉ bằng một lệnh npx wrangler login.

3. Yêu cầu hệ thống (System Requirements)#

Trước khi bắt đầu, hãy đảm bảo máy tính của bạn đáp ứng các tiêu chuẩn sau:

• Node.js: Phiên bản 16.17.0 trở lên (Khuyến nghị dùng Node LTS ↗ hoặc công cụ quản lý phiên bản như nvm / volta / fnm / bun).
• Hệ điều hành: macOS 13.5+, Windows 11, hoặc Linux (glibc 2.35+).
• Trình duyệt Web: Đã đăng nhập sẵn tài khoản Cloudflare Dashboard ↗.

[!TIP] Nếu bạn từng cài đặt gói Wrangler cũ trên toàn hệ thống, hãy gỡ bỏ để tránh xung đột:

npm uninstall -g @cloudflare/wrangler

bash

4. Các bước thực hiện chi tiết#

Cách 1: Khởi tạo dự án mới hoàn toàn với C3 (Khuyên Dùng)#

Công cụ Create Cloudflare CLI (C3) là cách nhanh nhất để khởi tạo một ứng dụng Pages hoặc Workers với đầy đủ cấu hình và phiên bản Wrangler mới nhất.

Chạy lệnh sau trên Terminal:

# Sử dụng npm
npm create cloudflare@latest -- my-pages-app

# Hoặc sử dụng pnpm
pnpm create cloudflare@latest my-pages-app

# Hoặc sử dụng Bun
bun create cloudflare@latest my-pages-app

Trình hướng dẫn sẽ hỏi bạn:

1. Loại ứng dụng muốn tạo: Chọn template Website tĩnh, framework ưa thích (Astro, Next.js, Nuxt, SvelteKit, React/Vite, v.v.) hoặc “Hello World”.
2. Ngôn ngữ: TypeScript hoặc JavaScript.
3. Deploy ngay lập tức: Bạn có thể chọn No để chỉnh sửa code trước hoặc Yes để deploy ngay.

Cách 2: Cài đặt Wrangler vào dự án có sẵn và Deploy Website Tĩnh#

Nếu bạn đã có sẵn thư mục code hoặc muốn tạo một trang HTML đơn giản từ đầu:

Bước 1: Chuẩn bị thư mục và file giao diện#

Tạo thư mục dự án và file index.html:

mkdir my-first-page
cd my-first-page

Tạo thư mục public và file public/index.html:

<!DOCTYPE html>
<html lang="vi">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Trang Web Đầu Tiên Trên Cloudflare Pages</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      background: linear-gradient(135deg, #f38020, #faad3f);
      color: #fff;
    }
    .card {
      background: rgba(255, 255, 255, 0.15);
      backdrop-filter: blur(10px);
      padding: 2.5rem;
      border-radius: 16px;
      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
      text-align: center;
      max-width: 500px;
    }
    h1 { margin-top: 0; }
  </style>
</head>
<body>
  <div class="card">
    <h1>🚀 Xin chào từ Cloudflare Pages!</h1>
    <p>Trang web này được deploy trực tiếp qua Wrangler CLI lên mạng lưới 300+ Edge Data Centers.</p>
  </div>
</body>
</html>

Bước 2: Cài đặt Wrangler cục bộ#

Khởi tạo file package.json (nếu chưa có) và cài đặt Wrangler:

npm init -y
npm install --save-dev wrangler

Bước 3: Xác thực tài khoản với Cloudflare#

Chạy lệnh đăng nhập:

npx wrangler login

Trình duyệt web mặc định của bạn sẽ tự động mở trang xác thực của Cloudflare. Nhấp vào nút Allow (Cho phép) để cấp quyền cho Wrangler CLI. Khi hoàn tất, màn hình terminal sẽ hiển thị thông báo thành công:

Successfully logged in.

Bạn có thể kiểm tra lại thông tin tài khoản đang kết nối bằng lệnh:

npx wrangler whoami

5. Deploy trang web lên Cloudflare Pages#

Bây giờ bạn đã sẵn sàng đưa trang web lên môi trường Production.

Lệnh Deploy trực tiếp#

Chạy lệnh wrangler pages deploy kèm tên thư mục chứa file tĩnh cần xuất bản (ở đây là thư mục public hoặc dist / build tùy framework của bạn):

npx wrangler pages deploy public --project-name my-first-page

Khi chạy lần đầu, Wrangler sẽ:

1. Tự động tạo một Pages Project có tên my-first-page trong tài khoản Cloudflare của bạn.
2. Tải toàn bộ file trong thư mục public lên mạng lưới Cloudflare.
3. Cung cấp ngay một tên miền miễn phí dạng https://my-first-page.pages.dev.

[!NOTE] Bạn có thể chạy npx wrangler pages dev public để chạy thử nghiệm môi trường local server trước khi deploy lên internet:

npx wrangler pages dev public --port 8788

bash

6. Tổng hợp các lệnh Wrangler hữu ích (Quick Reference)#

Dưới đây là bảng tổng hợp các lệnh Wrangler thường dùng nhất cho Cloudflare Pages:

7. Tài liệu tham khảo#

• Cloudflare Pages - Get Started Guide ↗
• Wrangler Installation & Update ↗
• Wrangler Commands Reference ↗
• C3 (Create-Cloudflare) CLI Documentation ↗
• Wrangler v1 to v2/v3 Migration Guide ↗