첫 Cordova 프로젝트 만들기

지난 시간에 Cordova 설치를 완료했으니, 이번 시간에는 CLI 명령어로 프로젝트를 생성하는 방법을 알아보겠습니다.

1. Cordova 프로젝트 생성하기

터미널을 열고 프로젝트를 저장할 폴더로 이동한 뒤 아래 생성 명령어를 실행하세요.

cordova create hello com.foxdevelop.hello HelloWorldCode language: CSS (css)

매개변수 설명

1. hello : 프로젝트 폴더 이름
2. com.example.hello : 앱 패키지명(안드로이드 고유 식별자, 출시 시 반드시 수정해야 함)
3. HelloWorld : 앱에 표시되는 이름

아래는 실제 예시로, D드라이브에 디렉터리를 만들고 해당 폴더 안에 프로젝트를 생성하는 과정입니다.

C:\Users>d:

D:\>mkdir cordovademo

D:\>cd cordovademo

D:\cordovademo>cordova create hello com.foxdevelop.hello HelloWorld
Creating a new cordova project.Code language: CSS (css)

그러면 D드라이브 안에 cordovademo 폴더가 생성되고, 내부에 hello 하위 폴더가 만들어진 것을 확인할 수 있습니다.

핵심 소스 코드 경로 : hello/www/

진입 페이지 : www/index.html

platforms 폴더 내 파일은 절대 수정하지 마세요. 빌드 과정에서 덮어쓰기됩니다!

2. 프로젝트 진입 후 플랫폼 추가하기

cd hello

플랫폼 추가

# 안드로이드 플랫폼 (Windows에서 사용 가능)
cordova platform add android

# iOS 플랫폼【Windows에서는 컴파일 불가! Mac 컴퓨터만 지원】
# cordova platform add iosCode language: PHP (php)

실행 로그 예시

D:\cordovademo>cd hello

D:\cordovademo\hello>cordova platform add android
Using cordova-fetch for cordova-android
Adding android project...
Creating Cordova project for the Android platform:
        Path: platforms\android
        Package: com.foxdevelop.hello
        Name: HelloWorld
        Activity: MainActivity
        Android Target SDK: android-36
        Android Compile SDK: 36
Subproject Path: CordovaLib
Subproject Path: app
Android project created with cordova-android@15.1.0

D:\cordovademo\hello>cordova platform ls
Installed platforms:
  android 15.1.0
Available platforms:
  browser
  electronCode language: CSS (css)

3. 사전 환경 검사 (중요)

cordova requirements

명령어로 시스템 환경 설정 상태를 확인할 수 있으며, JDK 설치 여부 등을 체크합니다.

D:\cordovademo\hello>cordova requirements
Android SDK is missing cmdline-tools directory.

Requirements check results for android:
Java JDK: installed 11.0.31
Android SDK: installed true
Android target: not installed
Command failed with exit code 1: avdmanager list target
'avdmanager' �����ڲ����ⲿ���Ҳ���ǿ����еij���
���������ļ���
Gradle: not installed
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path, or install Android Studio
Some of requirements check failedCode language: PHP (php)

정상적으로 설정되었을 경우 아래와 같이 표시됩니다.

Java JDK: installed
Android SDK: installed
Gradle: installed

하지만 본 환경에서는 Gradle: not installed로 확인되었습니다.

만약 JDK가 설치되지 않았다면 별도로 설치해야 합니다. JDK 설치 방법은 다른 강의를 참고하세요.

필자는 JDK 11 버전을 사용했습니다.

필자의 PC에서 발생한 오류 내용은 다음과 같습니다.

D:\cordovademo\hello>cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=undefined (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)
Android SDK is missing cmdline-tools directory.
Using Android SDK: D:\Sortware\ADB
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path, or install Android StudioCode language: JavaScript (javascript)

안드로이드 스튜디오를 설치해야 합니다. 안드로이드 SDK가 포함되어 있습니다.

안드로이드 스튜디오 설치 관련 내용은 다른 강의를 참고하세요.

안드로이드 스튜디오 상단 메뉴 Tools → SDK Manager에 진입한 뒤 SDK 경로를 확인하세요.

그 다음 환경 변수를 설정합니다.

변수명 : ANDROID_HOME
변수값 : C:\Users\xxxxx\AppData\Local\Android\Sdk

환경 변수 생성 외에도 Path에 경로를 추가해야 합니다.

%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\cmdline-tools\latest\bin

Android Studio 명령줄 도구 설치

Android Studio 열기 → Tools → SDK Manager

SDK Tools 탭으로 전환합니다.

Gradle 바이너리 패키지 다운로드

공식 사이트 다운로드 링크 : https://gradle.org/releases/

