Node.js util.parseEnv 가이드: .env 파일을 검증 가능한 객체로 파싱하는 법

Node.js 애플리케이션에서 .env 파일은 로컬 개발과 테스트 환경을 단순하게 만들어 줍니다. 하지만 .env를 읽는 순간 곧바로 process.env에 값을 넣어 버리면 설정 검증, 기본값 병합, 테스트 격리가 어려워질 때가 있습니다. 특히 라이브러리 코드, 빌드 도구, CLI, 테스트 bootstrap처럼 “파일을 읽되 전역 환경을 바로 바꾸고 싶지는 않은” 코드에서는 한 단계 더 조심해야 합니다.

util.parseEnv()는 이런 상황에서 유용합니다. 이 함수는 .env 형식의 문자열을 받아 일반 객체로 파싱합니다. 즉, 파일을 읽는 책임과 환경변수를 적용하는 책임을 분리할 수 있습니다. 파싱 결과를 검증한 뒤 필요한 값만 process.env에 병합하거나, 아예 별도 config 객체로 넘기는 구조를 만들 수 있습니다.

이 글에서는 util.parseEnv()를 사용해 .env 문자열을 안전하게 다루는 방법, process.loadEnvFile()과의 선택 기준, 설정 검증과 테스트 격리 패턴을 정리합니다. .env 파일을 바로 로드하는 흐름은 Node.js process.loadEnvFile 가이드, CLI 인자와 환경변수를 함께 설계하는 기준은 Node.js util.parseArgs 가이드와 이어집니다. 환경변수를 새 프로세스로 전달할 때의 위생은 Node.js process.execve 가이드도 함께 참고할 수 있습니다.

util.parseEnv가 필요한 순간

H3. process.env를 바로 바꾸지 않고 먼저 검사한다

process.loadEnvFile()은 .env 파일을 읽어 process.env에 값을 채웁니다. 애플리케이션 시작 코드에서는 단순하고 편리합니다. 반면 util.parseEnv()는 문자열을 객체로 바꾸는 데 집중합니다.

import { parseEnv } from 'node:util';

const source = `
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug
FEATURE_PREVIEW=true
`;

const parsed = parseEnv(source);

console.log(parsed);
// {
//   NODE_ENV: 'development',
//   PORT: '3000',
//   LOG_LEVEL: 'debug',
//   FEATURE_PREVIEW: 'true'
// }

이 코드는 전역 상태를 바꾸지 않습니다. 그래서 파싱 결과를 검증하고, 허용된 키만 골라 적용하고, 잘못된 값이 있으면 시작 전에 명확히 실패시킬 수 있습니다.

const allowedKeys = new Set([
  'NODE_ENV',
  'PORT',
  'LOG_LEVEL',
  'FEATURE_PREVIEW'
]);

for (const key of Object.keys(parsed)) {
  if (!allowedKeys.has(key)) {
    throw new Error(`Unsupported environment key: ${key}`);
  }
}

작은 프로젝트에서는 이 검사가 과해 보일 수 있습니다. 하지만 운영 설정이 많아지고 여러 사람이 .env.example, .env.local, .env.test를 함께 다루기 시작하면 허용되지 않은 키를 빨리 잡는 편이 훨씬 안전합니다. 오타로 DATABASE_URL 대신 DATABSE_URL을 넣었는데 애플리케이션이 기본값으로 조용히 실행되는 상황을 막을 수 있습니다.

H3. 파일 읽기와 파싱 책임을 분리한다

util.parseEnv()는 파일 경로를 직접 받지 않습니다. 문자열을 받기 때문에 파일 읽기는 fs/promises.readFile() 같은 API로 분리합니다.

import { readFile } from 'node:fs/promises';
import { parseEnv } from 'node:util';

export async function readEnvFile(pathname) {
  const source = await readFile(pathname, 'utf8');
  return parseEnv(source);
}

이 구조의 장점은 테스트하기 쉽다는 점입니다. 파일 시스템을 직접 건드리지 않고도 파싱과 검증 로직을 문자열로 검증할 수 있습니다.

import test from 'node:test';
import assert from 'node:assert/strict';
import { parseEnv } from 'node:util';

