error - Node.js Linux 배포 환경에서의 sharp 라이브러리 로딩 오류 해결 방법 (feat. linux-x64 로딩 오류 해결)

Node.js 환경에서 이미지 리사이징 등의 처리를 위해 sharp 라이브러리를 사용하는 경우가 많습니다. sharp는 성능이 뛰어나지만, 특히 Linux 서버 환경(예: AWS EC2, Elastic Beanstalk)에 배포하는 과정에서 아래와 같은 모듈 로딩 오류를 마주치는 경우가 종종 발생합니다.

Jan 27 06:47:02 ip-172-31-13-178 web[2859]: /var/app/current/node_modules/sharp/lib/sharp.js:113
Jan 27 06:47:02 ip-172-31-13-178 web[2859]:  throw new Error(help.join('\n'));
Jan 27 06:47:02 ip-172-31-13-178 web[2859]:  ^
Jan 27 06:47:02 ip-172-31-13-178 web[2859]: Error: Could not load the "sharp" module using the linux-x64 runtime
Jan 27 06:47:02 ip-172-31-13-178 web[2859]: Possible solutions:
Jan 27 06:47:02 ip-172-31-13-178 web[2859]: - Ensure optional dependencies can be installed:
Jan 27 06:47:02 ip-172-31-13-178 web[2859]:    npm install --include=optional sharp
Jan 27 06:47:02 ip-172-31-13-178 web[2859]: - Ensure your package manager supports multi-platform installation:
Jan 27 06:47:02 ip-172-31-13-178 web[2859]:    See https://sharp.pixelplumbing.com/install#cross-platform
Jan 27 06:47:02 ip-172-31-13-178 web[2859]: - Add platform-specific dependencies:
Jan 27 06:47:02 ip-172-31-13-178 web[2859]:    npm install --os=linux --cpu=x64 sharp
Jan 27 06:47:02 ip-172-31-13-178 web[2859]: - Consult the installation documentation:
Jan 27 06:47:02 ip-172-31-13-178 web[2859]:    See https://sharp.pixelplumbing.com/install

이번 글에서는 이러한 sharp 모듈 로딩 오류가 발생하는 원인을 분석하고, 이를 해결하기 위한 몇 가지 방법들을 제시하고자 합니다.

오류 발생 원인

sharp 라이브러리는 순수 JavaScript로만 구성된 것이 아니라, 내부적으로 고성능 이미지 처리 라이브러리인 libvips(C++ 기반)를 사용합니다. 이 때문에 npm install sharp 명령을 실행하면, JavaScript 코드 외에도 현재 시스템 환경(OS 및 CPU 아키텍처)에 맞는 네이티브 바이너리(binary) 파일을 다운로드하거나 소스 코드를 컴파일하여 빌드하는 과정이 포함됩니다.

오류는 주로 다음과 같은 상황에서 발생합니다.

1. 개발 환경과 실행 환경의 불일치: 개발 환경(예: Windows, macOS)에서 npm install로 생성된 node_modules 디렉토리를 그대로 서버 환경(예: Linux x64)으로 복사하여 사용할 경우, 네이티브 바이너리가 호환되지 않아 오류가 발생합니다.

2. 서버 환경에서의 설치 실패: 배포 과정 중 서버 환경에서 직접 npm install을 실행하는 동안 네트워크 문제, 디스크 공간 부족, 또는 sharp가 의존하는 시스템 라이브러리(libvips 등) 부재로 인해 바이너리 다운로드나 빌드에 실패하는 경우입니다.

3. Docker 환경에서의 불일치: Docker 이미지를 빌드하는 환경과 실제 컨테이너가 실행되는 환경의 아키텍처나 OS가 다른 경우에도 유사한 문제가 발생할 수 있습니다. Multi-stage build 사용 시 특히 주의가 필요합니다.

결론적으로, 이 오류의 핵심 원인은 애플리케이션이 실제로 실행되는 환경(예: linux-x64)에 호환되는 sharp 네이티브 모듈이 제대로 설치되지 않았기 때문입니다.

해결 방법

