안녕하세요 여러분. 제 이름은 Asim Khan이고 현재 Meta Melon에서 풀스택 개발자로 일하고 있습니다. 최근 결혼 모바일 및 웹 애플리케이션인 Naseebi.com 프로젝트를 진행하면서 실망스러운 문제에 직면했습니다. 이 문제는 Node.js의 punycode 모듈 지원 중단과 관련이 있으며, 제 경험과 해결 방법을 여러분과 공유하고 싶습니다.

문제

애플리케이션에서 프로필 생성 기능을 작업하는 동안 502 잘못된 게이트웨이 오류가 발생했습니다. AWS EC2에서 서버 로그를 확인한 후 다음 경고를 발견했습니다.

The punycode module is deprecated. Please use a userland alternative instead. (Use node --trace-deprecation ... to show where the warning was created)

내 코드에서 퓨니코드를 직접 사용하지 않았기 때문에 이것은 이상했습니다. 그러나 package-lock.json 파일을 검사한 후 프로젝트 어딘가에 종속성으로 포함되어 있음을 발견했습니다. 당시 내 Node.js 버전은 v22.0.0이었습니다. v20.9.0, 심지어 v18.18.0으로 다운그레이드를 시도했지만 경고가 계속 발생했습니다.

문제 이해

punycode 모듈은 Node.js 버전 21에서 더 이상 사용되지 않습니다. 이 문제를 해결하려면 권장되는 사용자 영역 대안인 punycode.js로 교체해야 했습니다. 하지만 단순히 userland 모듈을 설치하는 것만으로는 도움이 되지 않는 것 같았습니다.

솔루션 및 해결 방법

문제를 최종적으로 해결하기 위해 취한 단계는 다음과 같습니다.

1. Node.js 버전 다운그레이드

최신 Node.js 버전을 특별히 사용하지 않는 경우 빠른 해결 방법은 21 이전 버전으로 다운그레이드하는 것입니다.

nvm install 20.5.1
nvm use 20.5.1

2. 문제가 있는 종속성 식별

npm ls punycode를 실행하여 여전히 punycode를 사용하고 있는 종속성을 식별할 수 있습니다.

npm ls punycode

제 경우에는 ajv와 whatwg-url-without-unicode가 범인이었습니다. 다음 단계를 통해 이를 찾았습니다.

ajv 업데이트: package.json 파일에서 ajv를 업데이트했습니다.

"overrides": {
  "ajv": "^8.17.1"
}

whatwg-url 업데이트 중: whatwg-url도 업데이트했습니다.

"overrides": {
  "ajv": "^8.17.1",
  "whatwg-url": "^14.0.0"
}

이 업데이트 이후 경고가 사라졌습니다. 하지만 문제가 지속되면 다음 단계를 따르세요.

3. 경고 억제(임시 수정)

package.json 스크립트에서 경고를 표시하지 않을 수 있습니다.

"scripts": {
  "start": "NODE_NO_WARNINGS=1 vite"
}

이렇게 하면 콘솔 출력에서 ​​지원 중단 경고가 제거됩니다.

4. pm2를 사용하여 애플리케이션 관리

마지막으로 두 클러스터 중 하나가 다운되었다는 사실을 깨닫고 pm2로 애플리케이션을 관리하기 위해 프로젝트 루트에 Ecosystem.config.js 파일을 추가했습니다.

module.exports = {
  apps: [
    {
      name: "my-app",
      script: "npm",
      args: "run start",
      instances: "max",
      exec_mode: "cluster",
      max_memory_restart: "1G",
      watch: false,
      autorestart: true,
      restart_delay: 5000,
    },
  ],
};

EC2에서 코드를 푸시하고 풀한 후 pm2 서버를 다시 시작했고 모든 것이 원활하게 작동하기 시작했습니다.

결론

이 문제를 통해 종속성을 관리하고 더 이상 사용되지 않는 모듈을 처리하는 방법에 대해 많은 것을 배울 수 있었습니다. 퓨니코드 모듈은 더 이상 사용되지 않지만 일시적으로 사용할 수는 있지만 향후 문제를 방지하려면 지금 문제를 해결하는 것이 좋습니다. 비슷한 문제가 발생할 경우 이 가이드가 도움이 되기를 바랍니다.