본문 바로가기
개발 모바일 업데이트

Capacitor CLI: 프로젝트 설정 가이드

몇 단계의 간단한 과정을 통해 웹 기술로 iOS 및 Android Native Build 앱을 구축하기 위한 Capacitor CLI 설정 방법을 알아보세요.

Martin Donadieu

Martin Donadieu

콘텐츠 마케터
Capacitor CLI: 프로젝트 설정 가이드

하나의 코드베이스로 iOS와 Android 앱을 만들고 싶으신가요? Capacitor CLI를 사용하면 웹 기술로 네이티브 앱을 만들 수 있어 프로세스가 훨씬 간편해집니다. 다음 내용을 학습하게 됩니다:

  • 빠른 설정: Capacitor CLI를 설치하고 몇 분 안에 프로젝트를 초기화하세요.
  • 플랫폼 통합: 간단한 명령어로 iOS 및 Android 지원을 추가하세요.
  • Live Update: Capgo 즉각적인 over-the-air 업데이트를 위해.
  • 자주 발생하는 문제 해결: sync 오류나 build 실패와 같은 문제를 해결합니다.

시작하기 위한 핵심 단계:

  1. 설치 Node.js, npm, JDK, Xcode, 그리고 Android Studio.
  2. 실행 npm install @capacitor/core @capacitor/cli 프로젝트를 초기화합니다.
  3. 다음 명령어로 iOS 및 Android 플랫폼을 추가하세요: npx cap add ios 및 npx cap add android.
  4. 선택 사항: 실시간 앱 업데이트를 위한 Capgo 설정 앱 업데이트.

이 가이드는 Capacitor CLI 설정부터 플랫폼 구성, 앱 배포까지 필요한 모든 과정을 다룹니다. 바로 시작해 보시죠!

소개합니다 Capacitor 구성

Capacitor 프레임워크 문서 사이트

설정 요구사항

시작하기 전에 다음 도구들이 설치되어 있는지 확인하세요:

  • Node.js (버전 14 이상) 및 npm
  • Java JDK (버전 11 이상)
  • Xcode (iOS 빌드를 위해 버전 12 이상 권장)
  • Android Studio (Android 빌드용)
  • Capacitor CLI를 (버전 6 또는 7)

선택 사항: Live Update를 활성화하려면 아래의 “Capgo 설정 가이드”를 확인하세요.

CLI 설치 단계

시작하기 전에 다음 항목이 설치되어 있는지 확인하세요: Node.js, npm, JDK, Xcode, 그리고 Android Studio 설정을 완료하세요. 준비가 되면 다음 명령어를 실행하여 Capacitor CLI를 설치할 수 있습니다:

npm install --save @capacitor/core @capacitor/cli
npx cap init

이 명령어를 통해 Capacitor를 설치하고 핵심 구성 요소를 설정합니다.

이 단계가 끝나면 다음으로 이동하여 새 프로젝트 생성 애플리케이션 스캐폴딩을 진행하세요.

새 프로젝트 생성

프로젝트를 시작하려면 Capacitor CLI를 사용하여다음 단계를 따르세요:

mkdir my-app && cd my-app
npm init -y
npx cap init my-app com.company.app --web-dir dist

설정 파일 업데이트

다음 설정을 포함하도록 capacitor.config.json 파일을 수정하세요:

{
  "appId": "com.company.app",
  "appName": "My App",
  "webDir": "dist",
  "bundledWebRuntime": false,
  "server": {
    "hostname": "app.example.com",
    "androidScheme": "https"
  }
}

업데이트가 완료되면, 이 설정을 사용하여 프로젝트에 Capacitor를 설정하세요.

플랫폼 설정

프로젝트 스캐폴딩이 완료되었으니, 이제 iOS 및 Android 타겟을 설정할 차례입니다.

iOS 및 Android 추가

Capacitor CLI를 사용하여 필요한 플랫폼별 패키지를 설치하는 것부터 시작하세요:

npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android