test('parses local env values without mutating process.env', () => {
  const before = process.env.PORT;
  const parsed = parseEnv('PORT=3100\nLOG_LEVEL=debug\n');

  assert.equal(parsed.PORT, '3100');
  assert.equal(process.env.PORT, before);
});

전역 상태를 건드리지 않는 코드는 테스트 실패 원인을 좁히기 쉽습니다. 테스트가 끝난 뒤 process.env를 원래대로 복원하는 보일러플레이트도 줄어듭니다.

설정 검증 패턴

H3. 문자열 값을 도메인 타입으로 변환한다

환경변수 값은 모두 문자열입니다. PORT=3000, FEATURE_PREVIEW=true, CACHE_TTL_SECONDS=60처럼 숫자나 boolean처럼 보이는 값도 파싱 결과에서는 문자열입니다. 그래서 애플리케이션 내부로 넘기기 전에 명시적으로 변환해야 합니다.

export function buildConfig(rawEnv) {
  return {
    nodeEnv: readEnum(rawEnv.NODE_ENV ?? 'development', [
      'development',
      'test',
      'production'
    ], 'NODE_ENV'),
    port: readPort(rawEnv.PORT ?? '3000'),
    logLevel: readEnum(rawEnv.LOG_LEVEL ?? 'info', [
      'debug',
      'info',
      'warn',
      'error'
    ], 'LOG_LEVEL'),
    featurePreview: rawEnv.FEATURE_PREVIEW === 'true'
  };
}

function readPort(value) {
  const port = Number(value);

  if (!Number.isInteger(port) || port < 1 || port > 65535) {
    throw new Error(`Invalid PORT: ${value}`);
  }

  return port;
}

function readEnum(value, allowed, key) {
  if (!allowed.includes(value)) {
    throw new Error(`Invalid ${key}: ${value}`);
  }

  return value;
}

이렇게 하면 설정을 읽는 코드와 설정을 사용하는 코드의 경계가 선명해집니다. 나머지 애플리케이션은 config.port가 숫자인지, config.logLevel이 허용된 문자열인지 매번 의심할 필요가 없습니다.

또 하나의 장점은 오류가 시작 시점에 모인다는 점입니다. 잘못된 설정은 서버가 요청을 받은 뒤 뒤늦게 터지는 것보다 부팅 단계에서 바로 실패하는 편이 낫습니다. 배포 파이프라인이나 컨테이너 health check에서도 원인을 더 빨리 확인할 수 있습니다.

H3. 기본값과 명시값의 우선순위를 고정한다

.env 파싱 결과를 사용할 때는 우선순위를 코드로 명확히 표현해야 합니다. 일반적으로는 셸이나 배포 플랫폼이 이미 주입한 process.env 값을 최우선으로 두고, .env는 빠진 값을 채우는 보조 입력으로 두는 편이 안전합니다.

export function mergeEnv(defaults, fileEnv, runtimeEnv) {
  return {
    ...defaults,
    ...fileEnv,
    ...runtimeEnv
  };
}

const defaults = {
  NODE_ENV: 'development',
  PORT: '3000',
  LOG_LEVEL: 'info'
};

const finalEnv = mergeEnv(defaults, parsed, process.env);
const config = buildConfig(finalEnv);

위 순서에서는 process.env가 가장 마지막에 병합됩니다. 따라서 사용자가 PORT=4000 node ./server.js처럼 명령줄에서 지정한 값은 .env보다 우선합니다. 배포 환경에서 이미 주입된 값도 로컬 파일 때문에 덮이지 않습니다.

반대로 테스트에서는 .env.test 값을 강제로 우선하고 싶을 수 있습니다. 그 경우에도 병합 순서를 함수 호출부에서 드러내는 것이 좋습니다.

const testEnv = mergeEnv(process.env, parsedFromTestFile, {
  NODE_ENV: 'test'
});

중요한 것은 팀이 읽었을 때 우선순위를 추측하지 않아도 되게 만드는 것입니다. 환경 설정은 장애가 났을 때 가장 먼저 확인하는 영역이므로, 암묵적인 규칙보다 작은 함수 하나가 더 실용적입니다.

process.loadEnvFile과의 선택 기준

H3. 애플리케이션 진입점은 loadEnvFile이 단순하다

