Docker 환경에서 Next.js 디버깅하기 위해 겪은 삽질기

Docker 환경에서 Next.js를 디버깅하려다 보니, 생각보다 복잡한 문제에 막혀 꽤 고생을 했습니다.
특히 --inspect=0.0.0.0:9229 옵션을 썼을 때 예상치 못한 에러가 나서 한참 헤맸는데, 그 과정을 공유합니다.

1. 기본 설정과 시도

처음에는 package.json에 이렇게 디버깅용 스크립트를 넣고,

"debug": "NODE_OPTIONS='--inspect=0.0.0.0:9229' next dev"

Dockerfile에서는

CMD ["npm", "run", "debug"]

를 실행해 원격에서 디버깅할 수 있도록 0.0.0.0에 바인딩하려 했습니다.

2. 5시간 동안의 삽질과 문제 원인 찾기

그런데 컨테이너가 실행되지 않고, 아래와 같은 에러가 계속 떴습니다.

/usr/local/bin/node: must be 0 or in range 1024 to 65535

포트나 IP 문제라는 단서는 있었지만 왜 이런 오류가 나는지 정확히 알 수 없었고,
AI와도 여러 번 대화를 나누며, 관련 문서와 이슈, 커뮤니티를 뒤지며 거의 5시간 동안 씨름했네요.

그 과정에서 답답하고 4번정도는 포기한듯 합니다.

3. 해결책: next-dev.js 수정과 포트 변경

결국 문제를 해결한 방법은 다음과 같습니다.

1) next-dev.js 파일 직접 수정

Next.js 내부에서 디버그 포트를 처리하는 next-dev.js 스크립트에 문제가 있어,
Dockerfile 빌드 시점에 sed 명령어로 직접 고쳐주었습니다.

RUN sed -i 's|NODE_OPTIONS.*nodeDebugType.*|NODE_OPTIONS = `\${NODE_OPTIONS} --\${nodeDebugType}=0.0.0.0:9230`;|' node_modules/next/dist/cli/next-dev.js

2) 기본 포트 9229 대신 9230 사용

그리고 package.json 디버그 스크립트도 9229 대신 9230 포트로 바꿨습니다.

"debug": "NODE_OPTIONS='--inspect=0.0.0.0:9230' next dev",

이렇게 두 가지만 바꾸니, 더 이상 /usr/local/bin/node: must be 0 or in range 1024 to 65535 에러 없이 디버깅이 잘 되더군요.

4. 참고 및 감사

이 문제와 해결법은 다음 GitHub 이슈에서 큰 도움을 받았습니다.
같은 문제로 고생하는 분들은 꼭 참고해보세요.

• Next.js GitHub Issue #53127 - Debug Port Issue
  (StefanMeindlDatenKraft 님 감사합니다!)

고생 끝에 얻은 해결법이라 더 의미가 크네요.
Docker 환경에서 Next.js 디버깅이 막힌 분들께 조금이나마 도움이 되길 바랍니다!

package.json

"scripts": {
    ...
    "debug": "NODE_OPTIONS='--inspect=0.0.0.0:9229' next dev" // 문제 발생하는 디버깅 명령어
   ...
},

Dockerfile

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 3000 9229 9230

# next-dev.js 내부 디버그 포트 문제를 직접 수정하는 부분
RUN sed -i 's|NODE_OPTIONS.*nodeDebugType.*|NODE_OPTIONS = `\${NODE_OPTIONS} --\${nodeDebugType}=0.0.0.0:9230`;|' node_modules/next/dist/cli/next-dev.js 

CMD ["npm", "run","debug"]

부디 더 쉬운방법이 있다면 알려주세요