Node.js 환경 설정의 강력한 도구, NODE_OPTIONS (Next,React 설치시 생기는 에러)

최근에 Next 프로젝트를 회사에서 설치를 했었는데 에러가 계속 떠서 새로 만들기를 몇번을 반복했었다. 그러다가 결국 찾은 문제는 Node 관련된 문제였던거 같다. 따라서 이번에는 관련된 NODE_OPTIONS 을 한번 살펴보려고 한다.

 

Node.js를 사용하다 보면 간혹 기존 환경에서 잘 동작하던 코드가 새로운 Node.js 버전에서 갑자기 오류를 일으키는 경우가 있다. 이는 대부분 Node.js가 내부적으로 사용하는 라이브러리의 버전 변경이나 보안 정책의 강화로 인해 발생하는 문제이다. 이때 개발자가 이러한 변경 사항에 대응하기 위해 알아두어야 할 환경 변수 중 하나가 바로 NODE_OPTIONS이다.

NODE_OPTIONS는 Node.js의 다양한 옵션을 환경 변수로 설정하여 프로세스 전체에 적용할 수 있도록 돕는 도구이다. 메모리 관리, 디버깅, 실험적 기능의 활성화 또는 비활성화와 같은 옵션을 설정하여 개발 환경을 손쉽게 제어할 수 있다. NODE_OPTIONS를 통해 Node.js의 실행 환경을 보다 유연하게 제어하는 방법과, 실질적인 사용 사례를 알아보자.

 

1. NODE_OPTIONS란?

 

NODE_OPTIONS는 Node.js의 동작을 제어하기 위해 사용할 수 있는 환경 변수이다. 이 환경 변수를 통해 Node.js 실행 시 다양한 설정을 전달할 수 있으며, Node.js 프로세스의 전역 설정을 손쉽게 변경할 수 있다.

예를 들어, Node.js가 사용할 메모리 용량을 늘리거나, 디버깅을 활성화하거나, 특정 실험적 기능을 활성화할 때 사용할 수 있다.

 

2. NODE_OPTIONS를 사용하는 이유

1. 프로세스 전역 설정: NODE_OPTIONS를 사용하면 특정 설정을 일괄적으로 Node.js 프로세스 전체에 적용할 수 있어, 별도로 코드 수정 없이 환경 변수를 통해 실행 환경을 제어할 수 있다.
2. 환경별 설정 관리: 로컬 개발 환경, 테스트 환경, 운영 환경 등에서 환경 변수만 다르게 설정하여 다양한 실행 환경을 손쉽게 관리할 수 있다.
3. 문제 해결 도구: 메모리 부족 문제나 특정 기능의 비활성화, 디버깅 옵션 설정 등 문제 해결을 위한 옵션을 쉽게 적용할 수 있다.

 

3. NODE_OPTIONS의 주요 사용 사례

1. 메모리 제한 설정
   • 메모리 부족 오류를 해결하기 위해 Node.js의 힙 메모리 크기를 조정할 수 있다.
2. 디버깅 옵션 활성화
   • 개발 중 애플리케이션의 디버깅을 위해 --inspect 옵션을 활성화하여 디버그 모드로 실행할 수 있다.
3. 실험적 기능 활성화 또는 비활성화
   • 특정 실험적 기능을 활성화하거나 비활성화해야 하는 경우 --experimental 옵션을 사용할 수 있다.

//메모리 제한 설정
 NODE_OPTIONS="--max-old-space-size=8192"
// 디버깅 옵션
 NODE_OPTIONS="--inspect"
//특정 기능 활성화
 NODE_OPTIONS="--experimental-modules"
//특정 기능 비활성화
 NODE_OPTIONS="--no-experimental-fetch"

 

4. openssl-legacy-provider란?

 

openssl-legacy-provider는 Node.js 17 버전 이상에서 OpenSSL 3.0으로 업그레이드되면서 발생한 호환성 문제를 해결하기 위해 사용하는 옵션이다. Node.js는 OpenSSL을 사용하여 암호화 알고리즘을 지원하며, OpenSSL 3.0에서는 기존의 일부 알고리즘과 메서드가 기본적으로 지원되지 않거나 비활성화되었다. 이러한 문제로 인해 ERR_OSSL_EVP_UNSUPPORTED와 같은 오류가 발생할 수 있다.

Error: error:0308010C:digital envelope routines::unsupported

리엑트 설치시 위와 같은 에러가 생기는 경우가 있다는 문의글 본적이 있다. 이 오류는 openssl-legacy-provider 플래그를 사용하여 해결할 수 있다.

NODE_OPTIONS="--openssl-legacy-provider"

이 설정을 통해 Webpack 빌드 과정에서 발생하는 OpenSSL 관련 오류를 해결할 수 있으며, 기존 애플리케이션이 Node.js 17 이상 환경에서 문제없이 동작하도록 도와준다.