오류 메시지에서도 몇 가지 해결책을 제시하지만, 보다 근본적이고 확실한 해결 방법은 다음과 같습니다.

1. 실행 환경에서 의존성 재설치 (권장)

가장 확실하고 권장되는 방법은 애플리케이션이 실제 구동될 대상 서버 환경에서 직접 npm install을 다시 실행하는 것입니다.

# 서버 접속 후 프로젝트 디렉토리로 이동
rm -rf node_modules
npm install

AWS Elastic Beanstalk 사용 시

EB는 기본적으로 배포 과정에서 EC2 인스턴스 내부에서 npm install을 실행합니다. 배포 로그(/var/log/eb-engine.log 등)를 확인하여 npm install 단계에서 sharp 관련 오류가 발생하지 않았는지 확인해야 합니다. 만약 libvips-dev와 같은 시스템 패키지가 추가로 필요하다면, .ebextensions나 Platform Hooks를 사용하여 npm install 실행 전에 해당 패키지가 미리 설치되도록 구성해야 할 수 있습니다.

Docker 사용 시

Dockerfile에서 COPY package*.json ./ 이후, RUN npm install 명령이 실제 애플리케이션이 실행될 환경과 동일한 베이스 이미지 및 아키텍처에서 실행되는지 확인해야 합니다. 특히 Multi-stage build를 사용하는 경우, 빌드 스테이지와 최종 실행 스테이지의 환경 차이에 유의해야 합니다.

2. 특정 플랫폼용 설치/재빌드 지정

경우에 따라 특정 플랫폼용 바이너리를 명시적으로 설치하거나 재빌드해야 할 수도 있습니다.

# Linux x64용 sharp 강제 설치
npm install --os=linux --cpu=x64 sharp

# 또는 이미 설치된 sharp를 Linux x64용으로 재빌드
npm rebuild sharp --platform=linux --arch=x64

이 방법은 CI/CD 파이프라인 등에서 특정 타겟 환경을 위한 빌드를 수행할 때 유용하게 사용될 수 있습니다.

3. 시스템 의존성(libvips) 확인 및 설치

sharp는 libvips라는 시스템 라이브러리에 의존합니다. 대부분의 경우 npm install sharp 과정에서 관련 의존성을 자동으로 처리하려고 시도하지만, 실패하는 경우가 있습니다. 이 경우, 대상 시스템에 libvips 관련 개발 패키지가 설치되어 있는지 확인하고, 없다면 수동으로 설치해야 합니다.

Debian/Ubuntu 계열

sudo apt-get update
sudo apt-get install -y libvips-dev

CentOS/Fedora/RHEL 계열

sudo yum update
sudo yum install -y vips-devel

Elastic Beanstalk의 .ebextensions나 Dockerfile의 RUN 명령어를 사용하여 배포/빌드 초기 단계에 이러한 시스템 패키지를 미리 설치하도록 구성하는 것이 좋습니다.

4. npm 캐시 정리

매우 드문 경우지만, npm 캐시 데이터가 손상되어 설치 과정에 문제가 발생하는 경우도 있습니다. 문제가 지속될 경우 캐시를 정리하고 다시 시도해 볼 수 있습니다.

npm cache clean --force
rm -rf node_modules
npm install

결론

sharp 모듈 로딩 오류는 주로 개발 환경과 실제 실행 환경 간의 네이티브 바이너리 비호환성 때문에 발생합니다. 문제 해결의 핵심은 애플리케이션이 최종적으로 구동될 환경에 맞는 sharp 바이너리를 올바르게 설치하는 것입니다. 대부분의 경우, 대상 실행 환경에서 node_modules 디렉토리를 삭제하고 npm install을 다시 실행하는 것으로 문제가 해결됩니다. Docker나 Elastic Beanstalk과 같은 환경에서는 빌드 및 배포 과정에서 npm install이 올바르게 수행되고 필요한 시스템 의존성(libvips 등)이 제대로 설치되는지 확인하는 것이 중요합니다.

이 글이 sharp 관련 오류로 어려움을 겪는 분들에게 도움이 되었기를 바랍니다.