Cordova 파일명이 아스키코드가 아닐때 (또는 한글인 경우) 빌드 실패

비 ASCII 파일명으로 인한 Cordova 빌드 오류 해결하기

문제

Cordova로 작업하는 중에 예상치 못한 빌드 오류가 발생했고, 원인을 찾기 어려웠습니다. 조사와 검색 끝에 문제의 원인이 비 ASCII 문자(한글 문자)를 포함한 리소스 파일명 때문이라는 것을 발견했습니다.

빌드 프로세스에서 다음과 같은 오류가 발생했습니다:

Error: cmd: Command failed with exit code 1 Error output:
FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':processDebugResources'.
> com.android.ide.common.process.ProcessException: org.gradle.process.internal.ExecException: Process 'command 'C:\andsdk\build-tools\24.0.1\aapt.exe'' finished with non-zero exit value 1

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

해결책

근본 원인을 파악하고 나니 해결책은 간단했습니다: 한글 파일명을 가진 모든 리소스 파일을 영어(ASCII) 문자를 사용하도록 이름을 바꾸었습니다.

이 문제가 발생하는 이유

Android 빌드 도구(특히 aapt.exe - Android Asset Packaging Tool)는 리소스 파일명에 비 ASCII 문자를 사용할 때 제한이 있습니다. 빌드 프로세스가 한글, 일본어, 중국어 또는 다른 비 ASCII 문자가 포함된 파일명을 만나면 이러한 리소스를 제대로 처리하지 못합니다.

이는 Cordova/PhoneGap 프로젝트와 네이티브 Android 개발에 모두 영향을 미치는 Android 빌드 시스템의 알려진 제한사항입니다.

이 문제를 예방하는 방법

향후 프로젝트에서 이 문제를 피하려면:

1. 모든 리소스 파일명에 ASCII 문자(A-Z, a-z, 0-9)만 사용
2. 파일명에 공백을 피하세요(대신 밑줄이나 하이픈 사용)
3. 대소문자 구분 파일 시스템의 문제를 방지하기 위해 파일명은 소문자로 유지
4. 리소스 파일에 명명 규칙을 사용 (예: 홈아이콘.png 대신 icon_home_large.png)

추가 문제 해결 팁

문제를 일으키는 파일을 식별하기 어려운 경우 다음과 같이 할 수 있습니다:

1. --debug 플래그를 사용하여 더 자세한 로그 확인
2. 체계적으로 리소스 그룹의 이름을 변경하여 문제가 있는 파일 찾기
3. 프로젝트 디렉토리에서 비 ASCII 파일명을 식별할 수 있는 도구 사용

참고 자료

더 자세한 정보는 이 스택 오버플로우 게시물을 참조하세요: Ionic build failed: find the line where the error occurs