iOS의 경우 Xcode 14 이상이 필요하며, CocoaPods 1.11 이상, macOS 12 이상이 필요합니다. Android의 경우 Android Studio Giraffe (2022.3.1+), JDK 17 이상, 그리고 Gradle이 필요합니다. 7.5 이상 버전.

설치가 완료되면, 웹 애플리케이션의 변경 사항을 네이티브 타겟에도 계속 반영해 주어야 합니다.

플랫폼 업데이트

웹 앱 업데이트 후, 최신 웹 변경 사항을 플랫폼에 동기화하려면 다음 단계를 따르세요:

npm run build
npx cap sync

이 cap sync 이 명령은 두 가지 작업을 수행합니다:

  • 업데이트된 웹 에셋을 네이티브 플랫폼으로 복사
  • 최신 변경 사항에 맞춰 네이티브 설정 및 플러그인 업데이트

IDE 설정

각 플랫폼에 맞는 IDE에서 프로젝트를 여세요:

npx cap open ios     # Opens Xcode
npx cap open android # Opens Android Studio

Xcode에서:

  1. 개발 팀(Development Team)을 선택하세요.
  2. 서명 인증서를 설정합니다.
  3. Bundle Identifier를 업데이트합니다.

Android Studio에서:

  1. 다음 파일에서 Application ID를 수정합니다: build.gradle.
  2. 서명용 Keystore를 구성합니다.
  3. Debug 및 Release 빌드 변형을 모두 설정합니다.

모든 설정이 완료되면 다음 명령어로 프로젝트를 빌드합니다: npx cap build ios 또는 npx cap build android. 모든 에셋이 최신 상태인지 확인하려면 npx cap sync 를 다시 실행하는 것을 잊지 마세요.

Capgo 설정 가이드

Capgo Live Update 대시보드 인터페이스

앱에 즉각적인 over-the-air 업데이트를 적용하려면 Capgo를 설정하세요.

Capgo의 주요 기능

Capgo는 앱 업데이트를 간소화하는 다양한 도구를 제공합니다:

  • 종단 간 암호화 업데이트의 안전한 전달을 보장합니다.
  • 업데이트는 백그라운드에서 앱 실행 시 동작합니다.
  • 분석 도구를 통해 업데이트 성공률과 사용자 참여도를 추적할 수 있습니다.
  • 일치하는 원클릭 롤백 이 옵션을 사용하면 문제가 발생한 업데이트에서 빠르게 복구할 수 있습니다.
  • 다음을 사용하세요: 채널 시스템은 단계적 배포 및 베타 테스트용입니다.

Capgo 설치하기

Capgo 시작을 위해 다음 단계를 따르세요:

  1. Capgo CLI 설치:

    npm install --save @capgo/cli

  2. Capgo 초기화 프로젝트에서:

    npx capgo init

  3. 업데이트 빌드 및 배포:

    npm run build
npx capgo release

  4. 앱을 실행하여 백그라운드 업데이트 프로세스를 트리거하세요.

모범 사례

  • 채널을 활용해 모든 사용자에게 배포하기 전 업데이트를 미리 테스트하세요.
  • 분석 데이터를 모니터링하여 업데이트가 성공적으로 전달되는지, 사용자 참여도는 유지되는지 확인하세요.
  • 에러 트래킹을 활성화하여 문제를 조기에 발견하고 해결하세요.
  • 문제가 발생했을 때 즉시 대응할 수 있도록 롤백 기능을 준비해 두세요.

Capgo는 Capacitor 8과 호환되며, CI/CD 파이프라인과 원활하게 통합되고 Apple 및 Google 스토어 요구 사항을 준수합니다.

주요 이슈 및 팁

플랫폼 및 Capgo 설정을 마친 후 몇 가지 일반적인 에러가 발생할 수 있습니다. 해결 방법은 다음과 같습니다.

환경 설정 이슈

  • CLI를 찾을 수 없음 오류: 명령 npx cap 실패합니다. 해결: 실행 npm install --save @capacitor/cli @capacitor/core 그리고 다시 시도하세요.

  • Node 버전 불일치 오류: Node.js 버전 오류로 인해 CLI 명령어가 실패합니다. 해결: 설치 요구 사항에 따라 Node.js 버전 14 이상을 설치하세요.

