Biến môi trường Node.js: hết cảnh “máy em chạy mà”

Biến môi trường Node.js: dùng process.env, file .env và node --env-file, gom cấu hình vào một chỗ có kiểm tra bằng Zod để máy chủ báo lỗi rõ ràng lúc khởi động.

Biến môi trường là những cặp tên và giá trị mà hệ điều hành đưa cho chương trình lúc khởi động, để cùng một đoạn code chạy với cấu hình khác nhau trên mỗi máy. Trong Node.js bạn đọc chúng qua process.env. Điều khó là đọc cho an toàn. Cùng mình xem nhé!

Vì sao máy bạn chạy được còn máy anh Khoa thì không?

Ở bài trước, nhánh của bạn đã nằm trên main. Rồi anh Khoa, người review code, kéo main về, chạy thử và nhắn lại rằng máy anh báo lỗi trong khi máy bạn chạy ngon. (Quán Mộc và anh Khoa là nhân vật minh họa của series này.) Câu "máy em chạy mà" quen đến mức thành chuyện cười của cả nghề, và nguyên nhân thường không nằm trong code. Nó nằm ở những thứ code đọc từ bên ngoài: cổng nào, file ở đâu, khóa nào.

Hãy nhìn máy chủ đơn hàng của Mộc lúc này. Website của quán sắp gửi đơn qua POST, nên máy chủ có thêm một thứ mới: một khóa chung mà website phải gửi kèm để chứng minh đơn đến từ nó. Khóa đó không được nằm trong code, vì code thì ai trong team cũng đọc, và sẽ lên GitHub. Nó phải đến từ bên ngoài. Cùng với cổng, đường dẫn file đơn hàng và vài tùy chọn bật tắt, mình có sáu thứ cần cấu hình. Biến môi trường là cách quen thuộc nhất để đưa chúng vào.

Mình sẽ làm theo đúng thứ tự mình hay làm: viết bản đơn giản nhất, cho nó hỏng ở những chỗ thật sự hỏng, rồi sửa. Bạn cần Node.js 22.18 trở lên, vì từ bản đó Node chạy thẳng file .ts, và cờ --env-file mình dùng ở dưới có từ Node 20.6. Tạo thư mục don-hang-moc với cấu trúc này:

Cấu trúc thư mục
don-hang-moc/
  package.json
  .gitignore
  .env.example
  data/orders.json
  src/server-ngay-tho.ts
  src/config.ts
  src/server.ts
  src/config.test.ts
package.json
{
  "name": "don-hang-moc-12",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node --env-file=.env src/server.ts",
    "test": "node --test src/config.test.ts"
  },
  "dependencies": {
    "zod": "4.6.7"
  }
}

Chạy npm install để cài Zod. File dữ liệu là hai đơn mẫu, đủ để máy chủ có gì đó trả về:

data/orders.json
[
  { "id": 1041, "khach": "NGUYỄN AN", "tong": 83000 },
  { "id": 1042, "khach": "TRẦN BÌNH", "tong": 32000 }
]

Biến môi trường là gì, và process.env trả về cái gì?

Mỗi tiến trình trên máy có một bảng tên và giá trị riêng, gọi là môi trường. Khi bạn mở terminal rồi chạy node app.js, Node nhận một bản sao của bảng đó và đưa nó cho bạn qua đối tượng process.env. Bạn đặt một biến ngay trước lệnh chạy như sau trên macOS, Linux và Git Bash:

Đặt biến cho một lần chạy (macOS, Linux, Git Bash)
PORT=8080 node src/server.ts

Trên PowerShell bạn viết khác: $env:PORT = "8080" rồi mới chạy node. Có một điều bạn nên nhớ từ đầu, vì nó là nguồn của gần mọi lỗi dưới đây. Giá trị trong process.env luôn luôn là chuỗi. Nếu bạn đặt PORT=8080 thì process.env.PORT là chuỗi "8080", không phải số 8080. Và nếu bạn không đặt, nó là undefined. Hai chỗ đó, kiểu chuỗi và khả năng thiếu, là toàn bộ chuyện.

Bản đầu tiên: đọc process.env ở khắp nơi

Cách mà ai cũng làm trước tiên là đọc process.env ngay chỗ cần dùng. Máy chủ dưới đây có hai đường. GET /don-hang trả danh sách đơn. POST /don-hang nhận đơn mới, nhưng chỉ khi website gửi header Authorization: Bearer <khóa>, và khóa đó so với biến ORDER_API_KEY:

src/server-ngay-tho.ts
// Máy chủ đơn hàng bản đầu tiên: đọc thẳng process.env ở khắp nơi. Chạy: node src/server-ngay-tho.ts
import { createServer } from "node:http";
import { readFileSync } from "node:fs";

const port = Number(process.env.PORT ?? 3000);
const chiTiet = Boolean(process.env.LOG_REQUESTS);
const donHang = JSON.parse(readFileSync(process.env.ORDERS_FILE ?? "data/orders.json", "utf8"));

const server = createServer((request, response) => {
  if (chiTiet) console.log(`${request.method} ${request.url}`);
  if (request.url === "/don-hang" && request.method === "GET") {
    return void response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(donHang));
  }
  if (request.url === "/don-hang" && request.method === "POST") {
    // Website gửi kèm "Authorization: Bearer <khóa>". So với khóa lấy từ biến môi trường.
    if (request.headers.authorization !== "Bearer " + process.env.ORDER_API_KEY) {
      return void response.writeHead(401).end("Sai khóa");
    }
    return void response.writeHead(201).end("Đã nhận đơn");
  }
  response.writeHead(404).end();
});

server.listen(port, () => console.log(`Máy chủ nghe ở cổng ${(server.address() as { port: number }).port}`));

Code này đọc rất xuôi và nó chạy được trên máy bạn. Giờ thử năm tình huống mà máy của một người khác có thể rơi vào. Mình chạy từng cái và dán nguyên kết quả.

Tình huống đầu tiên: ai đó đặt PORT=abc, chẳng hạn vì gõ nhầm. Number("abc") ra NaN, và máy chủ nổ khi gọi listen:

PORT=abc node src/server-ngay-tho.ts
RangeError [ERR_SOCKET_BAD_PORT]: options.port should be >= 0 and < 65536. Received type number (NaN).
  code: 'ERR_SOCKET_BAD_PORT'

Lỗi này ít ra còn nổ ngay. Nhưng thông báo nói về options.port của Node chứ không nói "biến PORT của bạn sai", và người mới đọc sẽ mất một lúc để nối hai thứ lại. Tình huống thứ hai tệ hơn. Trong file .env của nhiều dự án có dòng PORT= để trống, và biến được đặt với giá trị rỗng:

PORT= node src/server-ngay-tho.ts
Máy chủ nghe ở cổng 58868

Máy chủ không nổ. Nó nghe ở một cổng lạ, vì ?? chỉ thay thế undefined hoặc null, không thay thế chuỗi rỗng, và Number("") là 0. Cổng 0 nghĩa là "hệ điều hành chọn một cổng trống". Website của quán gọi cổng 3000 thì không thấy gì, và không có dòng lỗi nào để lần theo.

Tình huống thứ ba là biến bật tắt. Người dùng muốn tắt log chi tiết nên đặt LOG_REQUESTS=false:

LOG_REQUESTS=false node src/server-ngay-tho.ts (rồi gọi GET /don-hang)
Máy chủ nghe ở cổng 3301
GET /don-hang

Log chi tiết vẫn bật. Boolean("false") là true, vì mọi chuỗi không rỗng đều "đúng". Người đặt biến nghĩ mình đã tắt, và code thì hiểu ngược lại.

Tình huống thứ tư mới là chuyện nghiêm trọng. Điều gì xảy ra nếu máy chạy mà quên đặt ORDER_API_KEY? Lúc đó process.env.ORDER_API_KEY là undefined, và "Bearer " + undefined ra chuỗi "Bearer undefined". Mình gửi hai yêu cầu POST tới máy chủ đã khởi động mà không có khóa, một với khóa sai, một với đúng chữ undefined:

curl -X POST -H 'Authorization: Bearer ...' localhost:3301/don-hang
Bearer undefined -> Đã nhận đơn (201)
Bearer sai       -> Sai khóa (401)

Máy chủ nhận đơn từ bất kỳ ai biết gửi chữ undefined. Không có lỗi nào lúc khởi động, vì thiếu một biến không phải lỗi của JavaScript. Đây là loại lỗi bảo mật chỉ lộ ra khi có người cố tình thử, và lúc đó đã muộn.

Tình huống thứ năm không liên quan tới biến nào, nhưng cùng một họ: đường dẫn data/orders.json là đường dẫn tương đối, và nó được tính từ thư mục bạn đang đứng khi chạy lệnh, chứ không phải từ chỗ file code nằm. Chạy từ thư mục src thay vì thư mục gốc:

cd src && node server-ngay-tho.ts
Error: ENOENT: no such file or directory, open 'C:\moc-demo\don-hang-moc\src\data\orders.json'

Cả năm lỗi đều là "máy em chạy mà". Máy bạn có PORT=3000 đúng, không có dòng rỗng, chạy từ thư mục gốc, và vô tình đã đặt khóa trong terminal của mình từ tuần trước. Máy của anh Khoa thì khác một chút, và chỉ một chút là đủ.

Gom cấu hình vào một chỗ, kiểm tra một lần

Cách sửa mình thích là đừng để process.env rải rác khắp code. Chỉ một file đọc nó, kiểm tra từng biến, đổi sang đúng kiểu, và nếu có gì sai thì dừng ngay lúc khởi động với một thông báo nói rõ biến nào sai. Phần còn lại của chương trình chỉ nhận một đối tượng config đã sạch.

Bài trước đó trong series đã dùng Zod để kiểm tra đơn hàng gửi lên. Cấu hình cũng là dữ liệu từ bên ngoài, nên mình dùng lại đúng công cụ đó. Đây là src/config.ts. Mình giải thích các quyết định ngay sau code:

src/config.ts
// Mọi cấu hình của máy chủ đi qua đây: đọc biến môi trường MỘT lần, kiểm tra, đổi sang đúng kiểu.
// Có sai chỗ nào thì máy chủ dừng ngay lúc khởi động và liệt kê tất cả chỗ sai cùng một lượt.
import { resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { z } from "zod";

const GOC_DU_AN = fileURLToPath(new URL("..", import.meta.url));

// Biến chưa đặt hoặc đặt rỗng ("PORT=") đều coi như chưa có và dùng giá trị mặc định.
// Mặc định là một CHUỖI, để nó cũng đi qua đúng kiểm tra như giá trị người dùng nhập.
const coMacDinh = <T extends z.ZodType>(macDinh: string, kieu: T) =>
  z.preprocess((giaTri) => (giaTri === undefined || giaTri === "" ? macDinh : giaTri), kieu);

const SO_NGUYEN = /^\d+$/;
const boolEnv = z
  .enum(["true", "false", "1", "0"], "chỉ nhận true, false, 1 hoặc 0")
  .transform((giaTri) => giaTri === "true" || giaTri === "1");

const configSchema = z.object({
  PORT: coMacDinh("3000", z.string().regex(SO_NGUYEN, "phải là số nguyên từ 1 đến 65535").transform(Number).pipe(z.number().min(1, "phải từ 1 đến 65535").max(65535, "phải từ 1 đến 65535"))),
  NODE_ENV: coMacDinh("development", z.enum(["development", "test", "production"], "chỉ nhận development, test hoặc production")),
  LOG_LEVEL: coMacDinh("info", z.string().toLowerCase().pipe(z.enum(["debug", "info", "warn", "error"], "chỉ nhận debug, info, warn hoặc error"))),
  LOG_REQUESTS: coMacDinh("false", boolEnv),
  // Đường dẫn tính từ thư mục gốc của dự án, KHÔNG phụ thuộc vào thư mục đang đứng khi chạy lệnh.
  ORDERS_FILE: coMacDinh("data/orders.json", z.string().min(1)).transform((duong) => resolve(GOC_DU_AN, duong)),
  // Bí mật: không có mặc định. Chưa đặt thì dừng, thay vì chạy với một giá trị đoán được.
  ORDER_API_KEY: z.string("chưa đặt (bắt buộc)").min(16, "phải dài ít nhất 16 ký tự"),
});

export type Config = z.infer<typeof configSchema>;

// Các biến mà giá trị không bao giờ được in ra, kể cả trong thông báo lỗi.
const BI_MAT = new Set<string>(["ORDER_API_KEY"]);

export class ConfigError extends Error {
  cacLoi: { bien: string; loi: string }[];

  constructor(cacLoi: { bien: string; loi: string }[]) {
    super(["Cấu hình sai, máy chủ không khởi động:", ...cacLoi.map(({ bien, loi }) => `  - ${bien}: ${loi}`)].join("\n"));
    this.name = "ConfigError";
    this.cacLoi = cacLoi;
  }
}

export function loadConfig(env: Record<string, string | undefined> = process.env): Config {
  const ketQua = configSchema.safeParse(env);
  if (ketQua.success) return ketQua.data;
  throw new ConfigError(
    ketQua.error.issues.map((issue) => {
      const bien = String(issue.path[0]);
      const daNhap = env[bien];
      const kemGiaTri = daNhap !== undefined && daNhap !== "" && !BI_MAT.has(bien) ? ` (đang là "${daNhap}")` : "";
      return { bien, loi: issue.message + kemGiaTri };
    }),
  );
}

// Bản in được ra log lúc khởi động: giá trị bí mật chỉ còn độ dài.
export function moTaConfig(config: Config): Record<string, string | number | boolean> {
  return { ...config, ORDER_API_KEY: `(đã đặt, ${config.ORDER_API_KEY.length} ký tự)` };
}

Mỗi lỗi trong năm lỗi ở trên có một câu trả lời ở đây. Hàm coMacDinh coi biến rỗng (PORT=) giống như biến chưa đặt, nên lỗi thứ hai biến mất. Mặc định là một chuỗi chứ không phải số, để nó đi qua cùng bộ kiểm tra với giá trị người dùng gõ vào, nên mình chỉ có một đường đi cho cả hai. PORT phải khớp mẫu chỉ có chữ số rồi mới đổi sang số và kiểm khoảng 1 đến 65535, nên abc, 0, 70000 và 30.5 đều bị từ chối bằng một câu nói rõ biến nào sai. Biến bật tắt chỉ nhận bốn chuỗi true, false, 1, 0 và đổi sang boolean thật, nên false là false, còn yes bị báo lỗi thay vì được đoán. Đường dẫn ORDERS_FILE được tính từ thư mục gốc của dự án (GOC_DU_AN, lấy từ vị trí của chính file config.ts), nên chạy từ thư mục nào cũng ra cùng một file.

Chỗ quan trọng nhất là ORDER_API_KEY, và nó khác các biến còn lại ở một điểm: nó không có giá trị mặc định. Một giá trị mặc định cho khóa bí mật, kiểu "changeme" hay "dev-key", thì chẳng khác gì để cửa mở. Chưa đặt thì dừng. Yêu cầu dài ít nhất 16 ký tự là một chốt chặn nhỏ nữa, để khóa kiểu abc không lọt qua. Con số 16 là do mình chọn, không có con số chuẩn nào.

Hàm loadConfig gom hết lỗi rồi mới dừng, thay vì dừng ở lỗi đầu tiên. Nếu bạn đã sửa PORT mà vẫn còn LOG_LEVEL sai, bạn không phải chạy lại ba lần để biết hết. Nó nhắc lại giá trị sai vào thông báo (đang là "abc") để người đọc nhìn thấy ngay mình đã gõ gì, trừ biến nằm trong danh sách BI_MAT, vì thông báo lỗi sẽ vào log, và log thì đừng bao giờ chứa khóa. Hàm moTaConfig làm điều tương tự khi in cấu hình lúc khởi động: khóa chỉ còn lại độ dài.

Máy chủ dùng cấu hình mới

Giờ máy chủ chỉ đọc config, không đụng tới process.env nữa, ngoại trừ ở đúng một chỗ là lúc gọi loadConfig():

src/server.ts
// Máy chủ đơn hàng bản dùng cấu hình có kiểm tra. Chạy: npm start  (tức node --env-file=.env src/server.ts)
import { timingSafeEqual } from "node:crypto";
import { readFileSync } from "node:fs";
import { createServer } from "node:http";

import { ConfigError, loadConfig, moTaConfig, type Config } from "./config.ts";

let config: Config;
try {
  config = loadConfig();
} catch (loi) {
  if (!(loi instanceof ConfigError)) throw loi;
  console.error(loi.message);
  process.exit(1);
}

const THU_TU = ["debug", "info", "warn", "error"];
const ghiLog = (muc: string, noiDung: string) => {
  if (THU_TU.indexOf(muc) >= THU_TU.indexOf(config.LOG_LEVEL)) console.log(`[${muc}] ${noiDung}`);
};

// So khóa bằng timingSafeEqual: thời gian so sánh không để lộ khóa đúng được bao nhiêu ký tự.
const khoaDung = (header: string | undefined) => {
  const nhan = Buffer.from(header ?? "");
  const that = Buffer.from(`Bearer ${config.ORDER_API_KEY}`);
  return nhan.length === that.length && timingSafeEqual(nhan, that);
};

const donHang = JSON.parse(readFileSync(config.ORDERS_FILE, "utf8"));

const server = createServer((request, response) => {
  if (config.LOG_REQUESTS) ghiLog("info", `${request.method} ${request.url}`);
  if (request.url === "/don-hang" && request.method === "GET") {
    return void response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(donHang));
  }
  if (request.url === "/don-hang" && request.method === "POST") {
    if (!khoaDung(request.headers.authorization)) return void response.writeHead(401).end("Sai khóa");
    return void response.writeHead(201).end("Đã nhận đơn");
  }
  response.writeHead(404).end();
});

