Deploy Next.js lên Vercel: biến môi trường, preview và rollback

Deploy Next.js lên Vercel: kiểm biến môi trường trước khi lên, giữ preview ở chế độ noindex, kiểm nhanh sau khi deploy và quay về bản cũ khi production lỗi.

Deploy Next.js lên Vercel gồm bốn chuyện cần kiểm: biến môi trường đã đặt đủ chưa, preview có bị index nhầm không, trang production có chạy sau khi lên không, và nếu lỗi thì quay về bản cũ thế nào. Bạn đã bao giờ deploy xong mới nhớ thiếu một biến chưa?

Test xanh rồi, nhưng người đọc vẫn chưa thấy gì

Ở tập trước của Xây blog với Next.js và Supabase, mỗi lần đẩy code lên là GitHub Actions chạy kiểm kiểu và test. Nhưng một cổng chất lượng chỉ nói code không phá những gì đã kiểm. Nó không nói trang thật có lên được không, và không giúp gì khi bản mới lên rồi mới thấy lỗi.

Khác với các bài trước, bài này không có tính năng mới. Blog Tech Notes đã chạy trên Vercel, nên mình dùng chính nó làm đối tượng thật: mình viết hai script nhỏ, một cái kiểm biến môi trường trước khi deploy, một cái kiểm nhanh sau khi deploy, rồi chạy chúng trên repo blog và trên trang production. Những gì mình không thử được (cụ thể là rollback) mình sẽ nói rõ.

Biến môi trường: cái quên đặt là cái hỏng sau khi lên

Trên máy bạn, biến môi trường nằm trong .env.local. Trên Vercel, chúng nằm trong phần cài đặt của dự án, được đặt riêng cho từng môi trường (Production, Preview, Development). Hai nơi này không tự đồng bộ: bạn thêm một biến mới vào code, đặt nó trong .env.local, mọi thứ chạy tốt, rồi deploy mà quên đặt nó trên Vercel.

Cách giảm rủi ro mà blog này dùng là file .env.example: mọi biến mà code đọc đều phải có một dòng ở đó, kèm chú thích. Nhưng ai kiểm điều ấy? Mình viết kiem-env.ts. Nó đọc mọi file trong src/ (và next.config.*), tìm các chỗ viết process.env.TEN hoặc env.TEN, rồi so với danh sách biến có dòng TEN= trong .env.example. Hàm phanTich bên dưới nhận danh sách file (tên và nội dung) cùng nội dung .env.example, rồi trả về bốn thứ: biến code dùng mà thiếu trong mẫu, biến có trong mẫu mà code không thấy dùng, các biến NEXT_PUBLIC_, và những chỗ đọc biến bằng tên động.

kiem-env.ts (hàm phanTich; phần duyệt thư mục và in kết quả lược đi vì chỉ là thủ tục)
export type Nguon = { file: string; noiDung: string };
export type KetQua = {
  thieuTrongMau: string[];
  khongThayTrongCode: string[];
  congKhai: string[];
  docDong: { file: string; dong: number }[];
};

/** Biến do nền tảng hoặc công cụ đặt sẵn, không cần khai báo trong .env.example. */
const DO_NEN_TANG = /^(VERCEL(_.*)?|NODE_ENV|CI|NEXT_RUNTIME|NEXT_PHASE|PORT|TZ)$/;