압축 해제 경로 예시：C:\gradle\gradle-8.5

Gradle by Develocity | Releases

시스템 환경 변수 설정

변수명 : GRADLE_HOME
변수값 : C:\gradle-8.7

【시스템 변수】로 새로 생성합니다.

Path에 경로를 추가합니다.

정상 설치되었는지 검증합니다.

cmd 창을 엽니다.

gradle -v

다시 테스트했을 때 아래와 같은 결과가 표시되면 환경 설정이 완료된 것입니다.

D:\cordovademo\hello>cordova requirements

Requirements check results for android:
Java JDK: installed 11.0.31
Android SDK: installed true
Android target: not installed
No android targets (SDKs) installed!
Gradle: installed C:\gradle-8.7\bin\gradle.BAT
Some of requirements check failedCode language: CSS (css)

문제점2 JDK 버전

필자가 cordova run android 명령어를 실행하자 다음과 같은 오류가 발생했습니다.

D:\cordovademo\hello>cordova run android
Checking Java JDK and Android SDK versions
ANDROID_HOME=C:\Users\maiwu\AppData\Local\Android\Sdk (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)

BUILD SUCCESSFUL in 1sCUTING [91ms]
1 actionable task: 1 up-to-date
Subproject Path: CordovaLib
Subproject Path: app

[Incubating] Problems report is available at: file:///D:/cordovademo/hello/platforms/android/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* Where:
Build file 'D:\cordovademo\hello\platforms\android\app\build.gradle' line: 20

* What went wrong:
A problem occurred evaluating project ':app'.
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in C:\Program Files\Zulu\zulu-11
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.14.2/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD FAILED in 2s
Command failed with exit code 1: D:\cordovademo\hello\platforms\android\tools\gradlew.bat cdvBuildDebugCode language: JavaScript (javascript)

필자 환경에는 JDK11이 설치되어 있었지만, 현재 Cordova 안드로이드 플랫폼과 연동되는 AGP(Android Gradle Plugin)은 JDK17을 강제로 요구하기 때문에 빌드가 실패했습니다.

필자는 기존 Zulu JDK 11을 사용했기 때문에 Zulu JDK 17로 업그레이드했습니다.

아래 링크에서 다운로드할 수 있습니다. Java 8, 11, 17, 21, 25 Download for Linux, Windows and macOS

다운로드 받은 msi 파일을 실행한 뒤 아래 항목을 체크하고 설치하면 설치 프로그램이 자동으로 JAVA_HOME, Path 환경변수를 설정해줍니다.

CMD 창을 열어 자바 버전을 확인합니다.

java -version

openjdk version "17.0.20" 2026-07-21 LTS
OpenJDK Runtime Environment Zulu17.68+17-CA (build 17.0.20+8-LTS)
OpenJDK 64-Bit Server VM Zulu17.68+17-CA (build 17.0.20+8-LTS, mixed mode, sharing)Code language: CSS (css)

위 내용이 출력되면 정상 설치된 것입니다.

4. 앱 빌드하기

# 모든 플랫폼 빌드(현재 안드로이드만 추가된 상태)
cordova build

# 안드로이드만 빌드
cordova build android
Code language: PHP (php)

컴파일에 성공하면 APK 파일은 아래 경로에 생성됩니다.

hello\platforms\android\app\build\outputs\apk\debug\app-debug.apk

실행 로그 예시

D:\cordovademo\hello>cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=C:\Users\maiwu\AppData\Local\Android\Sdk (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)
Using Android SDK: C:\Users\maiwu\AppData\Local\Android\Sdk

BUILD SUCCESSFUL in 9s
1 actionable task: 1 up-to-date
Subproject Path: CordovaLib
Subproject Path: app

> Task :CordovaLib:compileDebugJavaWithJavac
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

[Incubating] Problems report is available at: file:///D:/cordovademo/hello/platforms/android/build/reports/problems/problems-report.html

BUILD SUCCESSFUL in 11s
50 actionable tasks: 50 executed
Built the following apk(s):
        D:\cordovademo\hello\platforms\android\app\build\outputs\apk\debug\app-debug.apkCode language: JavaScript (javascript)

경로 D:\cordovademo\hello\platforms\android\app\build\outputs\apk\debug\ 에서 APK 파일을 확인할 수 있습니다.

5. 테스트 실행하기

방식1 : 안드로이드 에뮬레이터로 실행

cordova emulate android

방식2 : USB 연결 실기기 테스트 (USB 디버깅 활성화 필요)

cordova run android

실기기로 테스트하는 방식을 추천합니다. 안드로이드 폰을 데이터 케이블로 연결하고 휴대폰에서 디버깅 모드를 켜주세요.