server.listen(config.PORT, () => {
  ghiLog("info", `Máy chủ nghe ở cổng ${config.PORT}`);
  ghiLog("debug", `Cấu hình: ${JSON.stringify(moTaConfig(config))}`);
});

Có hai điểm đáng nói. Ở đầu file, nếu cấu hình sai thì mình in thông báo ra console.error rồi process.exit(1). Mã thoát khác 0 là cách để bất kỳ công cụ nào chạy máy chủ (trình quản lý tiến trình, CI, dịch vụ deploy) biết rằng nó không khởi động được. Thứ hai, ở hàm khoaDung, mình so khóa bằng timingSafeEqual của Node thay vì ===. So sánh chuỗi thông thường dừng ở ký tự đầu tiên khác nhau, nên về lý thuyết thời gian phản hồi hé lộ khóa đúng được bao nhiêu ký tự. Hàm này so toàn bộ độ dài trong thời gian cố định. Với một blog nhỏ thì nguy cơ này rất thấp, nhưng nó chỉ tốn ba dòng nên mình giữ.

File .env, và lệnh node --env-file

Gõ sáu biến trước mỗi lệnh chạy thì không ai chịu nổi, nên người ta ghi chúng vào một file tên .env và nạp file đó vào lúc khởi động. Từ Node 20.6, Node làm được việc này sẵn bằng cờ --env-file, không cần cài thêm thư viện nào. Script start trong package.json ở trên đã dùng nó: node --env-file=.env src/server.ts. Bạn có thể kiểm tra cờ này có trong bản Node của mình bằng node --help:

node --help | grep env-file
  --env-file=...              set environment variables from supplied
  --env-file-if-exists=...    set environment variables from supplied

Cờ --env-file-if-exists giống cờ đầu, chỉ khác ở chỗ nó không lỗi nếu file không có. Mình thử cả hai cách. Khi file .env chưa tồn tại, lệnh npm start dừng ngay với một thông báo rõ ràng:

node --env-file=.env src/server.ts (chưa có file .env)
C:\Program Files\nodejs\node.exe: .env: not found

Và với --env-file-if-exists=.env.khong-co, Node chỉ ghi một dòng cảnh báo rồi chạy tiếp:

node --env-file-if-exists=.env.khong-co src/server.ts (dòng đầu của kết quả)
.env.khong-co not found. Continuing without it.

Với dự án mà team dùng nhiều phiên bản Node cũ hơn, thư viện dotenv làm cùng việc (import "dotenv/config"). Tài liệu hướng dẫn chính thức của Node có trang về cách đọc biến môi trường mô tả cả hai cách.

Giờ viết file .env của bạn. Đừng viết từ đầu: dự án nên có một file mẫu, .env.example, được commit lên Git, liệt kê mọi biến cùng ý nghĩa và mặc định. Người mới chỉ việc sao chép nó thành .env và điền các giá trị còn thiếu:

.env.example
# Sao chép file này thành .env rồi điền giá trị thật. File .env KHÔNG được commit (đã nằm trong .gitignore).
# Mỗi biến có một dòng mô tả. Biến không có giá trị mặc định thì bắt buộc phải điền.

# Cổng máy chủ lắng nghe, từ 1 đến 65535. Mặc định 3000.
PORT=3000

# development, test hoặc production. Mặc định development.
NODE_ENV=development

# Mức log: debug, info, warn hoặc error. Mặc định info.
LOG_LEVEL=info

# Có ghi log từng request không: true hoặc false. Mặc định false.
LOG_REQUESTS=false

# Đường dẫn file đơn hàng, tính từ thư mục gốc của dự án. Mặc định data/orders.json.
ORDERS_FILE=data/orders.json