애플리케이션이 시작할 때 로컬 .env를 읽고 바로 process.env를 채우는 목적이라면 process.loadEnvFile()이 더 간결합니다.

import process from 'node:process';

if (process.env.NODE_ENV !== 'production') {
  process.loadEnvFile('.env.local');
}

이 방식은 “로컬에서 실행하기 쉽게 만든다”는 목적에 잘 맞습니다. 프레임워크 서버, 작은 CLI, 개발용 스크립트처럼 전역 환경을 곧바로 쓰는 코드라면 충분히 좋은 선택입니다.

다만 전역 상태를 바꾼다는 점은 알고 있어야 합니다. 한 번 process.env에 들어간 값은 같은 프로세스 안의 다른 모듈에서도 보입니다. 테스트 runner, 빌드 스크립트, 여러 config 파일을 순서대로 읽는 도구에서는 이 부작용이 문제를 만들 수 있습니다.

H3. 라이브러리와 검증 도구는 parseEnv가 안전하다

라이브러리나 공용 도구는 호출자의 환경을 함부로 바꾸지 않는 편이 좋습니다. 예를 들어 .env.example 파일이 실제 설정과 맞는지 검사하는 CLI를 만든다면 util.parseEnv()가 더 적합합니다.

import { readFile } from 'node:fs/promises';
import { parseEnv } from 'node:util';

const requiredKeys = [
  'DATABASE_URL',
  'SESSION_SECRET',
  'LOG_LEVEL'
];

export async function validateEnvExample(pathname = '.env.example') {
  const source = await readFile(pathname, 'utf8');
  const env = parseEnv(source);

  const missing = requiredKeys.filter(key => !(key in env));

  if (missing.length > 0) {
    throw new Error(`Missing keys in ${pathname}: ${missing.join(', ')}`);
  }

  return env;
}

이 코드는 .env.example을 검사하지만 실제 process.env는 건드리지 않습니다. CI에서 실행해도 다른 테스트나 빌드 단계에 영향을 주지 않습니다. 또한 파싱 결과를 그대로 출력하지 않고, 누락된 키 이름만 보고합니다.

민감정보가 들어갈 수 있는 파일을 검사할 때는 값 자체를 로그에 남기지 않는 것이 기본입니다. DATABASE_URL, SESSION_SECRET, API_TOKEN 같은 값은 디버깅 로그에서도 마스킹해야 합니다.

function summarizeEnv(env) {
  return Object.fromEntries(
    Object.keys(env).sort().map(key => [
      key,
      isSensitiveKey(key) ? '[masked]' : '[set]'
    ])
  );
}

function isSensitiveKey(key) {
  return /TOKEN|SECRET|PASSWORD|DATABASE_URL|PRIVATE/i.test(key);
}

설정 검증 도구는 문제를 알려 주는 역할이지, 비밀 값을 퍼뜨리는 역할이 아닙니다. 키 이름과 존재 여부만으로도 대부분의 설정 문제는 충분히 진단할 수 있습니다.

테스트와 CI에서의 활용

H3. 테스트 fixture를 문자열로 관리한다

util.parseEnv()는 문자열 입력을 받으므로 테스트 fixture를 작게 유지하기 좋습니다. 파일을 만들지 않아도 다양한 케이스를 빠르게 검증할 수 있습니다.

import test from 'node:test';
import assert from 'node:assert/strict';
import { parseEnv } from 'node:util';
import { buildConfig } from '../src/config.js';

test('buildConfig accepts a parsed env fixture', () => {
  const env = parseEnv(`
    NODE_ENV=test
    PORT=4100
    LOG_LEVEL=warn
    FEATURE_PREVIEW=false
  `);

  assert.deepEqual(buildConfig(env), {
    nodeEnv: 'test',
    port: 4100,
    logLevel: 'warn',
    featurePreview: false
  });
});

이 방식은 설정 파싱, 기본값, 타입 변환을 한꺼번에 검증할 수 있습니다. 테스트가 읽기 쉽고, 실패했을 때 어떤 입력이 문제였는지도 바로 보입니다.

