패키지 설치 오류 및 해결

npm install 또는 pip install 중 발생하는 빌드 오류와 C++ 네이티브 모듈 컴파일 실패 해결법을 알아봅니다.

디스호스트는 컨테이너 시작 시 package.json 또는 requirements.txt를 자동으로 인식해 패키지 설치를 진행합니다. 하지만 패키지 자체의 네이티브 컴파일 요건이나 캐시 문제로 부팅 중 오류가 발생할 수 있습니다.

1. C++ 네이티브 모듈 컴파일 실패 (`node-gyp` 등)

오디오 스트리밍이나 이미지 처리를 담당하는 일부 라이브러리(@discordjs/opus, canvas 등)는 내부적으로 C/C++ 소스코드를 로컬에서 컴파일해야 합니다.

증상: 콘솔에 gyp ERR! build error 또는 make: *** Error 스택 트레이스가 출력되며 부팅이 멈춥니다.
원인: 경량화된 컨테이너 환경에는 C++ 컴파일 툴체인(gcc, g++, python-dev 등)이 포함되어 있지 않아 로컬 빌드가 실패합니다.
해결 방법:
- 오디오 코덱의 경우: C++ 컴파일이 필요한 @discordjs/opus 대신, 순수 JavaScript로 구현된 @discordjs/voice + opusscript 조합을 사용하는 것을 권장합니다.
- 이미지 처리 모듈의 경우: 로컬 C 컴파일이 요구되는 canvas 대신, 사전 빌드된 바이너리를 제공하는 sharp 라이브러리로 대체하는 것이 안정적입니다.

패키지 설치 도중 연결이 끊기거나 비정상 종료되어 node_modules 폴더가 손상된 경우, 부팅 시 Cannot find module 에러가 반복될 수 있습니다.

이때는 캐시를 비우고 패키지를 처음부터 다시 내려받아야 합니다.

Node.js: package.json은 유효한 JSON 형식이어야 합니다. 쉼표(,) 누락이나 오타가 없는지 확인해 보세요.
Python: requirements.txt에서 버전을 지정할 때 단일 등호(=) 대신 이중 등호(==)를 사용했는지 확인해 보세요.