아래는 “재현 → 원인 좁히기 → 해결” 순서로 정리한 에러 메시지별 if/then 트리입니다.
먼저 공통으로 확인하면 좋은 최소 체크리스트입니다.
- Composer 실행 환경이 CLI인지(PHP-FPM/Apache가 아니라), 그리고 사용 중인 PHP 버전이 무엇인지 확인
- php -m에서 curl 모듈이 로드되는지 확인
- 서버 시간이 맞는지(NTP 동기화) 확인 (시간이 틀리면 TLS 인증서 검증이 자주 깨짐)
- 프록시/방화벽 환경인지(사내망, WAF, outbound 제한) 확인
아래 트리에서 같은 에러가 반복되면, “해결”만 따라가기보다 “원인 좁히기” 단계의 확인 명령을 먼저 수행하는 게 좋습니다.
1) if “The requested PHP extension ext-curl * is missing” then: PHP에 cURL 확장 미설치/미로드
Composer가 네트워크 요청을 할 때 cURL을 사용하려고 하는데, 현재 PHP CLI에 curl 확장이 없을 때 흔히 나옵니다. (웹서버 PHP에는 있는데 CLI에는 없는 경우도 있습니다.)
재현(확인)
- php -m | grep -i curl 결과가 비어 있으면 curl 확장 미로드
- php -i | grep -i "Loaded Configuration File"로 CLI가 읽는 php.ini 확인
원인 좁히기
- PHP 버전에 맞는 curl 패키지가 설치되어 있는지 확인 (Debian은 버전별 패키지 이름이 달라질 수 있음)
- 여러 PHP 버전이 공존하면(예: 8.1/8.2) composer가 어느 php를 타는지(which php, php -v) 확인
해결
- Debian 패키지로 PHP curl 확장 설치 후, 다시 php -m로 로드 여부 확인
- CLI가 다른 php.ini를 보고 있었다면, 해당 ini에서 curl 확장이 활성화되었는지 확인
2) if “cURL error 60: SSL certificate problem: unable to get local issuer certificate” then: CA 인증서 체인 문제
Debian에서 Composer의 다운로드는 HTTPS가 기본이라, 로컬의 CA 인증서(신뢰 저장소)가 최신이 아니거나 경로를 못 찾으면 cURL error 60이 가장 흔하게 발생합니다.
재현(확인)
- Composer 에러에 cURL error 60이 포함되는지 확인
- php -i | grep -i "curl.cainfo\|openssl.cafile\|openssl.capath"로 CA 설정이 비어 있거나 이상한 경로인지 확인
원인 좁히기
- OS의 CA bundle 설치 여부 확인(일반적으로 ca-certificates 패키지)
- 사내 프록시가 TLS를 가로채는 환경(자체 루트 CA 사용)인지 확인
- 컨테이너/최소 설치 이미지라서 CA 번들이 빠져 있는지 확인
해결
- Debian에서 CA 인증서 번들을 설치/갱신하고, 필요하면 PHP가 참조할 CA 경로를 명시
- 사내 프록시 환경이라면 사내 루트 CA를 OS 신뢰 저장소에 추가한 뒤 재시도
- 임시 우회로 SSL 검증을 끄는 방법이 인터넷에 돌지만, 보안상 권장하지 않습니다(특히 CI/운영 서버)
3) if “cURL error 35 / SSL connect error / wrong version number” then: TLS/프록시/중간장비 또는 OpenSSL 호환
이 계열은 원인이 여러 갈래라 “재현”을 조금 더 꼼꼼히 해서 네트워크 계층 문제인지, TLS 라이브러리 문제인지부터 나누는 게 빠릅니다.
재현(확인)
- 에러에 cURL error 35, SSL connect error, wrong version number가 포함되는지 확인
- 같은 서버에서 OS 레벨 도구로 HTTPS 접속이 되는지 확인(예: curl 커맨드로 packagist.org 접근)
원인 좁히기
- HTTPS가 아니라 HTTP 프록시로 잘못 연결되고 있지 않은지 확인(환경변수 HTTP_PROXY/HTTPS_PROXY)
- 방화벽/프록시가 특정 SNI/도메인을 차단하거나 TLS 검사로 실패시키는지 확인
- Debian의 OpenSSL/cURL 버전이 너무 낮아 최신 TLS 정책과 충돌하는지 확인(구형 배포판에서 특히)
해결
- 프록시 환경이면 Composer/시스템에 프록시를 올바르게 설정하고, 인증이 필요하면 자격증명 방식도 점검
- 중간장비 이슈가 의심되면, 우선 동일 네트워크에서 다른 외부 도메인도 실패하는지 비교해 범위를 줄이기
- 구형 Debian이라면 보안 업데이트 적용 및(OpenSSL/cURL 업데이트), 가능하면 지원되는 릴리스로 업그레이드 검토
4) if “Could not resolve host” then: DNS 문제(또는 컨테이너/서버의 resolv.conf)
Composer가 packagist.org나 GitHub에 접근할 때, 도메인 해석이 안 되면 다운로드 자체가 시작되지 않습니다. 의외로 “네트워크는 되는데 DNS만 막힌” 환경도 많습니다.
재현(확인)
- 에러에 Could not resolve host가 포함되는지 확인
- 동일 서버에서 특정 도메인 조회가 되는지 확인(예: getent hosts, nslookup/dig 등)
원인 좁히기
- 서버의 /etc/resolv.conf가 올바른지, 컨테이너에서 올바르게 마운트/전달되는지 확인
- systemd-resolved 사용 여부와 DNS 설정 경로(예: /run/systemd/resolve) 혼선 확인
- 내부 DNS에서 외부 도메인 해석이 차단되는 정책인지 확인
해결
- DNS 서버를 정상 값으로 설정하고, 변경이 유지되도록(systemd-resolved/NetworkManager/클라우드-init 등) 설정 위치를 맞추기
- 컨테이너 환경이면 런타임의 DNS 설정 옵션(Docker의 --dns 등)도 함께 점검
5) if “Operation timed out / Connection timed out” then: outbound 차단, 라우팅, 프록시 미설정
타임아웃은 대체로 “아예 못 나가고 있는” 경우입니다. 방화벽에서 443 outbound가 막혀 있거나, 프록시가 필요한데 설정이 빠졌거나, 라우팅이 꼬였을 때 자주 봅니다.
재현(확인)
- Composer 메시지에 timed out가 반복되는지 확인
- 같은 서버에서 다른 HTTPS 목적지도 타임아웃인지 비교(특정 도메인만인지, 전반인지)
원인 좁히기
- 사내망/클라우드 보안그룹에서 443 egress가 허용되는지 확인
- 프록시가 필수인데 설정이 누락되면, DNS는 되지만 연결이 타임아웃일 수 있음
- IPv6 경로 문제로 특정 환경에서 지연/실패하는 경우도 있어 IPv4/IPv6 우선순위 확인
해결
- 네트워크 정책(방화벽/보안그룹)에서 outbound 443 허용
- 프록시 환경이면 Composer/환경변수에 HTTPS 프록시를 명확히 설정
- IPv6 이슈가 강하게 의심되면 네트워크 구성에 맞게 우선순위 조정(근본 원인 해결이 최선)
6) if “Failed to decode response: zlib” 또는 다운로드가 깨짐 then: 압축/전송 계층 문제(확장, 프록시 변조)
응답을 압축해서 받는 과정에서 깨지면 “decode”나 “zlib” 메시지로 나타나는 경우가 있습니다. 서버가 아주 미니멀한 이미지라 확장이 빠졌거나, 중간 프록시가 응답을 변조/차단하는 경우를 나눠 봐야 합니다.
재현(확인)
- 에러에 Failed to decode response, zlib가 포함되는지 확인
- php -m | grep -i zlib로 zlib 로드 여부 확인
원인 좁히기
- 프록시가 gzip/deflate 응답을 제대로 전달하는지(보안 장비가 응답을 끊거나 수정하는지) 확인
- 패킷 손실이 있는 네트워크에서 대용량 다운로드만 깨지는지 확인
해결
- zlib 확장/관련 패키지 누락이면 보강 후 재시도
- 프록시/중간장비가 원인이라면, 예외 처리(화이트리스트)나 올바른 프록시 설정으로 경로를 정상화
마무리
Debian에서 Composer의 cURL 관련 실패는 대부분 “확장 미설치(ext-curl)”, “CA 인증서(cURL error 60)”, “프록시/TLS(cURL error 35)”, “DNS/타임아웃” 중 하나로 정리됩니다. 먼저 같은 조건으로 재현하고, 메시지에 맞춰 원인을 좁히면 불필요한 설정 변경을 줄일 수 있습니다.
특히 SSL 검증을 끄는 우회는 문제를 가릴 뿐이라, 가능한 한 CA 번들과 네트워크 경로를 정상화하는 방향으로 해결하는 걸 권합니다.