문제 정의

IntelliJ IDEA 기본 React 프로젝트(CRA, webpack 4 기반)를 실행할 때 다음과 같은 에러가 발생합니다.

1
2
3
4
5
6

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:67:19)
    at Object.createHash (node:crypto:130:10)
    at module.exports (/Users/user/.../node_modules/webpack/lib/util/createHash.js:135:53)
    at NormalModule._initBuildHash (/Users/user/.../node_modules/webpack/lib/NormalModule.js:417:16)
    at handleParseError (/Users/user/.../node_modules/webpack/lib/NormalModule.js:)

프로젝트는 정상적으로 작성했는데 빌드/시작 단계에서 해시 계산 중 오류가 나며 실행이 중단됩니다.

원인 탐구

에러 스택을 보면 webpack/lib/util/createHash.js에서 createHash를 호출하는 순간 실패합니다. 즉 문제는 웹팩이 해시 함수를 만들 때 사용하는 Node.js의 OpenSSL 계층에서 발생합니다.

주요 원인 요약:

요인설명
Node.js 버전17 이상 (OpenSSL 3.0 내장)
webpack 버전4 (구형 해시 알고리즘 사용)
해시 알고리즘MD4 (OpenSSL 3.0에서 기본 제공이 중단됨)

react-scripts(create-react-app) 4.x가 의존하는 webpack 4는 기본적으로 MD4 해시를 사용하는데, Node.js 17부터 내장된 OpenSSL 3.0에서는 MD4가 기본 제공 프로바이더에서 빠졌기 때문에 unsupported 오류가 발생합니다.

근본 원인 분석

근본 원인은 버전 불일치입니다.

  • Node.js 17+ 는 보안 강화를 위해 OpenSSL 3.0으로 전환했습니다.
  • OpenSSL 3.0 은 기본 프로바이더에서 MD4 등 구식 알고리즘을 제거했습니다.
  • webpack 4 는 해시 함수로 MD4를 여전히 사용합니다.
  • 그 결과 createHash('md4') 호출이 digital envelope routines::unsupported 로 실패합니다.

즉, 애플리케이션 코드가 잘못된 것이 아니라, 운영체제(Node.js)가 올린 보안 기준과 프레임워크(webpack 4)가 사용하는 기술이 맞지 않아 발생하는 호환성 문제입니다.

코드 해결책

채택된 답변은 “좋은 방법 2가지"와 “임시방편 2가지"를 제시합니다.

1) node_modules 재설치 (가장 간단한 시도)

의존성이 설치된 Node 버전에 맞춰 컴파일되는 경우, 재설치로 즉시 해결될 수 있습니다.

1
2

rm -rf node_modules
npm install

성공 확률은 가장 낮지만 아무런 부작용 없이 시도해볼 수 있는 방법입니다.

2) 의존성 업데이트 (권장 · 근본 해결책)

거의 모든 의존성에 호환되는 최신 버전이 있습니다. Node 18이 LTS가 된 이후의 버전으로 의존성을 올리세요. react-scripts의 경우 5 이상으로 업그레이드하면 webpack 5가 적용되어 해결됩니다.

1
2
3

npm install react-scripts@latest
# 또는
npm update

1
2
3
4
5

{
  "dependencies": {
    "react-scripts": "^5.0.1"
  }
}

채택 답변: “이것이 사실상 유일하게 올바른 해결책이다. 의존성도 Node.js처럼 업데이트하지 않으면 보안 취약점에 노출될 수 있다.”

3) Node.js v16으로 다운그레이드 (임시방편)

Node를 구형 OpenSSL을 사용하는 v16으로 내려도 실행은 됩니다. 단, 보안이 취약한 구버전을 쓰는 것이므로 근본 해결책이 아닙니다.

1
2
3

# nvm 사용
nvm install 16
nvm use 16

Windows는 nvm-windows를 사용합니다.

4) OpenSSL legacy 프로바이더 사용 (임시 우회책)

Node에게 legacy OpenSSL 프로바이더를 사용하라고 알려주면 구식 해시 알고리즘을 허용합니다. 실행 환경에 따라 설정 방법이 다릅니다.

Unix 계열 (Linux, macOS, Git bash):

1

export NODE_OPTIONS=--openssl-legacy-provider

Windows 명령 프롬프트:

1

set NODE_OPTIONS=--openssl-legacy-provider

PowerShell:

1

$env:NODE_OPTIONS = "--openssl-legacy-provider"

react-scripts 사용 시 한 번만 적용:

1

NODE_OPTIONS=--openssl-legacy-provider npm start

주의: 채택 답변은 “Node 18이 LTS가 된 이후에는 방법 3, 4는 심각한 선택지로 간주해선 안 된다"고 경고합니다.

향후 예방 조치

  1. 의존성을 정기적으로 업데이트하세요. Node.js LTS 전환(16→18→20) 시기에 오래된 프레임워크와 충돌하는 호환성 오류가 흔히 발생합니다.
  2. webpack 4 기반 프로젝트는 webpack 5(또는 react-scripts 5+)로 업그레이드하세요. webpack 5는 기본 해시 알고리즘을 안전한 것으로 교체했습니다.
  3. --openssl-legacy-provider 는 임시 우회책일 뿐입니다. 보안이 약화되므로 장기 운영 환경에서는 사용하지 마세요.
  4. Node.js 메이저 버전 업그레이드 전에 package.json 의존성의 호환성을 확인하세요.
  5. 이미 Node 18 이후 환경이라면 NODE_OPTIONS 우회보다 의존성 업데이트(방법 2)를 먼저 시도하세요.

출처: StackOverflow 69692842 - Error message “error:0308010C:digital envelope routines::unsupported”