Android Studio가 Gradle 동기화 단계에서 "멈추는" 경우, SDK Manager가 구성 요소를 로드하지 않거나 Maven Central에서 종속성을 다운로드하지 않는 경우 — 80%의 경우 문제는 코드가 아니라 네트워크 환경에 있습니다. 기업 방화벽, VPN, 리포지토리의 IP 차단 또는 단순히 인터넷에 대한 직접 접근이 없는 경우 — 이는 IDE, Gradle 및 SDK Manager의 세 가지 수준에서 프록시를 올바르게 설정하여 해결할 수 있습니다. 프록시를 올바르게 설정하고 불필요한 동기화 오류를 피하는 방법을 살펴보겠습니다.
Android 개발자에게 프록시가 필요한 이유
Android Studio와 함께 프록시는 여러 시나리오에서 사용됩니다. 첫 번째는 기업 네트워크로, 인터넷에 직접 접근할 수 없으며 모든 트래픽, google(), mavenCentral() 및 dl.google.com에 대한 요청이 회사의 프록시 서버를 통해 이루어져야 합니다. 두 번째는 지역 제한을 우회하는 것입니다: 일부 SDK 구성 요소, Google Play Services API 또는 서드파티 리포지토리는 특정 국가에서 직접 접근할 수 없으며, 개발자는 다른 지리적 위치의 IP를 통해 트래픽을 라우팅해야 합니다.
세 번째 시나리오는 애플리케이션의 geo-종속 기능을 테스트하는 것입니다. 애플리케이션이 사용자 국가에 따라 다른 콘텐츠, 가격 또는 광고를 표시하는 경우, QA 엔지니어와 개발자는 릴리스를 기다리지 않고 빌드 및 디버깅 단계에서 필요한 지역의 요청을 에뮬레이트해야 합니다. 네 번째는 특정 서비스에 대한 접근이 제한된 데이터 센터에 물리적으로 위치한 CI/CD 러너와 작업할 때이며, 프록시는 필요한 리포지토리나 API에 "접근"할 수 있는 유일한 방법이 됩니다.
이러한 모든 경우에 공통된 논리는 Gradle, SDK Manager 및 IDE 자체가 프록시 서버의 주소, 포트 및 필요 시 인증 정보를 알아야 한다는 것입니다. 그렇지 않으면 프로젝트 동기화가 타임아웃이나 연결 오류로 실패하게 됩니다.
개발을 위한 프록시 유형 선택하기
개발 및 테스트에서는 익명성보다는 안정적인 연결과 긴 다운로드 중 낮은 중단 비율이 중요합니다 (예: Android SDK Platform Tools는 수백 메가바이트에 달합니다). 아래는 Android 개발자의 작업에 적용 가능한 프록시 유형 비교입니다.
| 프록시 유형 | 사용 시기 | 특징 |
|---|---|---|
| 데이터 센터 프록시 | SDK 다운로드, Gradle 동기화, CI/CD | 높은 속도, 낮은 가격, 대용량 다운로드에 안정적 |
| 주거용 프록시 | geo-종속 API 및 콘텐츠 테스트 | 실제 사용자 IP, 서비스에 의해 차단될 확률이 낮음 |
| 모바일 프록시 | 특정 국가에서 모바일 API 및 푸시 알림 테스트 | 통신사 IP, 실제 모바일 트래픽에 최대한 가깝다 |
Gradle의 순수한 동기화 및 종속성 다운로드를 위해서는 데이터 센터 프록시를 사용하는 것이 더 합리적입니다 — 이들은 불필요한 지연 없이 안정적인 높은 속도를 제공합니다. 만약 작업이 애플리케이션의 백엔드가 다른 국가의 사용자에게 어떻게 응답하는지 확인하는 것이라면, 주거용 또는 모바일 IP가 더 적합합니다.
gradle.properties에서 프록시 설정하기
gradle.properties 파일은 Gradle이 HTTP 및 HTTPS 연결을 위한 프록시 설정을 찾는 주요 장소입니다. 이 파일은 프로젝트의 루트에 위치할 수 있으며 (해당 프로젝트에만 적용됨) 또는 전역 디렉토리 ~/.gradle/gradle.properties에 위치할 수 있습니다 (모든 프로젝트에 적용됨). 프록시를 통해 지속적으로 작업하려면 두 번째 옵션을 권장합니다.
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
# 선택 사항 — 프록시를 우회하여 직접 연결되는 예외
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp
파일을 저장한 후 반드시 File → Sync Project with Gradle Files를 클릭하거나 도구 모음의 "코끼리" 아이콘을 클릭하세요. IDE가 변경 사항을 자동으로 감지하지 못하는 경우, Android Studio를 재시작하세요 — 때때로 프록시 설정의 캐시는 Gradle Daemon 프로세스를 재시작할 때까지 유지됩니다.
중요한 점: systemProp.* 매개변수는 Gradle이 실행되는 JVM 수준에서 작동하므로, 이들은 종속성 다운로드뿐만 아니라 빌드 스크립트 내의 모든 네트워크 요청에도 영향을 미칩니다 (예: 외부 API를 호출하는 사용자 정의 Gradle 작업이 있는 경우).
Android Studio에서 프록시 설정하기
Gradle 외에도 IDE에는 자체 네트워크 설정이 있습니다 — 이는 플러그인, IDE 업데이트, 라이센스 확인 및 Google의 팁과 같은 일부 기능을 위해 필요합니다. 이 설정은 File → Settings → Appearance & Behavior → System Settings → HTTP Proxy를 통해 열 수 있습니다 (macOS에서는 Android Studio → Preferences).
열린 창에서 Manual proxy configuration을 선택하고 호스트와 포트를 입력한 후, 필요 시 Proxy authentication을 체크하고 로그인 및 비밀번호를 입력하세요. 거기에는 Check connection 버튼도 있어, 테스트 URL (예: https://dl.google.com)을 입력하고 클릭하여 프로젝트의 전체 동기화를 실행하기 전에 연결이 올바른지 확인할 수 있습니다.
차이를 이해하는 것이 중요합니다
Settings의 HTTP Proxy 설정은 IDE 자체에 영향을 미치고 (플러그인, 업데이트), gradle.properties의 매개변수는 Gradle 빌드 프로세스에 영향을 미칩니다. 이는 두 개의 독립적인 메커니즘이며, 프록시를 통한 완전한 작업을 위해서는 일반적으로 두 가지 모두를 설정해야 합니다.
SDK Manager를 위한 프록시
SDK Manager는 Android 플랫폼, 빌드 도구, 에뮬레이터 및 시스템 이미지를 다운로드하는 별도의 구성 요소입니다. SDK Manager는 역사적으로 IDE의 동일한 시스템 설정을 통해 프록시 구성을 지정하지만, 독립 실행형 sdkmanager (명령줄에서 실행하는 CLI 유틸리티)를 사용할 때는 매개변수를 JVM 플래그를 통해 명시적으로 전달해야 합니다.
sdkmanager --proxy=http \
--proxy_host=proxy.example.com \
--proxy_port=8080 \
--list
sdkmanager가 스크립트를 통해 실행되는 경우, 실행 파일이 읽는 JAVA_OPTS 환경 변수에 프록시를 직접 설정할 수 있습니다:
export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
자주 발생하는 오류는 Android Studio에서 프록시를 설정했지만, sdkmanager 또는 avdmanager와 같은 독립 실행형 유틸리티를 잊어버리는 것입니다. 이들은 별도의 Java 프로세스를 실행하며 IDE의 설정을 자동으로 상속받지 않습니다.
gradlew 및 환경 변수를 위한 프록시
IDE를 우회하여 터미널에서 ./gradlew로 프로젝트를 빌드하는 경우 (예: CI/CD 또는 단순한 습관으로), gradle.properties를 변경하지 않고도 명령어에 프록시를 직접 전달할 수 있습니다:
./gradlew build \
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080
지속적으로 사용하려면 쉘 프로필 (.bashrc, .zshrc for Linux/macOS 또는 Windows 환경 변수)에서 GRADLE_OPTS 환경 변수를 설정하는 것이 더 편리합니다:
export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"
이는 GitHub Actions, GitLab CI 또는 Jenkins의 CI 러너에서 특히 유용합니다. 여기서 환경 변수는 job 수준에서 한 번 설정되며, 이후 모든 빌드 단계에서 자동으로 인식되어 프로젝트 파일을 수정할 필요가 없습니다.
일반적인 동기화 오류 및 해결 방법
프록시 설정 시 개발자들이 자주 겪는 오류와 이를 해결하기 위한 구체적인 단계를 살펴보겠습니다.
| 오류 | 원인 | 해결 방법 |
|---|---|---|
| Connection timed out | 프록시가 지정되지 않았거나 접근할 수 없음 | gradle.properties에서 host/port를 확인하고 curl을 통해 프록시의 접근 가능성을 테스트하세요 |
| 407 Proxy Authentication Required | 로그인/비밀번호가 전달되지 않음 | systemProp.http.proxyUser 및 systemProp.http.proxyPassword를 추가하세요 |
| Unable to resolve host | DNS 해석이 프록스를 통해 이루어지지 않음 | SOCKS5를 위한 socksProxyHost 대신 http를 사용하세요 |
| Could not GET 'https://dl.google.com/...' | Gradle 설정은 되어 있지만 IDE에서는 설정되지 않음 (또는 그 반대) | 두 곳 모두에서 설정을 동기화하세요: Settings → HTTP Proxy 및 gradle.properties |
| SSL handshake failed | 프록시가 SSL을 가로챔 (기업 MITM) | 프록시의 루트 인증서를 JDK의 cacerts에 가져오세요 |
특정 Maven 아티팩트를 다운로드할 때 오류가 발생하는 경우 (예: androidx.* 라이브러리), Gradle의 확장 로그를 일시적으로 활성화하는 것이 유용합니다. ./gradlew build --info 명령을 사용하면 연결이 끊어지는 요청과 서버가 반환하는 응답 코드를 확인할 수 있습니다.
인증이 필요한 프록시: 로그인 및 비밀번호
프록시가 인증을 요구하는 경우 (이는 유료 프록시 서비스 및 기업 게이트웨인 경우 표준 상황입니다), gradle.properties에 두 줄을 추가해야 합니다:
systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword
프로젝트의 gradle.properties에 프록시 비밀번호를 평문으로 저장하는 것은 좋지 않은 관행입니다. Git에 커밋되지 않는 사용자 홈 디렉토리의 전역 파일을 사용하거나 CI/CD 단계에서 환경 변수를 통해 비밀번호를 전달하여 비밀이 리포지토리에 유출되지 않도록 하세요.
IP 회전이 필요한 시나리오 (예: 다양한 주소에서 API 한도를 테스트하는 경우)에서는 주소 풀과 단일 로그인으로 구성된 프록시 서비스를 사용하는 것이 더 편리합니다 — 그러면 회전은 공급자 측에서 설정되고, gradle.properties에서 세션 포트만 변경하면 됩니다.
진단 체크리스트
모든 설정 후에도 동기화가 여전히 실패하는 경우, 다음 항목을 순서대로 확인하세요:
- 프록시의 접근 가능성을 직접 확인하세요:
curl -x http://proxy.example.com:8080 https://dl.google.com - Settings → HTTP Proxy와 gradle.properties에 설정이 동시에 작성되었는지 확인하세요
- Gradle 캐시를 지우세요:
./gradlew --stop및.gradle/caches폴더를 삭제하세요 - 파일에 host/port 값 주위에 불필요한 공백이나 따옴표가 없는지 확인하세요
- SOCKS5를 사용하는 경우 — http.proxyHost 대신 socksProxyHost/socksProxyPort를 사용하세요
- 기업 MITM 프록시의 경우, 인증서를 JDK의 신뢰할 수 있는 인증서 저장소에 가져오세요 (keytool -import)
- properties 파일에 변경 사항이 있을 경우 Android Studio 및 Gradle Daemon을 재시작하세요
결론
Android 개발에서 프록시 설정은 세 가지 수준에서 작업하는 것입니다: IDE 자체를 위한 Android Studio의 시스템 설정, 빌드 프로세스를 위한 gradle.properties의 systemProp 매개변수, 그리고 sdkmanager와 같은 독립 실행형 유틸리티를 위한 별도의 구성입니다. 대부분의 동기화 오류는 하나의 수준이 설정되었지만 다른 수준이 잊혀지거나, 인증이 필요한 프록시에서 인증이 누락되기 때문에 발생합니다.
단순히 안정적으로 종속성과 SDK 구성 요소를 작업 프록시를 통해 다운로드하는 것이 목표라면, 데이터 센터 프록시가 적합합니다 — 이들은 빠르고 대용량 다운로드 시 불필요한 지연을 발생시키지 않습니다. 특정 국가의 사용자 또는 모바일 통신사에서 애플리케이션이 어떻게 작동하는지 테스트해야 하는 경우, 주거용 프록시 또는 모바일 IP를 고려해 보세요 — 이들은 다양한 지역에서 서비스의 동작을 보다 현실적으로 보여줍니다.