const BIEN = /(?<![\w.])(?:process\.env|env)\.([A-Z][A-Z0-9_]{2,})\b/g;
const DOC_DONG = /process\.env\[/;

export function phanTich(nguon: Nguon[], envExample: string): KetQua {
  const dung = new Set<string>();
  const docDong: KetQua["docDong"] = [];
  for (const { file, noiDung } of nguon) {
    noiDung.split(/\r?\n/).forEach((dong, i) => {
      for (const m of dong.matchAll(BIEN)) dung.add(m[1]!);
      if (DOC_DONG.test(dong)) docDong.push({ file, dong: i + 1 });
    });
  }
  const khaiBao = new Set([...envExample.matchAll(/^([A-Z][A-Z0-9_]+)=/gm)].map((m) => m[1]!));
  const dungCanKhaiBao = [...dung].filter((b) => !DO_NEN_TANG.test(b));
  return {
    thieuTrongMau: dungCanKhaiBao.filter((b) => !khaiBao.has(b)).sort(),
    khongThayTrongCode: [...khaiBao].filter((b) => !dung.has(b)).sort(),
    congKhai: dungCanKhaiBao.filter((b) => b.startsWith("NEXT_PUBLIC_")).sort(),
    docDong,
  };
}

Có hai chi tiết nhỏ đáng giải thích. Các biến như VERCEL_ENV và NODE_ENV do nền tảng đặt sẵn, nên không ai phải khai báo chúng, và DO_NEN_TANG loại chúng ra. Còn dòng bị comment như #BIEN=abc trong .env.example không tính là khai báo, vì regex chỉ nhận dòng bắt đầu bằng tên biến.

Mình chạy nó trên repo blog thật bằng node kiem-env.ts ../../../tech-notes (đường dẫn tới repo blog trên máy mình):

node kiem-env.ts ../../../tech-notes
Đã đọc 179 file. Biến có trong .env.example: 13.
Code dùng nhưng .env.example không khai báo: (không có)
.env.example khai báo nhưng code không thấy dùng: CONTENT_BOT_EMAIL, CONTENT_BOT_PASSWORD, DONATE_ACCOUNT_NAME
Biến NEXT_PUBLIC_ (ghi cứng lúc build): NEXT_PUBLIC_EN_LAUNCHED, NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION, NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, NEXT_PUBLIC_SUPABASE_URL
Chỗ đọc biến bằng tên động: (không có)

Tin tốt là không có biến nào code dùng mà thiếu trong mẫu. Dòng thứ ba cần giải thích, vì nó trông như lỗi mà không phải. CONTENT_BOT_EMAIL và CONTENT_BOT_PASSWORD chỉ được các script nằm ngoài src/ dùng (công cụ đẩy bản nháp), và mình chỉ quét src/. DONATE_ACCOUNT_NAME là biến tùy chọn, chính chú thích trong .env.example ghi là không hiển thị. Vì vậy bộ kiểm không tìm ra lỗi thật trên repo này; mình ghi lại điều đó vì một công cụ kiểm tra mà bạn chưa thấy nó bắt được gì thì chưa đáng tin. Để chứng minh nó bắt được, các test dùng dữ liệu giả: một biến BIEN_QUEN_KHAI_BAO có trong code mà thiếu trong mẫu bị báo, và env.DONATE_BANK (dạng tham số env như trong donate.ts của blog) cũng được nhận ra.

Biến NEXT_PUBLIC_ được ghi cứng lúc build

Dòng thứ tư của output là điều mình thấy đáng chú ý nhất cho chuyện deploy. Theo tài liệu biến môi trường của Next.js, biến có tiền tố NEXT_PUBLIC_ được "inline" vào gói JavaScript lúc chạy next build: Next.js thay mọi process.env.TEN bằng giá trị lúc đó, và sau khi build xong, ứng dụng không còn phản ứng với thay đổi của biến. Hệ quả cho Vercel: nếu bạn đổi NEXT_PUBLIC_SITE_URL trong phần cài đặt, bản đang chạy vẫn dùng giá trị cũ cho tới khi bạn build lại. Cũng theo tài liệu đó, đọc biến bằng tên động (process.env[ten]) không được inline, nên trình duyệt sẽ không thấy giá trị, và đó là lý do kiem-env.ts chỉ ra các chỗ như vậy (blog này không có chỗ nào).

Có một hệ quả mình tận mắt thấy khi build blog trên máy. Mình chạy npm run build ở môi trường không đặt NEXT_PUBLIC_SITE_URL cũng không có biến của Vercel, và Next.js in lặp lại một cảnh báo cho từng trang:

npm run build (trích một dòng cảnh báo, lặp lại nhiều lần)
⚠ metadataBase property in metadata export is not set for resolving social open graph or twitter images, using "http://localhost:3000".

Địa chỉ gốc của site được tính trong src/lib/site.ts theo thứ tự: NEXT_PUBLIC_SITE_URL nếu có, rồi VERCEL_PROJECT_PRODUCTION_URL (Vercel tự đặt), và cuối cùng là http://localhost:3000. Theo cách mình hiểu thì Vercel đặt sẵn biến thứ hai cho dự án, nên trên Vercel code không rơi xuống nhánh cuối (mình chưa kiểm điều này trong phần cài đặt của dự án); kết quả kiểm production ở dưới cũng không thấy localhost. Nhưng trên máy mình, nó rơi xuống đó, và mọi liên kết ảnh chia sẻ sẽ trỏ về localhost. Mình sẽ dùng chính tình huống này ở phần sau để thử script kiểm sau deploy.

Preview: bản xem thử không được lên Google

Mỗi pull request trên Vercel có một địa chỉ preview riêng. Một preview công khai mà cho công cụ tìm kiếm index thì nội dung chưa duyệt có thể xuất hiện trên kết quả tìm kiếm, và còn tranh vị trí với trang thật. Blog giải quyết bằng một hàm duy nhất trong src/lib/site.ts:

src/lib/site.ts (trích từ repo blog Tech Notes)
/** Only Vercel's production deployment may be indexed; previews and local builds stay `noindex`. */
export function isIndexable(): boolean {
  return process.env.VERCEL_ENV === "production";
}

Chỉ khi VERCEL_ENV bằng đúng production thì trang mới được index. Mọi trường hợp khác (preview, development, hay chạy trên máy mình mà không có biến này) đều noindex. robots.ts của blog dùng đúng hàm đó: nếu không indexable thì trả Disallow: / cho mọi người, và các trang cũng có thẻ noindex. Thỏa thuận làm việc của kho còn ghi cùng điều đó dưới dạng luật: "Preview deployments must be noindex; only the production deployment may be indexed". Chọn "mặc định an toàn" như thế này (quên đặt biến thì noindex chứ không phải index) là thiết kế mình thấy đáng học.

Cái giá của mặc định an toàn là mặt trái của nó: nếu production vì lý do nào đó bị build mà VERCEL_ENV không đúng, cả site sẽ âm thầm noindex. Không ai thấy lỗi trên trang, chỉ vài tuần sau thấy lượng truy cập từ tìm kiếm tụt. Đó là lý do mình muốn một phép kiểm tự động sau mỗi lần deploy.

Đừng build preview cho thay đổi chỉ động vào nội dung

Một chi tiết nữa của blog, mà mình thấy đáng kể vì nó tiết kiệm thời gian build: vercel.json có ignoreCommand chạy scripts/vercel-ignore-build.sh. Script này cho Vercel bỏ qua build preview khi commit chỉ đụng tới content, docs, .claude hoặc file Markdown:

scripts/vercel-ignore-build.sh (trích từ repo blog)
[ "${VERCEL_ENV:-}" = "production" ] && exit 1
git rev-parse --verify -q HEAD^ > /dev/null || exit 1

git diff --quiet HEAD^ HEAD -- . ':(exclude)content' ':(exclude)docs' ':(exclude).claude' ':(exclude)*.md'
case $? in
  0) echo "Only content/docs/Markdown changed: skipping this preview build."; exit 0 ;;
  *) exit 1 ;;
