Skip to content

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úcAi đọc đượcDùng cho
.env → runtimeConfigLúc chạy (không build lại)Server, trừ nhánh publicEndpoint IAM, gateway, secret
runtimeConfig.publicLúc chạyCả clientCấu hình form đăng nhập, baseURL API
app.config.tsLúc buildCả clientTiê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ếnMôi trườngGhi chú
NUXT_SESSION_SECRETBắt buộc ở productionKhoá 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 hoặc ngắn hơn 32 ký tự thì mọi route chạm session trả 500
NUXT_AUTH_BASE_URLBắt buộc khi không bật mockBase URL cổng IAM, bọc cả /iam và /auth
NUXT_API_PROXY_TARGETBắt buộc khi dùng /api/**Backend gateway thật. Để trống thì /api/** trả 500

Các nhóm biến ​

NhómBiếnKhi nào cần đổi
Phiên và proxyNUXT_SESSION_SECRET, NUXT_API_PROXY_TARGET, NUXT_PUBLIC_API_BASE_URLMỗi môi trường
Chống CSRFNUXT_CSRF_ALLOWED_ORIGINS, NUXT_CSRF_ENABLEDCó app khác origin cần gọi BFF, hoặc đã chống CSRF ở lớp phía trước
IAM — endpointNUXT_AUTH_BASE_URL, NUXT_AUTH_ENDPOINTS_*IAM của dự án khác đường dẫn mặc định
IAM — bóc dữ liệuNUXT_AUTH_MAPPING_*Response IAM khác cấu trúc mặc định
IAM — mã phương thức OTPNUXT_AUTH_AUTHEN_METHOD_*IAM dùng mã authenMethod khác
Form đăng nhậpNUXT_PUBLIC_AUTH_*Ẩn dropdown ứng dụng, tắt OTP, khai super-role
DevNUXT_AUTH_MOCKChạ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.

ts
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 ​

ts
// 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 ​

ts
// nuxt.config.ts của dự án
export default defineNuxtConfig({
  extends: ['@tasco-fe/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 ​