Khi làm việc trên dự án có nhiều môi trường – như staging và production – cho backend API và frontend deployment, bạn muốn đảm bảo cấu hình và lệnh đúng cho từng nhánh trong repository.
Điều này trở nên khó khăn khi nhiều dev cùng làm việc trên codebase, thay đổi nhánh khác nhau, hoặc quản lý nhiều cấu hình riêng cho từng nhánh.
Giống như mọi pull request hoặc thay đổi push lên nhánh, bạn cần review từng dòng code bị thay đổi, thêm, xóa trước khi quyết định merge. File cấu hình trong codebase không ngoại lệ, dễ dẫn đến lỗi vì một thay đổi nhỏ có thể ảnh hưởng toàn bộ thiết lập Continuous Integration.
Khi thay đổi được push lên nhánh staging hoặc production và build được kích hoạt, bạn muốn đảm bảo tài nguyên đúng cho nhánh đó được duy trì. Trong một số trường hợp, bạn cần định nghĩa quy tắc redirect khác nhau cho từng client, lệnh build tùy chỉnh, hoặc cài đặt khác cho từng nhánh.
Trong bài này, tôi sẽ hướng dẫn cách quản lý cấu hình riêng cho từng nhánh (bao gồm redirect cho nhiều nhánh) tự động, dùng script Bash đơn giản. Cũng sẽ chỉ cách merge an toàn các quy tắc theo ngữ cảnh cho nhánh staging và production trên Netlify.
Nội dung bao gồm:
Cấu trúc dự án và tình huống
Redirect/Rewrite là gì?
Netlify xử lý Redirect như thế nào?
Cú pháp file
_redirectsCú pháp file cấu hình
netlify.toml
Vấn đề: Quản lý nhiều file
netlify.tomlcho nhánh khác nhauCách viết script tự động tạo file cấu hình
File Netlify.toml mẫu
Bước 1: Tạo thư mục script và thêm file script
Bước 2: Sửa package.json để thêm lệnh script
Cách deploy client lên Netlify
Triển khai lần đầu dự án lên Netlify
Triển khai tiếp theo / Cách thiết lập Branch Deployments
Bước 1: Thiết lập Environment Variables trên Netlify cho từng ngữ cảnh – production, staging, v.v.
Bước 2: Kích hoạt deploy mới
Kiểm tra Deployments
Kết luận
Cấu trúc dự án và tình huống
Xét tình huống: bạn có 2 server riêng cho dự án: một phục vụ môi trường staging (deploy trên Render), một cho production (deploy trên Google Cloud Run).
Bạn cũng có 2 client deployment riêng trên Netlify, mỗi cái với API_BASE_URL riêng, được phục vụ bởi server tương ứng như hình minh họa:
Hình dưới là repository sample-project với thư mục api và client. Tổng quan cấu trúc trong các nhánh. Mỗi thư mục có package.json riêng, được xem như thành phần độc lập, có thể deploy lên 2 dịch vụ riêng.
Trong frontend deployment cho từng client, tất cả request đến endpoint bắt đầu bằng /api/v1/ được route đến server. Các route khác giữ nguyên trong frontend để điều hướng trang. Do đó bạn cần viết quy tắc đúng để client biết cách xử lý request. Đây gọi là redirect rules hoặc rewrites.
Redirect/Rewrite là gì?
Redirect (hay rewrite) là quy tắc cho phép URL tự động chuyển đến vị trí mới bất kỳ trên internet (nguồn: WPengine). Còn gọi là URL forwarding, dùng được cho toàn bộ website, một phần website, hoặc toàn bộ web app.
Trong web app, redirect thường dùng để quyết định cách xử lý request. Nền tảng hosting như Netlify, Vercel cung cấp tùy chọn này để dev xác định cách web app xử lý request.
Netlify xử lý Redirect như thế nào?
Netlify có 2 cách chỉ định redirect rules: dùng cú pháp file _redirects hoặc file cấu hình netlify.toml. Cả hai đạt cùng mục tiêu, nhưng netlify.toml cho nhiều tùy chọn và khả năng hơn.
Dùng cú pháp file _redirects
Nếu chọn cách này, chỉ cần tạo file _redirects trong thư mục public của client app, viết quy tắc redirect bên trong. Rất đơn giản. Ví dụ quy tắc redirect trong file:

Quy tắc trên nghĩa là:
Gửi tất cả request khớp
/api/v1đến API URL chỉ định, trả về status 200. Dấu sao (*) sau/api/v1/như trong/api/v1/*chỉ việc nối phần mở rộng URL gốc vào API URL. Ví dụ route/api/v1/userstrên frontend sẽ redirect đếnhttps://your-api-base-url.com/api/v1/users.:splattrong API URL chỉ placeholder.Phục vụ các route mặc định khác qua thư mục index.html. Cần thiết để tránh trang bị lỗi khi điều hướng trang khác và quay lại bằng nút "back".
Dùng cú pháp file cấu hình netlify.toml
File netlify.toml cho nhiều linh hoạt hơn khi chỉ định redirect rules, bao gồm match route gốc, đích đến, status code, header rules, signatures, giới hạn quốc gia, roles, v.v.
File netlify.toml mẫu từ tài liệu Netlify:

Lưu ý nhanh: Dùng file redirects để redirect request đến API hoàn toàn ổn. Nhưng coi như rủi ro bảo mật nếu để API URL dạng plain text trong file redirects khi API_BASE_URL nên giữ bí mật. Vì file trong public folder là công khai – ai cũng truy cập được.
Nếu URL đích là public, dùng _redirects thoải mái. Nhưng nếu muốn URL riêng tư, dùng netlify.toml kết hợp environment variables an toàn hơn.
Vấn đề: Quản lý nhiều netlify.toml cho nhánh khác nhau
Khi dùng netlify.toml định nghĩa lệnh build và cài đặt môi trường, và bạn push thay đổi, mở pull request, bạn phải thủ công bỏ qua hoặc sửa từng netlify.toml trên mỗi nhánh. Điều này trở nên căng thẳng và dễ lỗi.
Ngoài ra, muốn tránh hardcode API URL trong _redirects hoặc netlify.toml trong codebase vì lý do bảo mật. Sẽ dùng environment variables từ Netlify UI cho production và staging.
Để tránh các vấn đề trên, sẽ dùng script nhỏ trong codebase để động tạo netlify.toml đúng cho từng nhánh. Cách này loại bỏ xung đột và không cần can thiệp thủ công khi chuyển nhánh hoặc xử lý pull request.
Cách viết script tự động tạo file cấu hình
File Netlify.toml mẫu
Dưới đây ảnh chụp file netlify.toml mẫu mà chúng ta muốn đạt được cho mỗi build. Tất cả request khớp api/v1/ trong codebase sẽ route đến API.
Bạn có thể cấu trúc endpoint API khác, ví dụ /api/your-endpoint – chỉ cần điều chỉnh script cho phù hợp. Dự án mẫu dùng api/v1/your-endpoint.
Bước 1: Tạo thư mục script và thêm file script
Trong thư mục client, tạo thư mục scripts/ và file script configure-netlify.sh. Bắt buộc làm cho mỗi nhánh trong repo. Nội dung giống nhau.
Mở configure-netlify.sh và dán nội dung sau:
#!/bin/bash # Đảm bảo API_BASE_URL được thiết lập if [ -z "$API_BASE_URL" ]; then echo "Lỗi: Biến môi trường API_BASE_URL chưa được thiết lập." exit 1 # Dừng script để dừng deployment fi echo "Đang dùng API endpoint: $API_BASE_URL" # Định nghĩa cấu hình Netlify mong muốn NETLIFY_CONFIG=" [build] command = \"npm install && npm run build\" base = \"client\" publish = \"dist\" [[redirects]] from = \"/api/v1/*\" to = \"$API_BASE_URL/:splat\" status = 200 force = true [[redirects]] from = \"/*\" to = \"/index.html\" status = 200 " # Tạo hoặc cập nhật file netlify.toml if [ ! -f "netlify.toml" ]; then echo "Đang tạo file netlify.toml..." else echo "Đang cập nhật file netlify.toml hiện có..." fi echo "$NETLIFY_CONFIG" > netlify.toml # Xác nhận cấu hình thành công echo "File netlify.toml đã được cấu hình thành công!"
Script thực hiện:
Kiểm tra biến môi trường đảm bảo
API_BASE_URLđã set. Nếu chưa, thoát build và gây fail. Đảm bảo không deploy thành công nhưng với URL sai trong production.Tạo nội dung
netlify.tomlnhư mẫu. Nếu endpoint API dùng cấu trúc khácapi/v1/your-endpoint, điều chỉnh script cho phù hợp.Kiểm tra xem đã có
netlify.tomlchưa. Nếu chưa, tạo mới và ghi nội dung. Nếu có, cập nhật nội dung đúng trong lúc build, dùngAPI_BASE_URLtừ environment variables.
Bước 2: Sửa package.json thêm lệnh script
Để tích hợp script vào quy trình build, thêm lệnh script vào package.json gọi script trước khi build thực sự.
Thêm lệnh configure-netlify như sau: "configure-netlify": "bash scripts/configure-netlify.sh" trong scripts của package.json.
Cập nhật lệnh build chạy script trước: "build": "npm run configure-netlify && vite build".
Đừng quên lưu thay đổi và push lên remote repository.
Cách Deploy Client lên Netlify
Khi deploy client lên Netlify, có 3 tùy chọn:
Import dự án có sẵn (từ git repo như GitHub, GitLab),
Import từ template,
Deploy thủ công static site qua Netlify drop (drag and drop).
Để cấu hình trong repo hoạt động đúng khi build, bạn bắt buộc dùng tùy chọn import từ dự án có sẵn (GitHub). Kéo thả không hoạt động. Nếu buộc phải dùng, hãy chọn cú pháp _redirects để định nghĩa redirect.
Triển khai lần đầu dự án lên Netlify
Lần đầu deploy, chỉ được deploy 1 nhánh ban đầu. Chỉ thêm nhánh khác ở các lần deploy sau.
Các bước deploy:
Đăng nhập Netlify > netlify.com
Click "Add new site" > "Import an existing project" > "Deploy with GitHub"
Click "Configure Netlify on GitHub" > Tìm repository > Chọn
Nhập tên site duy nhất
Cấu hình deploy settings. Chọn nhánh deploy. Lần đầu sẽ deploy nhánh
main(production branch).Branch: main/master
Build command:
npm run buildPublish directory:
dist(Chọn thư mục chứa file tĩnh. Dự án mẫu export radist. Một số tool export rabuild)
Nhập environment variables cho dự án. Đừng quên
API_BASE_URLtừ server. Đây là yêu cầu bắt buộc theo script Bash.Click "Deploy site"

Dự án sẽ deploy đúng, bạn thấy file netlify.toml do script tạo bằng cách xem chi tiết deployment ở dưới trang deploy thành công.
Có thể tải file về máy để xem cấu hình tạo ra. Nên khớp với file mẫu netlify.toml ở trên. Cũng test bằng link site generated.

Triển khai tiếp theo / Cách thiết lập Branch Deployments
Bước 1: Thiết lập Environment Variables trên Netlify cho từng ngữ cảnh – production, staging, v.v.
Sau khi deploy thành công, có thể thiết lập deploy cho nhánh staging. Để chỉnh cấu hình:
Vào danh sách sites
Chọn site đã deploy thành công
Click "site configuration" menu trái
Chọn "environment variables" > click "Add a variable"

Có tùy chọn thêm variable riêng lẻ hoặc import cả file .env. Chọn tùy ý. Hình dưới chọn "Import from a .env file".

Vì production site (từ nhánh main với env production) đã deploy, bạn cần:
Bỏ check production branch (để không ghi đè main branch ban đầu. Cẩn thận không lẫn env variables giữa nhánh)
Chọn "branch deploys"
Copy nội dung file .env vào ô nhập
Đừng quên thêm
API_BASE_URLcho môi trường staging
Lưu ý: chọn branch deploys nghĩa là env variables import ở đây ảnh hưởng tất cả branch deploys, trừ production branch. Có thể tùy chỉnh context bằng custom branch nhưng đó là cách khác, có thể cần tùy chỉnh thêm netlify.toml hoặc script Bash.

Nếu import từng env variable riêng lẻ, có tùy chọn tương tự. Đảm bảo chọn đúng context cho từng nhánh.
KHÔNG DÙNG GIÁ TRỊ GIỐNG NHAU CHO TẤT CẢ CONTEXTS. Như hình dưới, chọn "different value for each deploy context" cho phép định nghĩa giá trị cho từng context. Ở đây định nghĩa cho branch deploys. Variable production ban đầu đã tồn tại.
Sau khi import xong, kiểm tra bằng cách chọn dropdown bên phải mỗi variable xem giá trị.

Bước 2: Kích hoạt deploy mới
Khi đã import xong env variables cho các context – production và staging – vào "deploys" panel trái. Click "Trigger deploy", clear cache, bắt đầu deploy mới.

Kiểm tra Deployments
Xác nhận script hoạt động đúng bằng cách chọn deployment bất kỳ, chọn dropdown "building" trong "Deploy log". Sẽ thấy lệnh chạy, output và API URL cho deployment đó, theo context.

Kết luận
Làm theo các bước trong hướng dẫn, dùng script và lệnh cập nhật trên mỗi nhánh trong repo, khi push thay đổi Netlify sẽ tự động tạo hoặc cập nhật file netlify.toml trên mỗi nhánh. Điều này đảm bảo cấu hình đúng và environment variables cho từng môi trường được dùng tại build time.
Script giống nhau trên tất cả nhánh. Điều này giúp bạn tập trung vào thay đổi code khác mà script lo phần cấu hình an toàn, dễ dàng.
Hãy push thay đổi lên bất kỳ nhánh nào để thấy hoạt động.
Thoải mái kết nối với tôi trên Twitter (@francisihej) hoặc LinkedIn!
Học lập trình miễn phí. Chương trình mã nguồn mở của freeCodeCamp đã giúp hơn 40.000 người tìm việc lập trình viên. Bắt đầu ngay