esac

Mã thoát 0 nghĩa là bỏ qua build, mã 1 nghĩa là build. Dòng đầu cho biết production luôn build (một commit về tài liệu vẫn có thể là commit duy nhất bạn muốn lên trang thật), và dòng thứ hai cho biết khi không so sánh được với commit trước thì cũng build, chứ không bỏ qua. Cả hai đều chọn phía an toàn: thà build thừa còn hơn bỏ sót.

Kiểm nhanh sau khi deploy

Sau khi một bản lên Vercel, có vài thứ mình muốn biết ngay mà không phải mở trình duyệt: các trang chính còn trả 200 không, có <title> không, và quy tắc index có đúng với loại môi trường không. Script kiem-sau-deploy.ts nhận một địa chỉ gốc và loại môi trường (production hoặc preview), gửi vài yêu cầu GET, và báo từng chỗ. Nó gồm hai phần: các trang / và /bai-viet được kiểm kỹ, /robots.txt được kiểm riêng.

kiem-sau-deploy.ts (hàm kiemSauDeploy)
export type Loai = "production" | "preview";
export type KetQuaKiem = { duong: string; dat: boolean; chiTiet: string };

const TRANG = ["/", "/bai-viet"];

const coNoindex = (html: string, header: string | null): boolean =>
  /<meta[^>]+name=["']robots["'][^>]*content=["'][^"']*noindex/i.test(html) || /noindex/i.test(header ?? "");

/** Các URL tuyệt đối trong thẻ canonical và og:* mà trang trỏ tới. */
const urlTrongThe = (html: string): string[] =>
  [...html.matchAll(/<(?:link[^>]+rel=["']canonical["'][^>]*href|meta[^>]+property=["']og:(?:url|image)["'][^>]*content)=["']([^"']+)["']/gi)].map((m) => m[1]!);

export async function kiemSauDeploy(goc: string, loai: Loai, lay: Lay): Promise<KetQuaKiem[]> {
  const ketQua: KetQuaKiem[] = [];
  const g = goc.replace(/\/+$/, "");

  for (const duong of TRANG) {
    const batDau = Date.now();
    let r;
    try {
      r = await lay(g + duong);
    } catch (loi) {
      ketQua.push({ duong, dat: false, chiTiet: `không kết nối được (${loi instanceof Error ? loi.message : "lỗi"})` });
      continue;
    }
    const html = await r.text();
    const ms = Date.now() - batDau;
    const van: string[] = [];
    if (r.status !== 200) van.push(`mã ${r.status}, cần 200`);
    if (!/<title>[^<]+<\/title>/i.test(html)) van.push("không có <title>");
    const noindex = coNoindex(html, r.headers.get("x-robots-tag"));
    if (loai === "production" && noindex) van.push("production mà có noindex: công cụ tìm kiếm sẽ bỏ qua trang này");
    if (loai === "preview" && !noindex) van.push("preview mà không có noindex: bản nháp có thể bị index");
    if (loai === "production") {
      const localhost = urlTrongThe(html).filter((u) => /localhost|127\.0\.0\.1/.test(u));
      if (localhost.length > 0) van.push(`canonical/og trỏ về localhost (${localhost[0]}); thường do thiếu NEXT_PUBLIC_SITE_URL lúc build`);
    }
    ketQua.push({ duong, dat: van.length === 0, chiTiet: van.length === 0 ? `200 trong ${ms} ms, ${noindex ? "noindex" : "index được"}` : van.join("; ") });
  }
  // ... tiếp theo: kiểm /robots.txt: production không được có "Disallow: /" đứng một mình, preview thì phải có
  return ketQua;
}

Tham số lay là hàm gửi yêu cầu (khi chạy thật là fetch, khi test là một hàm giả), để script test được mà không cần mạng. Mình lược phần kiểm /robots.txt cuối hàm vì nó theo cùng khuôn: một dòng Disallow: / đứng riêng là "chặn toàn bộ", production không được có còn preview thì phải có.

Thử nó trên đúng tình huống mình vừa nhắc: bản build ở máy mình, không có VERCEL_ENV, nên hành xử như một preview. Mình chạy npm run build, rồi npx next start -p 3400 trong repo blog, và dùng script ở hai chế độ. Đầu tiên là chế độ preview:

node kiem-sau-deploy.ts http://localhost:3400 preview
http://localhost:3400 (preview)
  ✓ /  200 trong 93 ms, noindex
  ✓ /bai-viet  200 trong 29 ms, noindex
  ✓ /robots.txt  chặn toàn bộ

Tất cả đạt.

Bản build này đúng là một preview: noindex ở các trang và robots chặn hết. Giờ cùng địa chỉ đó nhưng khai báo là production, tức là mô phỏng chuyện production bị build thiếu cấu hình:

node kiem-sau-deploy.ts http://localhost:3400 production
http://localhost:3400 (production)
  ✗ /  production mà có noindex: công cụ tìm kiếm sẽ bỏ qua trang này; canonical/og trỏ về localhost (http://localhost:3000); thường do thiếu NEXT_PUBLIC_SITE_URL lúc build
  ✗ /bai-viet  production mà có noindex: công cụ tìm kiếm sẽ bỏ qua trang này; canonical/og trỏ về localhost (http://localhost:3000/bai-viet); thường do thiếu NEXT_PUBLIC_SITE_URL lúc build
  ✗ /robots.txt  production mà robots.txt chặn toàn bộ (Disallow: /)

3/3 chỗ không đạt.

Cả ba chỗ đều đỏ, và mỗi thông báo nói đúng điều cần sửa. Đây là chỗ script có giá trị: một production bị cấu hình sai trông hoàn toàn bình thường khi mở bằng mắt, vì giao diện vẫn đẹp. Điều khác biệt chỉ nằm trong thẻ robots, đường dẫn canonical và robots.txt. Cuối cùng mình chạy nó trên trang production thật của blog bằng vài yêu cầu GET:

node kiem-sau-deploy.ts https://www.technotes.asia production
https://www.technotes.asia (production)
  ✓ /  200 trong 4027 ms, index được
  ✓ /bai-viet  200 trong 2780 ms, index được
  ✓ /robots.txt  cho phép

Tất cả đạt.

Production trả 200, có <title>, index được, canonical không trỏ về localhost và robots.txt cho phép. Hai con số thời gian (4,0 và 2,8 giây) là của một yêu cầu duy nhất từ máy mình lúc đó, qua mạng nhà mình, nên mình không rút ra kết luận nào từ chúng; mình chỉ ghi lại vì chúng khiến mình tò mò.

Khi production lỗi: quay về bản cũ

Cả hai script trên đều là cách phát hiện lỗi sớm. Phần còn lại là phản ứng khi phát hiện. Thỏa thuận làm việc của repo blog nói thế này: "If production fails its smoke test, roll back to the prior healthy Vercel deployment and fix it in a new branch". Tức là không sửa vội trên production, mà quay về bản đã chạy tốt trước, rồi sửa trong một nhánh mới.

Theo tài liệu Instant Rollback của Vercel, rollback không build lại: nó trỏ các tên miền production về một deployment cũ có sẵn, nên nhanh. Cũng theo tài liệu đó, những deployment chưa từng được gán vào tên miền production (hầu hết preview) không đủ điều kiện, và với gói Hobby bạn chỉ quay lại được bản ngay trước. Có cả lệnh vercel rollback trên dòng lệnh và nút trong giao diện.

Mình chưa thử rollback, nên mình không có output nào để dán, và mình không muốn bạn tin rằng mình đã làm. Nhưng có hai điều mình suy ra từ những gì đã nói ở trên, và mình nghĩ bạn nên nghĩ tới trước khi cần. Thứ nhất, vì rollback không build lại và biến NEXT_PUBLIC_ được ghi cứng lúc build, bản cũ mang giá trị biến của lúc nó được build, không phải giá trị bạn vừa đổi (đây là suy luận của mình từ hai tài liệu; mình không tìm thấy trang nào nói thẳng điều này, nên hãy thử trước khi dựa vào nó). Thứ hai, rollback chỉ an toàn nếu cơ sở dữ liệu vẫn tương thích với bản cũ. Đó là lý do thỏa thuận của kho yêu cầu migration phải tương thích ngược với phiên bản ứng dụng đang được phát hành: nếu bản mới đã đổi tên một cột và bạn quay lại bản cũ, bản cũ sẽ tìm một cột không còn nữa.

Giữ hai script này bằng test

Mười sáu test của tập này kiểm các điều bài đã nói. Với kiem-env.ts (9 test): biến thiếu trong mẫu bị báo, cách viết env.TEN cũng được tính, VERCEL_ENV, NODE_ENV và CI không cần khai báo, dòng bị comment không tính là khai báo, biến khai báo thừa được liệt kê, biến NEXT_PUBLIC_ được liệt kê riêng, đọc bằng tên động chỉ ra file và dòng, tên chữ thường hay quá ngắn không bị nhầm, và một test ghi lại giới hạn đã biết (một biến nhắc trong chú thích vẫn bị tính là code dùng). Với kiem-sau-deploy.ts (7 test, dùng hàm lay giả): production đúng, preview đúng (noindex qua thẻ meta hoặc qua header), production có noindex hoặc robots chặn hết thì báo, preview thiếu noindex thì báo, canonical trỏ về localhost thì báo, mã 500 hay thiếu <title> thì báo, và không kết nối được thì báo mà các chỗ khác vẫn được kiểm. Bạn chạy bằng node --test kiem-env.test.ts kiem-sau-deploy.test.ts (file test nằm trong repo demo, bài này mình không dán).

node --test kiem-env.test.ts kiem-sau-deploy.test.ts (phần tổng kết)
# tests 16
# pass 16
# fail 0

Những điều bài này chưa làm

Mình nói thẳng các giới hạn. Một, mình không thử rollback và không có địa chỉ preview thật của Vercel. Phần preview mình thử bằng một bản build ở máy mình, vốn hành xử như preview vì không có VERCEL_ENV, nên nó chưa cho thấy preview thật của Vercel có đúng như vậy không. Hai, kiem-env.ts chỉ nhìn thấy process.env.TEN và env.TEN. Cách đọc biến bằng hàm bao như getEnv("TEN") hay bằng cách destructure (const { TEN } = process.env) thì nó mù, và nó không biết biến nào thật sự được đặt trên Vercel, chỉ biết nó được khai báo trong mẫu. Muốn biết điều đó bạn cần so với phần cài đặt trên Vercel, việc mình không làm ở đây. Ba, kiem-sau-deploy.ts chỉ kiểm hai trang, và nó chỉ chứng minh trang trông ổn ở mức trả 200 và có <title>, không chứng minh đăng nhập, đăng ký bản tin hay các luồng khác chạy. Bốn, "đã chạy trên production thật" nghĩa là mình gửi ba yêu cầu GET chỉ-đọc; mình không thử gì có thể thay đổi dữ liệu trên trang thật.

Blog đã trên mạng, nhưng địa chỉ và tốc độ thì sao?

Giờ mỗi thay đổi của blog đi qua một chuỗi: test, build, preview noindex, deploy production, kiểm nhanh, và có đường lùi. Với một blog cá nhân thì đã khá đủ. Nhưng đây mới là vòng đầu tiên. Blog vẫn dùng địa chỉ mặc định, nên bước tiếp theo là một tên miền riêng, và khi tên miền đã gắn thì người đọc từ khắp nơi sẽ thấy trang chậm hay nhanh theo cách mà một yêu cầu từ máy mình không cho thấy. Gắn tên miền riêng và đo hiệu năng cho đúng là việc của các bài viết sau.

Bạn theo dõi cả hành trình ở Xây blog với Next.js và Supabase. Bài Row Level Security trong Supabase giải thích vì sao cơ sở dữ liệu khóa quyền như vậy, điều có liên quan tới việc quay lại bản cũ, và các câu hỏi về deploy nằm trong ngân hàng câu hỏi phỏng vấn.

Nhận bài tiếp theo qua email.

Một email mỗi tuần, chỉ khi có điều đáng đọc. Không spam.