# BẮT BUỘC. Khóa mà website của quán gửi kèm khi POST đơn mới (ít nhất 16 ký tự).
# Tạo một khóa ngẫu nhiên bằng: node -e "console.log(require('node:crypto').randomBytes(24).toString('hex'))"
ORDER_API_KEY=

Và .gitignore bảo Git đừng bao giờ theo dõi file .env thật:

.gitignore
.env
node_modules/

Mình kiểm xem Git có thật sự bỏ qua file .env không, bằng một lệnh mà bạn nên chạy mỗi khi thêm file bí mật vào dự án:

git check-ignore -v .env
.gitignore:1:.env	.env

Dòng kết quả cho biết quy tắc ở dòng 1 của .gitignore đã khớp với .env. Nếu lệnh này không in gì, file đó sẽ bị Git theo dõi.

Chạy thử: sai thì báo rõ, đúng thì chạy

Giờ chạy lại những tình huống ở trên với máy chủ mới. Trước hết là một file .env cố tình sai ba chỗ: PORT=abc, LOG_LEVEL=Verbose và quên ORDER_API_KEY:

node --env-file=.env src/server.ts (.env có PORT=abc, LOG_LEVEL=Verbose, không có ORDER_API_KEY)
Cấu hình sai, máy chủ không khởi động:
  - PORT: phải là số nguyên từ 1 đến 65535 (đang là "abc")
  - LOG_LEVEL: chỉ nhận debug, info, warn hoặc error (đang là "Verbose")
  - ORDER_API_KEY: chưa đặt (bắt buộc)

Một lần chạy cho ra cả ba lỗi, mỗi lỗi nói đúng tên biến. Mã thoát của lệnh là 1. So với dòng RangeError [ERR_SOCKET_BAD_PORT] ở bản đầu, người mới như anh Khoa chỉ cần đọc đúng một thông báo là biết phải sửa gì. Giờ sửa file .env cho đúng, và cố tình để PORT= rỗng, đặt LOG_LEVEL=DEBUG viết hoa, bật LOG_REQUESTS=true:

.env (bản đúng, khóa là chuỗi giả)
PORT=
LOG_LEVEL=DEBUG
LOG_REQUESTS=true
ORDER_API_KEY=0123456789abcdef0123
node --env-file=.env src/server.ts (rồi GET, và hai lần POST: khóa 'undefined', khóa đúng)
Bearer undefined -> 401
đúng khóa -> 201
[info] Máy chủ nghe ở cổng 3000
[debug] Cấu hình: {"PORT":3000,"NODE_ENV":"development","LOG_LEVEL":"debug","LOG_REQUESTS":true,"ORDERS_FILE":"C:\\moc-demo\\don-hang-moc\\data\\orders.json","ORDER_API_KEY":"(đã đặt, 20 ký tự)"}
[info] GET /don-hang
[info] POST /don-hang
[info] POST /don-hang

Hai dòng đầu là kết quả của hai lệnh curl. Chữ undefined giờ bị từ chối (401), và chỉ khóa đúng mới được nhận (201). PORT= rỗng cho ra cổng 3000, LOG_LEVEL=DEBUG được hiểu là debug, và dòng cấu hình khi khởi động chỉ in độ dài của khóa, không in khóa. Cũng để ý đường dẫn ORDERS_FILE đã thành đường dẫn tuyệt đối.

Còn một câu hỏi mà mọi người đều gặp: điều gì xảy ra khi cùng một biến vừa có trong file vừa được đặt trong terminal? Mình đặt PORT=3555 ngay trước lệnh trong khi file .env có PORT= rỗng:

PORT=3555 node --env-file=.env src/server.ts (dòng đầu của kết quả)
[info] Máy chủ nghe ở cổng 3555

Giá trị đặt ở terminal thắng giá trị trong file. Tài liệu của Node nói điều này rõ: nếu một biến vừa có sẵn trong môi trường vừa có trong file thì giá trị của môi trường được ưu tiên. Quy tắc này hữu ích, vì nó cho phép bạn ghi đè tạm một biến mà không sửa file. Nhưng nó cũng là một nguồn nữa của "máy em chạy mà": nếu bạn đã export PORT=... trong terminal từ hôm qua, file .env của bạn bị âm thầm lờ đi. Khi gặp cấu hình khó hiểu, hãy kiểm tra env | grep PORT (hoặc Get-ChildItem Env: trên PowerShell) trước khi nghi ngờ code.

