🦾 Android | 재오픈 시 Android 뷰가 사라지는 문제 원인 분석 & 복구 자동화

🦾 Android | 재오픈 시 Android 뷰가 사라지는 문제 원인 분석 & 복구 자동화

IDE open

 

개요 (Intro)

오늘은 Android Studio에서 프로젝트를 닫았다가 다시 열면 Android 뷰가 안 보이는 현상을 다뤘다. 단순히 UI 설정 문제가 아니라, 대부분 Gradle 프로젝트로 정상 인식/Sync가 실패할 때 발생하는 케이스라서, 프로젝트 설정과 캐시(.idea)를 중심으로 원인을 좁히고 안정화까지 진행했다.

📅 날짜: 2025.12.27
🎯 목표: 프로젝트 재오픈 시 Android 뷰 미표시 문제를 재발 가능성 낮게 안정화 + 복구 스크립트 추가
🧰 기술: Android Studio, Gradle(8.13), Kotlin(2.x), AGP(8.x), PowerShell

---

문제 정의 (Problem / Motivation)

• 프로젝트를 닫았다가 다시 열면 Android 뷰(Android 탭)가 사라져서 Android Studio가 일반 폴더처럼 보임
• 이때 .idea 폴더를 삭제하고 프로젝트를 다시 열면 Android 뷰가 다시 나타남

이 현상은 보통 “프로젝트 소스가 잘못”이라기보다, Android Studio가 프로젝트를 Gradle/Android 프로젝트로 링크(import)하는 과정이 꼬였을 때 생긴다. 즉, .idea 내부의 Gradle 링크/캐시가 깨진 상태로 남아 재오픈 시 Sync가 정상 수행되지 않으면, Android Studio는 Android 모델을 못 만들고 Android 뷰 자체를 숨기는 식으로 증상이 나타날 수 있다.

참고: 과거 빌드 로그에는 :app:compileDebugKotlin FAILED 같은 흔적이 있었지만, 현재 상태에서는 Gradle CLI 빌드가 정상 통과해서 “항상 컴파일 에러 때문에 발생한다”라고 단정할 수는 없었다.

# 증상 요약
- 재오픈하면 Android 뷰 미표시
- .idea 삭제 후 재오픈하면 복구
- 즉, .idea/Gradle Sync 상태가 꼬일 가능성이 큼

---

해결 과정 (How I Solved It)

1) 우선 Gradle 모델이 정상 로드되는지 확인

Android 뷰가 안 보이는 원인이 “Gradle이 프로젝트를 못 읽는 것”이라면, CLI에서도 힌트를 얻을 수 있다. 그래서 우선 태스크 조회/컴파일/빌드를 직접 돌려봤다.

# 1) 프로젝트의 Gradle 모델이 로드되는지(태스크 조회)
.\gradlew.bat :app:tasks -q

# 2) 컴파일/빌드가 실패하는지 확인
.\gradlew.bat :app:compileDebugKotlin --stacktrace --no-configuration-cache
.\gradlew.bat :app:compileReleaseKotlin --stacktrace --no-configuration-cache

# 3) 실제 APK 조립까지 확인
.\gradlew.bat :app:assembleDebug --stacktrace
.\gradlew.bat :wear:assembleDebug --stacktrace --no-configuration-cache

결과적으로 현재 워크스페이스에서는 빌드가 정상 통과했다. 즉, “항상 컴파일 에러 때문에 Android 뷰가 사라진다”가 아니라, IDE에서 재오픈할 때의 Sync/캐시 충돌 가능성이 더 커졌다.

2) IDE Sync를 불안정하게 만들 수 있는 설정을 안정화

프로젝트의 gradle.properties를 점검했을 때, 아래 두 설정이 “환경에 따라 IDE Sync를 불안정하게 만들 수 있는 포인트”였다.

• org.gradle.java.home 강제 지정: Android Studio의 Gradle JDK 설정과 충돌할 수 있음
• configuration-cache 활성화: IDE tooling model import(Sync)에서 간헐적인 이슈가 날 수 있음

그래서 기본 상태를 안정적으로 만들기 위해:

• org.gradle.java.home는 주석 처리 (IDE에서 설정한 Gradle JDK를 우선)
• org.gradle.configuration-cache는 기본 false로 변경

# gradle.properties (요약)
# org.gradle.java.home=C:/Program Files/Java/jdk-21
org.gradle.configuration-cache=false

초보자 팁: Gradle JDK는 Android Studio에서 Settings > Build Tools > Gradle > Gradle JDK 에서 설정합니다. 프로젝트 파일로 강제하기보다 IDE와 일관되게 맞추는 편이 재오픈 안정성에 유리한 경우가 많습니다.

3) “한 방에 복구”할 수 있도록 PowerShell 스크립트 추가

문제의 핵심이 .idea 캐시/링크 꼬임이라면, 매번 수동으로 폴더 지우는 대신 복구 스크립트가 있으면 훨씬 편하다. 그래서 tools/android-studio-recover.ps1를 추가했다.

# tools/android-studio-recover.ps1 (핵심 개념 요약)

# 1) Gradle 데몬 중지 (안전)
#    - 데몬이 이상 상태면 Sync/빌드가 불안정해질 수 있음
.\gradlew.bat --stop

# 2) IDE/프로젝트 로컬 캐시 삭제 (생성물만 삭제하므로 안전)
#    - .idea  : Android Studio 프로젝트 메타데이터/Gradle 링크
#    - .gradle: 프로젝트 로컬 Gradle 캐시
#    - .kotlin: Kotlin 관련 캐시
Remove-Item -Recurse -Force .idea   -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .gradle -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .kotlin -ErrorAction SilentlyContinue

# 3) 워밍업(선택)
#    - 다음에 Android Studio가 Import/Sync할 때 덜 느리고 덜 흔들리게 도움
.\gradlew.bat tasks -q

그리고 README에도 복구 절차를 추가해서, 팀원이 보더라도 “왜 이게 필요한지/어떻게 쓰는지”가 바로 보이도록 정리했다.

---

결과 (Result)

✅ Gradle CLI 기준 :app/:wear 빌드가 정상 통과
✅ gradle.properties를 안정적인 기본값으로 조정(강제 JDK 제거, configuration-cache off)
✅ tools/android-studio-recover.ps1로 “Android 뷰 미표시” 상황을 빠르게 복구 가능
✅ README에 복구 가이드 추가

---

느낀 점 / 회고 (Reflection)

• “Android 뷰가 안 보인다”는 증상은 UI 설정 문제가 아니라, Gradle Sync/툴링 모델 로딩 실패가 원인인 경우가 정말 많았다.
• .idea 삭제가 해결되는 순간, 문제는 거의 “소스 코드”가 아니라 “IDE 메타데이터/링크 상태” 쪽이라는 확신이 생겼다.
• configuration-cache 같은 성능 옵션은 이득도 크지만, IDE와의 궁합까지 고려해야 한다. 특히 팀 작업/잦은 재오픈 환경에서는 “기본 안정성”을 우선 두는 게 마음이 편했다.

---

참고자료 (References)

• Android Developers - Configure your build
• Gradle - Configuration Cache
• Android Studio 소개