설정 문제

  • 설정 불일치 오류: 변경 사항이 capacitor.config.json 적용되지 않습니다. 해결: 다음 사항을 확인하세요. appId 및 webDir 값이 프로젝트의 package.json 및 웹 빌드 출력 폴더와 일치하는지.

  • 플랫폼 동기화 오류 오류: 실행 시 npx cap sync 로 인해 플러그인 버전 충돌이 발생합니다. 해결: 업데이트 @capacitor/android 및 @capacitor/ios 동일한 메이저 버전으로 업데이트한 후, sync 명령어를 다시 실행하세요.

빌드 및 배포

  • 빌드 서명 실패 오류: 인증서 또는 keystore가 없어 iOS 또는 Android 빌드가 실패합니다. 해결: IDE 설정 지침을 따르세요. iOS의 경우 Xcode에서 개발 팀을 추가하고, Android의 경우 다음에서 keystore를 설정하세요. build.gradle.

  • 웹 디렉토리를 찾을 수 없음 오류: npx cap sync 웹 에셋을 찾을 수 없습니다. 해결: 플랫폼을 sync하기 전에 웹 build 명령어를 실행하세요 (예: npm run build)

Live Update 문제

  • Capgo 업데이트 실패 오류: 프로덕션 앱에 업데이트가 반영되지 않습니다. 해결: 다음을 다시 확인하세요: Capgo API 키 에서 capacitor.config.json 와 올바른 채널을 대상으로 하고 있는지 확인하세요.

플랫폼별 설정에 대한 자세한 내용은 플랫폼 설정 섹션을 다시 확인하세요. 라이브 업데이트를 사용 중이라면 Capgo Setup Guide에서 추가 문제 해결 팁을 확인하세요.

요약

설정 검토

Capacitor CLI로 웹 앱을 시작하고, iOS와 Android 플랫폼을 설정하세요. 라이브 업데이트를 위해 Capgo를 선택적으로 추가할 수 있습니다.

시작 방법은 다음과 같습니다:

  • Capacitor CLI를 사용하여 프로젝트를 초기화하세요.
  • 앱의 package ID를 설정하고 웹 출력 디렉터리를 정의하세요.
  • iOS 및 Android 플랫폼 지원을 추가하세요.
  • 다음 명령어로 Capgo를 설치하고 설정하세요: npm install --save @capgo/cli && npx capgo init

자세한 설정 방법이나 문제 해결 방법은 공식 Capacitor 및 Capgo 문서를 참고하세요.

다음 단계로 이동: Capacitor CLI: Project Setup Guide

사용 중인 경우 Capacitor CLI: 프로젝트 설정 가이드 대시보드와 API 운영을 계획하려면, 이를 다음 항목과 연결하세요: API 개요 API Overview의 구현 상세 내용은 소개 Introduction의 구현 상세 내용은 API 키 API Keys의 구현 상세 내용은 디바이스 Devices의 구현 상세 내용과 번들 Bundles의 구현 상세 내용은

Capacitor 앱을 위한 Live Updates

웹 레이어 버그가 라이브 상태일 때, 앱 스토어 승인을 며칠씩 기다리지 말고 Capgo를 통해 수정 사항을 배포하세요. 네이티브 변경 사항은 정상적인 리뷰 절차를 따르는 동안, 사용자는 백그라운드에서 업데이트를 받습니다.

블로그 최신 글

Capgo는 진정한 프로급 모바일 앱을 만드는 데 필요한 최고의 인사이트를 제공합니다.

Capacitor 앱의 양방향 통신
개발 모바일 +1
2025년 4월 26일

Capacitor 앱의 양방향 통신

피해야 할 흔한 OTA 업데이트 실수 5가지
개발 보안 +1
2025년 4월 13일

피해야 할 흔한 OTA 업데이트 실수 5가지

모바일 앱 Live Update를 위한 5가지 보안 베스트 프랙티스
개발 모바일 +1
2025년 1월 14일

모바일 앱 Live Update를 위한 5가지 보안 베스트 프랙티스

블로그 전체 보기