Cuối cùng là lỗi thứ năm, đường dẫn tương đối. Mình chạy máy chủ từ thư mục src với ORDERS_FILE tính từ thư mục gốc dự án:

cd src && node --env-file-if-exists=.env.khong-co server.ts (PORT và ORDER_API_KEY đặt ngay trước lệnh)
.env.khong-co not found. Continuing without it.
[info] Máy chủ nghe ở cổng 3556

Nó chạy bình thường, vì đường dẫn không còn tính từ thư mục đang đứng.

Bí mật nằm ở đâu khi đưa lên mạng?

Mình cần nói rõ giới hạn của file .env: nó là tiện lợi cho máy của bạn lúc đang viết code, không phải nơi giữ bí mật của một hệ thống thật. File nằm trên đĩa dưới dạng chữ thường, và bất kỳ ai hay công cụ nào đọc được thư mục dự án đều đọc được nó. Với máy chủ thật, bạn đặt biến môi trường trong chính nơi chạy máy chủ: bảng điều khiển của dịch vụ deploy, hoặc kho bí mật của hệ thống CI. Khi đó code vẫn đọc process.env như cũ, và vẫn đi qua loadConfig, nên thiếu biến thì máy chủ dừng lúc khởi động thay vì chạy sai.

Quy tắc còn lại thì đơn giản mà nghiêm: không commit .env, và nếu lỡ commit một khóa thật thì thu hồi nó ngay, đừng chỉ xóa dòng đó khỏi Git, vì bản cũ vẫn nằm trong lịch sử. Mình đã nói kỹ chuyện này ở bài về bảo mật khi dùng AI, và nó đúng với mọi loại khóa chứ không riêng khi dùng AI.

Giữ cấu hình đúng bằng test

Vì mỗi lỗi ở đầu bài giờ có một câu trả lời trong config.ts, mình viết test để chúng không âm thầm quay lại. Các test dưới đây truyền một đối tượng thường vào loadConfig thay vì sửa process.env thật, nên chúng không ảnh hưởng nhau. Chúng kiểm các điều bài này vừa nói: chỉ cần khóa là chạy được với mặc định, PORT rỗng dùng mặc định thay vì thành 0, PORT sai (abc, 0, 70000, 30.5, -1) đều bị từ chối, LOG_REQUESTS=false là false thật, giá trị gõ sai như yes bị báo lỗi, LOG_LEVEL không phân biệt hoa thường, thiếu khóa và khóa quá ngắn có thông báo riêng, nhiều chỗ sai được báo cùng một lượt, thông báo lỗi nhắc giá trị sai nhưng không bao giờ in khóa, ORDERS_FILE thành đường dẫn tuyệt đối, và moTaConfig che khóa. Bạn chạy bằng node --test src/config.test.ts (file test nằm trong repo demo, bài này mình không dán).

node --test src/config.test.ts (phần tổng kết)
# tests 12
# pass 12
# fail 0

Giới hạn của bài thì mình nói thẳng. Mình chưa thử các cờ --env-file trên macOS hay Linux, chỉ trên Windows với Node 22.23. Mình cũng chưa thử cách để NODE_ENV=production thay đổi hành vi, vì ở đây NODE_ENV chỉ được kiểm tra chứ chưa dùng cho việc gì. Còn khóa trong bài là chuỗi giả mình gõ tay, và bạn nên tạo khóa thật bằng lệnh trong .env.example.

Máy anh Khoa chạy được rồi, nhưng người mới vào thì sao?

Anh Khoa sao chép .env.example thành .env, điền khóa, và máy chủ chạy ngay ở lần thứ hai (lần đầu anh quên khóa, và thông báo lỗi nói đúng điều đó). Nhưng đó là vì anh đã biết dự án này. Giờ hãy tưởng tượng một người hoàn toàn mới vào nhóm. Họ phải biết cài Node bản nào, có file nào cần sao chép, biến nào bắt buộc, lệnh nào để chạy thử, và test nào để biết mình đã làm đúng. Nếu những thứ đó chỉ nằm trong đầu của người đã làm lâu, người mới có thể mất cả hai ngày chỉ để chạy được dự án. Viết những điều đó ra thành một tài liệu mà ai cũng làm theo được là việc của các bài viết sau.

Bạn theo dõi cả hành trình ở Nhận dự án cũ: từ bug report đến pull request. Bài Zod validation giải thích cách dùng Zod để kiểm tra dữ liệu từ bên ngoài, và các câu hỏi về Node.js, cấu hình 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.