파일 경로, 인코딩, 권한 오류까지 검증해야 하는 경우에는 별도 통합 테스트를 두면 됩니다. 대부분의 로직 테스트는 문자열 fixture로 충분하고, 파일 시스템 테스트는 최소한으로 유지하는 편이 빠릅니다.

H3. CI에서는 .env.example 검사를 자동화한다

팀 프로젝트에서는 .env.example이 실제 코드의 요구사항과 어긋나는 일이 자주 생깁니다. 새 환경변수를 추가했는데 예시 파일을 갱신하지 않거나, 더 이상 쓰지 않는 키가 남아 있는 식입니다. CI에서 util.parseEnv() 기반 검사를 실행하면 이런 차이를 빨리 발견할 수 있습니다.

import { readFile } from 'node:fs/promises';
import { parseEnv } from 'node:util';

const expectedKeys = new Set([
  'DATABASE_URL',
  'SESSION_SECRET',
  'LOG_LEVEL',
  'PORT'
]);

const source = await readFile('.env.example', 'utf8');
const exampleEnv = parseEnv(source);
const actualKeys = new Set(Object.keys(exampleEnv));

const missing = [...expectedKeys].filter(key => !actualKeys.has(key));
const unknown = [...actualKeys].filter(key => !expectedKeys.has(key));

if (missing.length > 0 || unknown.length > 0) {
  throw new Error([
    missing.length > 0 ? `missing=${missing.join(',')}` : null,
    unknown.length > 0 ? `unknown=${unknown.join(',')}` : null
  ].filter(Boolean).join(' '));
}

이 검사는 값의 유효성보다 문서와 코드의 계약을 확인하는 데 초점을 둡니다. 실제 운영 비밀을 CI에 넣지 않아도 예시 파일의 키 목록은 점검할 수 있습니다.

실무 체크리스트

H3. parseEnv를 도입할 때 정할 것

util.parseEnv() 자체는 작고 단순한 도구입니다. 실무 품질은 파싱 이후의 정책에서 나옵니다.

• .env 파일은 어느 환경에서 읽는가.
• process.env, .env, 기본값의 우선순위는 무엇인가.
• 허용되지 않은 키를 오류로 볼 것인가, 무시할 것인가.
• 숫자, boolean, URL, enum 값은 어디에서 검증할 것인가.
• 민감정보 키는 어떤 방식으로 마스킹할 것인가.
• 테스트에서는 전역 process.env를 수정하지 않고 검증할 수 있는가.

작은 프로젝트라면 모든 항목을 처음부터 엄격하게 만들 필요는 없습니다. 하지만 최소한 “파싱”, “병합”, “검증”, “로그 출력”은 서로 다른 책임으로 생각하는 편이 좋습니다. 그래야 나중에 설정이 늘어나도 코드가 급격히 복잡해지지 않습니다.

H3. 추천 구조

실무에서는 아래처럼 파일을 나누면 유지보수가 쉽습니다.

src/
  config/
    read-env-file.js
    build-config.js
    validate-env-example.js

read-env-file.js는 파일을 읽고 parseEnv()를 호출합니다. build-config.js는 문자열 환경값을 애플리케이션 config 객체로 변환합니다. validate-env-example.js는 CI나 로컬 검사용으로 .env.example의 키 목록을 확인합니다.

이 구조는 process.env 직접 접근을 줄입니다. 애플리케이션의 나머지 코드는 이미 검증된 config 객체를 받으므로, 설정 오류와 비즈니스 로직 오류를 구분하기 쉬워집니다.

마무리

util.parseEnv()는 .env를 더 통제된 방식으로 다루고 싶을 때 선택할 수 있는 Node.js 기본 도구입니다. process.loadEnvFile()처럼 전역 환경을 바로 바꾸는 대신, 문자열을 객체로 파싱해 검증과 병합 단계를 명확히 둘 수 있습니다.

애플리케이션 진입점에서 간단히 로컬 .env를 읽는 목적이라면 process.loadEnvFile()이 충분합니다. 반대로 라이브러리, 테스트, CI 검증, 설정 진단 도구처럼 전역 상태 변경을 피해야 하는 코드라면 util.parseEnv()가 더 안전합니다. 핵심은 .env 파일 자체가 아니라, 그 값을 어떤 순서로 읽고 검증하고 노출할지에 대한 정책입니다.