Node 최신 버전인데도 Fetch API를 지원하지 않는다면?

오류 해결 기록 🔧

최근에 기존 Angular 프로젝트를 Next.js로 마이그레이션하는 작업을 진행했습니다. 그 원인과 해결 과정을 기록으로 남겨 두려고 합니다. 이 글이 비슷한 문제를 겪는 분들에게 도움이 되었으면 좋겠습니다.

문제 상황

프로젝트를 시작할 때는 별 문제가 없어 보였지만, 프로젝트를 Next.js로 마이그레이션하기 위해 시도하던 중 Fetch API와 관련된 오류가 계속 발생했습니다. 특히 Node.js 환경에서 Request 객체가 정의되지 않았다는 오류였고 그로 인해 진행되지 않는 상황이었습니다.

ReferenceError: Request is not defined
    at Object.<anonymous> (/node_modules/next/dist/server/web/spec-extension/request.js:28:27)

원인 분석

오류 메시지는 Request 객체가 정의되지 않았다고 명확히 말하고 있었고, 이는 Node.js 환경에서 브라우저 전용 API를 사용하려고 시도할 때 흔히 발생하는 문제였습니다.

그런데 제가 알기론 Node.js v18 이상에서는 기본적으로 Fetch API가 활성화된 것으로 알고 있었는데, 왜 이런 문제가 발생했을까요?

특히, 특정 컴퓨터에서만 이 문제가 발생하고, 다른 컴퓨터에서는 문제없이 작동했기 때문에 환경 설정이나 정책 차이일 가능성이 크다고 생각되었습니다.

그래서 문제의 원인을 확인하고 해결하려고 시도했습니다.

문제 해결 과정

1. Node.js 버전 확인

가장 먼저, Node.js 버전을 확인했습니다. Fetch API는 Node.js v18.13.0 이상에서 기본적으로 활성화되지만, 이전 버전에서는 --experimental-fetch 플래그를 추가해야만 사용할 수 있습니다.

node -v

해당 명령어를 통해서 살펴보니 버전은 Node.js v20.17.0으로 확인되었고, 이 버전에서는 Fetch API가 기본 활성화되어 있어야 했습니다. 하지만 오류는 여전히 발생하고 있었는데,,

따라서 문제는 Node.js 버전의 문제가 아닌 다른 환경 설정에 있을 가능성이 컸습니다.

Node.js 버전과 관련된 문제가 있을 수 있다는 생각을 떨칠 수 없어서, nvm을 사용하여 다른 버전의 Node.js로 시도해 보기도 했습니다. 하지만 소용 없었습니다.

구글이나 사수에게 여쭤보기, GPT한테 물어보기 등등 여러 방법을 시도해봤지만 별 소득이 없었습니다.

알아보던 중 node-fetch를 폴리필로 추가하여 Fetch API를 수동으로 활성화하려는 방법이 있다는 사실을 알게 되었는데 하지만 Node.js 자체가 Fetch API를 지원하는 상황에서는 굳이 폴리필을 추가할 필요가 없었기 때문에, 이 방법은 최종적으로 사용하지 않았습니다.

하지만 보통 문제를 해결하기 위해서는 여러 조건들을 생각해보게 되는데

특이하게도 특정 컴퓨터에게만 일어나는 현상이었습니다.

문득 '그렇다면 혹시 컴퓨터에 설정하는 파일이나 세팅에 문제가 있는 게 아닐까?' 라는 생각이 들었습니다.

2. NODE_OPTIONS 환경 변수 확인

그래서 다음으로 확인한 것은 NODE_OPTIONS 환경 변수였습니다. 환경 변수가 Fetch API를 비활성화하고 있을 수 있다는 점을 염두에 두고, 다음 명령어로 현재 설정된 환경 변수를 확인했습니다.

echo $NODE_OPTIONS

결과는 다음과 같았습니다:

--no-experimental-fetch

놀랍게도 여기서 --no-experimental-fetch 플래그가 Fetch API를 비활성화하고 있었습니다. Node.js가 정상적으로 지원하고 있었지만, 이 플래그가 Fetch API를 막고 있었습니다.

아마도 이전 분의 환경 세팅에 문제가 있었던 것으로 보입니다...

3. NODE_OPTIONS 수정

그래서 결국 --no-experimental-fetch 플래그를 제거하여 수정한 후 파일을 저장하고 다시 실행하였고 마침내, Fetch API 관련 오류가 해결되었고, Next.js 프로젝트가 정상적으로 작동하기 시작했습니다.

마무리

이번 문제는 정말 간단한 환경 변수 설정으로 인해 발생했지만, 문제를 해결하는 데까지 꽤 오랜 시간이 들었습니다. 그렇다보니 환경 변수나 시스템 설정이 코드 동작에 미치는 영향을 꼼꼼하게 확인하는 것이 중요하다는 점, 정확한 원인을 분석하는 과정이 필수적임을 다시금 느꼈습니다.

이 글이 정말 진짜 혹여나 같은 문제를 겪고 있는 분들에게 작은 도움이라도 되길 바라며 마칩니다.