Deploy React, Vite và SPA lên cloud có tên miền riêng, HTTPS
Để deploy một app React (hoặc Vue, Svelte) build bằng Vite lên ZoCloud, bạn đẩy code lên GitHub rồi tạo service từ repo, hoặc chạy zo deploy ngay trong thư mục dự án. ZoCloud tự nhận ra Vite, chạy npm run build, phục vụ thư mục dist bằng nginx và trả index.html cho mọi đường dẫn của SPA, nên React Router không bị 404 khi tải lại trang. App có ngay địa chỉ HTTPS dạng ….zocloud.app; gắn thêm tên miền riêng chỉ cần một bản ghi DNS.
ZoCloud nhận diện site tĩnh và SPA thế nào
Khi build, ZoCloud đọc thư mục dự án và chọn cách chạy. Với các framework front-end, kết quả là một site tĩnh: build một lần, rồi nginx phục vụ file, không có tiến trình Node chạy thường trực.
| Framework | Thư mục output | Trả index.html cho đường dẫn lạ (SPA) |
|---|---|---|
| Vite (React, Vue, Svelte) | dist |
có |
| Create React App | build |
có |
| Angular | dist/<tên>/browser (đọc từ angular.json) |
có |
| Gatsby, Docusaurus, VitePress, Astro tĩnh | public, build, .vitepress/dist, dist |
không |
Next.js với output: 'export' |
out |
không |
HTML thuần (có index.html) |
thư mục gốc | không |
Với site không phải SPA, /gioi-thieu sẽ tìm gioi-thieu, gioi-thieu/ rồi gioi-thieu.html.
ZoCloud chọn lệnh cài theo file lock (npm ci, yarn install --frozen-lockfile hoặc pnpm), chạy script build trong package.json, lấy phiên bản Node từ .nvmrc, .node-version hoặc engines.node. nginx nghe đúng biến PORT, bạn không phải cấu hình cổng.
Kiểm tra trước trên máy:
zo detect
Lệnh in ra framework, lệnh cài, lệnh build và thư mục sẽ phục vụ.
Lưu ý quan trọng: dự án Vite chỉ được coi là site tĩnh khi
package.jsonkhông có scriptstart. Nếu bạn có"start": "vite preview", ZoCloud sẽ chạy nó như một app Node. Xoá script đó để được phục vụ bằng nginx, nhanh và nhẹ hơn.
Chuẩn bị dự án React + Vite
Dự án tạo bằng npm create vite@latest gần như đã sẵn sàng. Kiểm tra ba điểm:
- Có script
buildtrongpackage.json(mặc định làvite buildhoặctsc -b && vite build). - Không ghi cứng
localhostcho địa chỉ API. Dùng biến môi trường của Vite:
const API = import.meta.env.VITE_API_URL;
const res = await fetch(`${API}/products`);
basetrongvite.configđể mặc định/nếu site nằm ở gốc tên miền. Đặt saibaselà nguyên nhân hay gặp của trang trắng vì không tải được file JS.
Biến VITE_ được đưa thẳng vào code lúc build, ai mở trang cũng đọc được: đừng đặt khoá bí mật vào đó.
Các bước deploy
Bước 1: Tạo project
Đăng ký, xác minh e-mail, hoàn tất thiết lập (nạp tiền vào ví hoặc kết nối GitHub). Ở mục Project, bấm Tạo project, đặt tên (ví dụ shop), chọn Vị trí.
Bước 2a: Deploy từ GitHub
- Trên canvas, bấm Thêm → Từ repo GitHub. Hộp Deploy từ Git mở ra, chọn thẻ GitHub (cần Kết nối GitHub trước nếu repo riêng tư).
- Chọn repo, đặt Tên service (ví dụ
web), kiểm tra Nhánh. - Monorepo thì điền Thư mục gốc, ví dụ
apps/web. Để trống Lệnh chạy: site tĩnh không cần. - Bấm Tạo và deploy.
Bật Tự deploy khi push ở tab Cấu hình để mỗi lần push là deploy. Monorepo thì thêm Watch paths (ví dụ apps/web/**).
Bước 2b: Deploy từ thư mục trên máy bằng zo CLI
Không cần Git, phù hợp khi bạn vừa làm xong bằng Cursor hay Claude Code:
curl -fsSL https://app.zocloud.io/install.sh | sh
zo login # dán token tạo ở Tài khoản → Token truy cập
zo deploy -to myorg/shop/web # chạy trong thư mục dự án
zo đóng gói thư mục, bỏ qua node_modules, .git và các mẫu trong .gitignore, không bao giờ gửi file .env* (trừ .env.example). Build chạy trên ZoCloud, bạn không cần upload sẵn thư mục dist. Những lần sau chỉ cần zo deploy.
Muốn để AI agent tự deploy, xem MCP server là gì.
Bước 3: Đặt biến môi trường cho lúc build
Ở tab Biến môi trường, bấm Thêm biến hoặc Sửa dạng .env để dán nhiều dòng:
VITE_API_URL=https://api.example.vn
VITE_SITE_NAME=Shop của tôi
Hoặc zo vars set VITE_API_URL=https://api.example.vn rồi zo deploy. Biến được dùng cả lúc build và lúc chạy, có hiệu lực từ lần deploy sau. Với Vite, đổi biến là phải deploy lại, vì giá trị đã nằm trong file JS đã build.
Nếu backend cũng chạy trên ZoCloud trong cùng environment (ví dụ service api), dùng biến tham chiếu để khỏi chép địa chỉ:
VITE_API_URL=${{api.PUBLIC_URL}}
${{api.PUBLIC_URL}} là địa chỉ https://…zocloud.app của web service api. Xem thêm biến môi trường và file .env.
Bước 4: Theo dõi deploy
Tab Deploy hiện log build. Bản đang chạy vẫn phục vụ khi bản mới lỗi. Quay lại bản trước: Quay lại bản này hoặc zo rollback <số>, không cần build lại.
Ghi đè lệnh build và thư mục output
Khi cần ghi đè, có hai chỗ:
- Tab Cấu hình → Build và chạy: Lệnh cài đặt, Lệnh build (để trống là dùng giá trị tự nhận diện).
- File
zocloud.jsonở gốc repo, được ưu tiên hơn các ô trên portal. Đây cũng là chỗ đổi thư mục output:
{
"build": {
"install": "npm ci",
"build": "npm run build:prod",
"runtime_version": "22",
"output_dir": "dist"
}
}
output_dir là đường dẫn tương đối trong repo; dùng khi bạn đổi build.outDir trong vite.config.
Gắn tên miền riêng
Gói Dùng thử chỉ có địa chỉ ….zocloud.app; tên miền riêng có từ gói Hobby.
- Mở service → tab Tên miền → nhập
www.example.vn→ Thêm. - Nếu portal yêu cầu chứng minh tên miền, thêm bản ghi TXT
_zocloud.example.vnvới giá trị portal đưa. - Tạo bản ghi DNS:
www:CNAMEvề địa chỉ<service>-<project>.zocloud.appmà portal hiện.- Tên gốc
example.vn: bản ghiAvề các IP portal liệt kê (trang Tên miền → Gắn tên miền); xoá các bản ghi A/AAAA cũ.
- ZoCloud kiểm tra DNS mỗi phút; khi đúng, chứng chỉ HTTPS được cấp tự động trong vài phút và tự gia hạn.
CLI tương đương: zo domains add www.example.vn (lệnh in bản ghi CNAME cần tạo). Tên miền mua tại ZoCloud hoặc dùng ZoCloud DNS thì bản ghi được tạo tự động. Chi tiết: trỏ tên miền về hosting và SSL/HTTPS miễn phí.
Lỗi thường gặp với React và site tĩnh
| Hiện tượng | Cách xử lý |
|---|---|
| Tải lại trang con bị 404 | Chạy zo detect: phải ra Vite, Create React App hoặc Angular. Nếu ra "Node.js", xoá script start khỏi package.json |
| Trang trắng, console báo không tải được JS | Kiểm tra base trong vite.config, thường phải là / |
Gọi API lỗi, vẫn trỏ localhost |
Đặt VITE_API_URL rồi deploy lại để build bản mới |
| Build lỗi ở bước chép file | Thư mục build khác dist: đặt output_dir trong zocloud.json |
Log request (mã trạng thái, đường dẫn) xem ở tab Log, bộ lọc Request HTTP, hoặc zo logs -stream http -status 4xx.
Chi phí cho một site React
Site tĩnh dùng rất ít RAM và CPU vì chỉ là nginx phục vụ file. Bạn có thể bắt đầu với gói Dùng thử (0 đ, địa chỉ ….zocloud.app), rồi lên Hobby 119.000 đ/tháng (chưa gồm VAT 10%) khi cần tên miền riêng; trả theo năm bằng 10 tháng. Xem chi phí chạy app vibe coding, hướng dẫn app và zo CLI. App làm bằng Lovable hay Bolt.new thường cũng là React + Vite: xem deploy app Lovable và deploy app Bolt.new. Mỗi Pull Request cũng có thể có bản preview riêng: xem môi trường staging và preview.
Câu hỏi thường gặp
ZoCloud build app React Vite bằng lệnh gì?
ZoCloud chạy lệnh cài theo file lock (npm ci, yarn hoặc pnpm), rồi script build trong package.json, và phục vụ thư mục dist bằng nginx. Bạn đổi được lệnh ở tab Cấu hình hoặc trong zocloud.json.
Vì sao tải lại trang con của React Router bị lỗi 404?
Với app Vite, Create React App và Angular, ZoCloud tự trả index.html cho mọi đường dẫn không có file nên tải lại trang con vẫn chạy. Nếu vẫn 404, kiểm tra zo detect có nhận ra Vite không, thường là do package.json có script start khiến app bị chạy như app Node.
Biến môi trường VITE_ đổi xong có hiệu lực ngay không?
Không. Vite đưa biến VITE_ vào code lúc build, nên sau khi đổi biến bạn cần deploy lại để build bản mới.
Gói Dùng thử có gắn tên miền riêng được không?
Chưa. Gói Dùng thử có sẵn địa chỉ ….zocloud.app với HTTPS; tên miền riêng có từ gói Hobby (3 tên miền) trở lên.