Cấu hình & biến môi trường

Framework có ba nơi cấu hình, phân theo ai đọc được và đổi lúc nào.

Nơi	Đổi lúc	Ai đọc được	Dùng cho
.env → runtimeConfig	Lúc chạy (không build lại)	Server, trừ nhánh public	Endpoint IAM, gateway, secret
runtimeConfig.public	Lúc chạy	Cả client	Cấu hình form đăng nhập, baseURL API
app.config.ts	Lúc build	Cả client	Tiêu đề, menu, chế độ theme

Nguyên tắc: bí mật luôn ở runtimeConfig (ngoài public). Mọi thứ trong public và app.config.ts đều nằm trong bundle gửi xuống trình duyệt.

Cách đặt tên biến môi trường

Nuxt map biến môi trường theo đường dẫn khoá cấu hình: tiền tố NUXT_, các cấp nối bằng _, camelCase tách thành chữ hoa.

auth.baseURL            → NUXT_AUTH_BASE_URL
auth.endpoints.userInfo → NUXT_AUTH_ENDPOINTS_USER_INFO
apiProxyTarget          → NUXT_API_PROXY_TARGET
public.auth.superRoles  → NUXT_PUBLIC_AUTH_SUPER_ROLES

Chỉ khoá đã tồn tại trong runtimeConfig mới nhận giá trị từ env. Đặt một biến NUXT_* cho khoá không có sẵn thì không có tác dụng gì.

Biến bắt buộc

Biến	Môi trường	Ghi chú
NUXT_SESSION_SECRET	Bắt buộc ở production	Khoá AES-256-GCM cho cookie phiên, ≥ 32 ký tự: openssl rand -base64 32. Dev để trống thì dùng khoá tạm và in cảnh báo; production để trống thì mọi route chạm session trả 500
NUXT_AUTH_BASE_URL	Bắt buộc khi không bật mock	Base URL cổng IAM, bọc cả /iam và /auth
NUXT_API_PROXY_TARGET	Bắt buộc khi dùng /api/**	Backend gateway thật. Để trống thì /api/** trả 500

Các nhóm biến

Nhóm	Biến	Khi nào cần đổi
Phiên và proxy	NUXT_SESSION_SECRET, NUXT_API_PROXY_TARGET, NUXT_PUBLIC_API_BASE_URL	Mỗi môi trường
IAM — endpoint	NUXT_AUTH_BASE_URL, NUXT_AUTH_ENDPOINTS_*	IAM của dự án khác đường dẫn mặc định
IAM — bóc dữ liệu	NUXT_AUTH_MAPPING_*	Response IAM khác cấu trúc mặc định
IAM — mã phương thức OTP	NUXT_AUTH_AUTHEN_METHOD_*	IAM dùng mã authenMethod khác
Form đăng nhập	NUXT_PUBLIC_AUTH_*	Ẩn dropdown ứng dụng, tắt OTP, khai super-role
Dev	NUXT_AUTH_MOCK	Chạy khi chưa có IAM

Tên từng biến, mặc định và nơi đọc: Biến môi trường & runtimeConfig. Bảng đó được CI đối chiếu với runtimeConfig của layer, nên thêm khoá mới mà quên ghi là job quality báo lỗi.

app.config.ts

Cấu hình giao diện, cố định lúc build, merge sâu giữa layer và dự án.

export default defineAppConfig({
  tasco: {
    appTitle: 'Quản lý đơn hàng',
    footerText: '© Tập đoàn Tasco',
    themeMode: 'light',
    topNav: [],
    nav: [],
  },
})

Bảng khoá tasco.* và kiểu NavItem: app.config › tasco. Item có permission tự ẩn với người không có quyền — xem Chặn theo quyền.

Mảng được nối, không thay thế

Nuxt merge cấu hình bằng defu: mảng của dự án đứng trước, mảng của layer nối phía sau. Layer để nav và topNav rỗng nên dự án khai gì thì menu hiện đúng thứ đó — nhưng nếu tự tạo layer trung gian có sẵn menu, hãy nhớ danh sách sẽ cộng dồn.

Đọc cấu hình trong code

// Client — chỉ thấy nhánh public
const { apiBaseURL, auth } = useRuntimeConfig().public

// Server (route Nitro) — thấy toàn bộ
export default defineEventHandler((event) => {
  const { apiProxyTarget, auth } = useRuntimeConfig(event)
})

// Cấu hình giao diện
const { tasco } = useAppConfig()

Luôn truyền event khi gọi useRuntimeConfig trong route Nitro — thiếu nó thì giá trị env của request hiện tại không được áp dụng.

Thêm cấu hình của dự án

// nuxt.config.ts của dự án
export default defineNuxtConfig({
  extends: ['@tasco/nuxt-layer-base'],
  runtimeConfig: {
    // Server-only: đặt NUXT_ERP_TOKEN để ghi đè.
    erpToken: '',
    public: {
      // Client đọc được: NUXT_PUBLIC_FEATURE_EXPORT_EXCEL=true
      featureExportExcel: false,
    },
  },
})

Khai giá trị mặc định (chuỗi rỗng, false) để khoá tồn tại và kiểu được suy đúng — đó cũng là điều kiện để biến NUXT_* có tác dụng.

Liên quan

• Đăng nhập & phân quyền — ý nghĩa nghiệp vụ của nhóm biến auth.
• Phiên đăng nhập — vì sao cần NUXT_SESSION_SECRET.
• CI/CD & Deploy — khai biến ở GitLab CI và compose.
• Biến môi trường & runtimeConfig — bảng tra đầy đủ.