hello 폴더에서 cmd를 열고 cordova run android 명령어를 실행합니다.

명령 실행 후 휴대폰에 앱이 설치됩니다.

Cordova 기본 화면이 표시되는 것을 확인할 수 있습니다.

6. 플러그인 설치하기

휴대폰 네이티브 기능에 접근

Cordova 웹 페이지 자체만으로는 카메라, 블루투스, 파일, 알림 등 하드웨어 기능을 호출할 수 없으며, 반드시 플러그인을 설치해야 합니다.

예시: 카메라 플러그인

cordova plugin add cordova-plugin-camera

설치된 플러그인 조회

cordova plugin ls

JS로 네이티브 API를 호출하려면 반드시 deviceready 이벤트가 발생한 뒤 실행해야 합니다. 페이지 로딩 완료 직후에는 플러그인을 호출할 수 없습니다!

기본 템플릿 예시 (www/js/index.js)

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    // 기기가 준비되면 모든 Cordova 플러그인 사용 가능
    console.log("Cordova 초기화 완료");
}
Code language: JavaScript (javascript)

실행 로그 예시

D:\cordovademo\hello>cordova plugin add cordova-plugin-camera
Installing "cordova-plugin-camera" for android
Subproject Path: CordovaLib
Subproject Path: app
Adding cordova-plugin-camera to package.json

D:\cordovademo\hello>cordova plugin ls
cordova-plugin-camera 8.0.0 "Camera"Code language: CSS (css)

index.html을 아래 코드로 수정한 뒤 카메라 기능을 테스트해보겠습니다.

먼저 프로젝트 생성 후 폴더 구조를 설명하겠습니다.

D:\cordovademo\hello

앞으로 코드 작업은 www 폴더 안에서 진행합니다.

index.html을 아래와 같이 수정합니다.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Camera Test</title>
    <script src="cordova.js"></script>
</head>
<body>
    <button id="btnTake">사진 촬영</button>
    <br>
    <img id="imgPreview" style="width:220px;">

    <script>
        let cameraReady = false;

        document.addEventListener("deviceready", onDeviceReady, false);

        function onDeviceReady() {
            console.log("deviceready 발생, Cordova 준비 완료");
            cameraReady = true;
        }

        // addEventListener로 이벤트를 바인딩하는 것을 권장합니다. onclick 사용 시 타이밍 충돌이 발생할 수 있습니다.
        document.getElementById("btnTake").addEventListener("click", function(){
            if(!cameraReady){
                alert("Cordova 초기화를 기다려 주세요!");
                return;
            }

            navigator.camera.getPicture(
                function(imageUri) {
                    console.log("촬영 성공：", imageUri);
                    document.getElementById("imgPreview").src = imageUri;
                },
                function(error) {
                    alert("촬영 실패：" + error);
                },
                {
                    destinationType: 0, // Camera.DestinationType.FILE_URI = 0, Camera 객체 미정의 문제를 피하기 위해 숫자 사용
                    sourceType: 1,      // Camera.PictureSourceType.CAMERA = 1
                    quality: 80
                }
            );
        });
    </script>
</body>
</html>Code language: C# (cs)

다시 cordova run android 명령어를 실행합니다.

앱이 실행되고 화면에 버튼이 표시됩니다. 버튼을 클릭하면 카메라가 실행되고 사진을 촬영할 수 있습니다.

* 7. merges 폴더: 플랫폼별 개별 파일 관리

기본적으로 모든 플랫폼은 www 폴더의 리소스를 공유합니다.

안드로이드와 iOS에서 사용하는 화면 리소스를 다르게 적용하고 싶다면 merges 폴더를 활용하세요.

merges/
├─android/
│  └─css/overrides.css  # 안드로이드에서만 적용
└─ios/
Code language: PHP (php)

빌드 과정에서 merges 내 파일은 www 폴더의 동일 이름 파일을 덮어쓰기 합니다.

* 8. Cordova 업그레이드

# 전역 Cordova CLI 업그레이드
npm update -g cordova

# 특정 버전 설치
npm install -g cordova@12.0.0

# 프로젝트 내 안드로이드 플랫폼 버전 업데이트
cordova platform update android --save
Code language: PHP (php)

자주 사용하는 명령어 정리

#1 프로젝트 생성
cordova create testapp com.mytest.app TestApp
cd testapp

#2 안드로이드 플랫폼 추가
cordova platform add android

#3 환경 요구사항 검사
cordova requirements

#4 디버그 빌드
cordova build android

#5 실기기 실행
cordova run android
Code language: CSS (css)

첫 Cordova 프로젝트 만들기