AWS Lambda Sharp 라이브러리 호환성 문제 - lets-go-trip/treaXure-backend GitHub Wiki
🛠️ 문제 상황
Lambda 함수에서 sharp 이미지 처리 라이브러리를 사용하는 Node.js 코드가 다음과 같은 오류를 출력하며 실행되지 않음:
{
"errorType": "Error",
"errorMessage": "Could not load the \"sharp\" module using the linux-arm64 runtime",
"stack": [
"Error: Could not load the \"sharp\" module using the linux-arm64 runtime",
"..."
]
}
🔍 원인 분석
- Lambda의 실행 환경(
linux-arm64)과 개발자의 로컬 빌드 환경(darwin-arm64)이 다름 sharp는 네이티브 바이너리를 포함하는 패키지로, 실행 환경에 맞게 빌드된 버전이 필요
⛔ 실패한 시도들
-
로컬에서 설치한
node_modules포함 배포- 실패 원인: 플랫폼 불일치로 인한 실행 오류
-
AWS 공식 Sharp Layer 사용
- 실패 원인: 초기 설정 오류 또는 레이어와 런타임 버전 불일치 가능성
-
-platform옵션으로 로컬에서 설치 시도npm install sharp --platform=linux --arch=arm64- 실패 원인: macOS에서는 cross-platform native 모듈 빌드가 어려움
✅ 최종 해결: Docker로 빌드된 zip 배포 패키지 사용
실행 환경과 동일한 플랫폼에서 패키징하기 위해 Docker를 사용
📁 디렉토리 구조
.
├── Dockerfile
└── lambda-linux-build/
└── index.js
🧾 Dockerfile 예시
FROM public.ecr.aws/lambda/nodejs:18
RUN yum install -y zip
COPY lambda-linux-build/index.js ${LAMBDA_TASK_ROOT}/
WORKDIR ${LAMBDA_TASK_ROOT}
RUN npm init -y && \
npm install --platform=linux --arch=arm64 @aws-sdk/client-s3 sharp && \
zip -r /tmp/lambda-linux-arm64.zip .
CMD ["index.handler"]
🐳 Docker 이미지 빌드 및 zip 추출
docker build -t lambda-sharp:arm64 .
docker create --name lambda-container lambda-sharp:arm64
docker cp lambda-container:/tmp/lambda-linux-arm64.zip .
docker rm lambda-container
🔄 Lambda 함수 업로드
- Lambda 콘솔 이동 → 함수 선택
- 코드 소스 →
.zip 파일 업로드선택 - 생성한
lambda-linux-arm64.zip업로드 - 저장 및 테스트 실행
🧠 핵심 교훈
sharp와 같은 네이티브 모듈은 빌드 환경과 실행 환경이 일치해야 한다- AWS Lambda의 표준 실행 환경(
linux-arm64)에 맞춰 Docker로 패키징하면 문제 해결 가능 - Lambda Layer는 편리하지만, 런타임 및 종속성과의 정확한 버전 호환이 중요