디렉터리 구조 - Cordova 튜토리얼

Cordova CLI로 생성한 프로젝트는 기본적으로 다음 디렉터리 구조를 갖습니다:

myapp/
├── config.xml
├── node_modules/
├── package.json
├── platforms/
├── plugins/
└── www

package.json

매니페스트 파일로 프로젝트에서 사용하는 JavaScript 패키지 의존성을 선언하며, Cordova, 추가된 플랫폼과 설치된 모든 플러그인 정보가 담깁니다. 플러그인 설정 변수 역시 이 파일에 저장됩니다.

프론트엔드 프레임워크로 생성된 자체 의존성 package.json이 프로젝트에 이미 존재할 수 있습니다. Cordova는 필요한 설정만 파일에 추가할 뿐 다른 도구와 기존 의존 정보를 건드리지 않습니다.

{
  "name": "com.foxdevelop.hello",
  "displayName": "HelloWorld",
  "version": "1.0.0",
  "description": "A sample Apache Cordova application that responds to the deviceready event.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "ecosystem:cordova"
  ],
  "author": "Apache Cordova Team",
  "license": "Apache-2.0",
  "devDependencies": {
    "cordova-android": "^15.1.0",
    "cordova-plugin-camera": "^8.0.0"
  },
  "cordova": {
    "platforms": [
      "android"
    ],
    "plugins": {
      "cordova-plugin-camera": {
        "ANDROIDX_CORE_VERSION": "1.6.+"
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

"name": "com.foxdevelop.hello" npm 패키지 이름. Cordova 프로젝트에서는 일반적으로 config.xml의 widget id와 일치시킵니다.

주의: 이 값은 Android/iOS 네이티브 패키지 이름이아닙니다. 네이티브 패키지 식별자는 여전히 config.xml의 id로 관리됩니다.

"displayName": "HelloWorld" 보기 쉬운 표시 이름으로 앱 이름에 해당하며 config.xml 내 <name>과 매칭됩니다.
"version": "1.0.0" 프로젝트 버전. 의미화 버전 규칙 주버전.부버전.수정버전을 따르며 config.xml 버전과 통일하는 것이 권장됩니다.
"description": "A sample Apache Cordova application that responds to the deviceready event." 프로젝트 설명 메타정보로 npm 페이지에 표시될 뿐 앱 빌드 및 실행에 영향을 주지 않습니다.
"main": "index.js" npm 규약 상 진입점 파일. Cordova는 이 필드를 거의 사용하지 않으며 템플릿 자동 생성 내용이므로 무시해도 무방합니다. Cordova 앱의 실제 웹 진입점은 www/index.html (config.xml로 제어)입니다.
"scripts": { "test": "echo \"Error: no test specified\" && exit 1" } npm 사용자 정의 스크립트. 기본 템플릿에는 test 명령만 존재하고 빌드, 패키지 단축 명령은 없습니다. 필요에 따라 직접 확장할 수 있습니다. 예시:

"scripts": {
  "build-android": "cordova build android"
}
Code language: JavaScript (javascript)

"keywords": ["ecosystem:cordova"] npm 검색 태그. ecosystem:cordova는 해당 프로젝트가 Cordova 생태계 프로젝트임을 표시하며 npm 검색에만 활용되고 실행에는 영향이 없습니다.
"author": "Apache Cordova Team" 작성자 정보로 단순 메타데이터입니다.
"license": "Apache-2.0" 오픈소스 라이선스 Apache 2.0. Cordova 공식 기본 라이선스입니다.

config.xml

Cordova 앱의 각종 환경설정 값을 담고 있으며 프로젝트 실행 동작을 커스터마이징할 때 사용합니다.

참고 문서: config.xml 공식 레퍼런스 매뉴얼

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.foxdevelop.hello" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>HelloWorld</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="https://cordova.apache.org">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
</widget>
Code language: HTML, XML (xml)

id="com.foxdevelop.hello"앱 고유 패키지 식별자 (Bundle ID)

Android: 앱 패키지명 applicationId
iOS: Bundle Identifier

스토어 등록 후 함부로 수정하면 안 됩니다. 수정 시 완전히 새로운 앱으로 인식됩니다. 명명 규칙: 역방향 도메인 회사도메인.프로젝트명

version="1.0.0" 앱 버전 번호 (의미화 버전 major.minor.patch). 빌드 결과물 앱 버전에 반영됩니다.

<name>HelloWorld</name>

앱 표시 이름으로 휴대폰 바탕화면 아이콘 아래에 보이는 이름입니다.

<description>

앱 설명 정보로 일부 플랫폼 빌드 과정과 앱 스토어 정보에서 읽어갑니다.

<author>

개발자 정보: 이메일, 공식 홈페이지, 작성자 이름. 메타데이터일 뿐 실행에 영향을 주지 않습니다.

<content src="index.html" />

가장 중요한 설정 항목

Cordova 앱이 실행될 때 최초 불러오는 메인 페이지입니다.

앱을 열면 웹 컨테이너가 바로 www/index.html을 로드합니다.

src="pages/home.html"로 수정하면 시작 페이지를 변경할 수 있습니다.

<allow-intent>

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
Code language: HTML, XML (xml)

역할: 앱에서 외부 브라우저를 호출해 웹페이지를 열 수 있도록 허용

allow-intent ≠ 웹뷰 내부 크로스도메인 접근 허용이 아닙니다!

두 설정은 매우 혼동하기 쉽습니다:

allow-intent: target="_blank" 링크 클릭 시 시스템 기본 브라우저로 이동하는 허용 규칙입니다. 현재 설정은 모든 http/https 주소에서 외부 브라우저 실행을 허용합니다.
access origin: 앱 내 웹뷰에서 외부 API 요청(크로스도메인)을 보낼 수 있는지 제어합니다. 이 설정 파일에는 해당 내용이누락되어 있습니다!

⚠️ 자주 발생하는 문제:

웹 페이지 AJAX 요청에서 크로스도메인 오류가 발생한다면 allow-intent만으로는 해결할 수 없으며 아래 설정을 추가해야 합니다.

xml

<!-- 웹뷰 내 모든 HTTPS 접근 허용 -->
<access origin="*" />Code language: HTML, XML (xml)

www/

HTML, CSS, JavaScript 및 각종 정적 리소스 파일 등 프로젝트 웹 자료를 저장하는 디렉터리입니다.

Cordova 개발자는 대부분의 업무 코드와 리소스를 이 폴더에 배치합니다. cordova prepare 명령 실행 후 이 폴더의 파일이 각 플랫폼 www 디렉터리로 복사됩니다.

소스 디렉터리 www는 각 플랫폼 하위 폴더로 동기화 복제됩니다. 예시 경로:

platforms/ios/www 또는 platforms/android/assets/www

CLI는 원본 www 폴더 내용으로 플랫폼 내 파일을 계속 덮어쓰므로, 루트 www 폴더의 파일만 수정하고 platforms 내 파일을 직접 변경하지 마세요.

프론트엔드 빌드 도구를 사용한다면 빌드 결과물 출력 경로를 www로 설정해야 합니다. www 폴더에서 직접 개발한다면 이 디렉터리를 버전 관리에 포함하는 것이 좋습니다.

node_modules/

npm 저장소에서 다운로드한 모든 JavaScript 의존 패키지가 위치합니다. Cordova, 관련 도구 및 package.json에 선언된 프로젝트 의존성이 포함됩니다.

cordova platform add, cordova plugin add로 플랫폼이나 플러그인을 추가할 때 필요한 자료가 npmjs에서 가져와 이곳에 저장됩니다.

그 뒤 Cordova가 이 디렉터리에서 플랫폼, 플러그인 소스 코드를 복사해 적절한 위치에 배치해 앱이 정상 작동하도록 합니다.

이 폴더에는 cordova prepare, cordova build로 각 플랫폼 빌드에 필요한 스크립트도 담겨 있습니다.

⚠️ 중요: node_modules는 의존 라이브러리 원본 폴더이므로 내부 파일을 직접 수정하면 안 됩니다. 또한 이 디렉터리를 버전 관리 시스템에 커밋하지 마세요.

자세한 내용은 npmjs 디렉터리 규격 문서를 참고하십시오.

platforms/

프로젝트에 추가한 각 플랫폼의 소스 코드와 빌드 스크립트를 보관합니다.

⚠️ 경고: CLI로 앱 빌드 시 원리를 충분히 이해했거나 공식 문서에 명시된 경우가 아니라면 /platforms/ 내 파일을 수정하지 마세요.

프로젝트 prepare 실행이나 플러그인 재설치 과정에서 이 폴더 파일들은 자주 덮어쓰기됩니다.

plugins/

플러그인 임시 중계 디렉터리로, 설치된 플러그인이 먼저 이곳에 복사된 뒤 각 플랫폼으로 배포됩니다.

이 디렉터리를 버전 관리에 포함하는 것은권장하지 않습니다.

직접 개발하거나 내부 커스터마이징, 수정한 플러그인은 plugins 폴더에 보관하지 마십시오.

버전 관리 규칙

platforms/, plugins/ 을 버전 관리에 넣지 않는 것을 권장합니다. 두 폴더는 빌드 산출물이기 때문입니다.

설치된 플랫폼과 플러그인 정보는 자동으로 package.json에 기록됩니다. cordova prepare 실행 시 프로그램이 자동으로 해당 플랫폼과 플러그인을 내려받습니다.

선택적 디렉터리

merges/

CLI로 Cordova 프로젝트 생성 시 기본적으로 merges 디렉터리가 생성되지 않습니다. 공식에서는사용을 권장하지 않지만 호환성 유지를 위해 기능을 남겨두고 있습니다.

이 폴더 하위 디렉터리에는플랫폼 전용 웹 리소스(HTML, CSS, JS)를 배치합니다. prepare 단계에서 각 네이티브 프로젝트로 배포됩니다.

merges/ 안에 위치한 파일은 해당 플랫폼에 한해 www 폴더의 동일 이름 파일을덮어씁니다.

디렉터리 구조 예시:

plaintext

myapp/
├── merges
│   ├── android/
│   │   └── android.js
│   └── ios/
│       └── app.js
└── www/
    └── app.js

Android, iOS 프로젝트 컴파일 후 결과:

Android 앱: app.js (www에서 가져옴) + android.js 포함
iOS 앱: app.js만 존재하며 merges/ios/app.js 파일이 www의 기본 app.js를 덮어쓴 상태

디렉터리 구조

Previous: 첫 Cordova 프로젝트 만들기