패키지 설치 오류 및 해결

npm install 또는 pip install 중 발생하는 빌드 오류와 네이티브 C++ 라이브러리 모듈 빌드 실패에 대한 원인 분석 및 해결 팁을 알아봅니다.

디스호스트는 봇 컨테이너 구동 시 package.json 또는 requirements.txt 파일을 자동 탐색해 패키지 설치를 중재합니다. 하지만 패키지 자체의 컴파일 요건 충돌이나 파일 결함으로 인해 부팅 단계에서 멈추거나 중단 오류가 보고될 수 있습니다.

1. 대표적인 C++ 네이티브 모듈 컴파일 실패 오류 (node-gyp 등)

디스코드 봇 중 오디오(음악) 스트리밍 연동 모듈(@discordjs/opus, sodium, canvas 등)은 구동 속도 극대화를 위해 내부적으로 C/C++ 소스코드를 로컬에서 빌드하는 컴파일러 의존성을 띱니다.

증상: gyp ERR! build error 또는 make: *** [Release/obj.target/...] Error 스택 트레이스 출력과 함께 부팅 실패.
원인: 격리 컨테이너의 가벼운 볼륨 환경 내에 무거운 C++ 컴파일 툴체인(gcc, g++, python-dev 등) 컴파일 환경 라이브러리가 존재하지 않아 로컬 컴파일에 실패하는 상황입니다.
해결 방법:

오디오 오푸스 코덱의 경우: C++ 네이티브 빌드가 필요한 @discordjs/opus 대신, 순수 JS(JavaScript)로 짜여 컴파일 단계가 필요 없는 @discordjs/voice + opusscript 조합 라이브러리로 종속성을 선언 및 변경해 줍니다.
이미지 가공 모듈의 경우: 로컬 C 컴파일이 강제되는 canvas 패키지 대신, 사전 컴파일된 런타임 바이너리를 공급해 컴파일 요건이 없는 sharp 라이브러리로 우회 마이그레이션하는 것을 적극 추천합니다.

패키지 설치 도중 네트워크 지연이나 불의의 취소 동작을 수행해 node_modules 폴더가 일부 누락 훼손되었을 때, 다음 부팅 시 시스템이 정상 설치된 것으로 오해하고 구동하다가 Cannot find module 에러를 연쇄 유포할 수 있습니다.

이 경우 캐시 볼륨을 깨끗하게 정리하고 신규 상태로 패키지를 처음부터 다시 내려받아야 합니다.

대시보드 상세 보기 화면으로 이동합니다.
제어 도구바 우측의 동작 제어 드롭다운 버튼을 누릅니다.
의존성 캐시 초기화 및 재설치 메뉴를 클릭합니다.
컨테이너가 볼륨 내부의 node_modules (또는 python 가상 라이브러리 캐시)를 즉시 물리적으로 일괄 제거한 뒤, 빌드 시퀀스에 다시 진입해 패키지를 첫 단계부터 복구 갱신합니다.

패키지 명세 파일의 포맷 결함 유무를 최종 점검하십시오.

Node.js: package.json은 철저한 JSON 문법 표준을 따릅니다. 괄호 누락이나 콤마(,) 기호 오용이 없는지 로컬 JSON Validator 등을 활용해 정합성을 체크해 보시기 바랍니다.
Python: requirements.txt 작성 시 버전을 특정하기 위한 더블 등호(==)를 단일 등호(=)로 기재하거나 오타가 섞이면 PIP 배포 도구가 패키지를 추적해오지 못하므로 확인이 필요합니다.