Capacitor는 웹앱을 어떻게 앱으로 바꿀까?

Capacitor는 Ionic 팀이 만든 오픈소스 도구로, 웹앱을 iOS·안드로이드 앱으로 바꿔 줍니다(github.com/ionic-team/capacitor, MIT 라이선스). 2019년 1.0이 나왔고, 2026년 10월 현재 최신 정식 버전은 8.5.3입니다.

 

웹을 앱으로 만드는 네 가지 방법 가운데 하이브리드에 속하는 대표 도구입니다. 이 글에서는 Capacitor가 앱 안에서 어떻게 작동하는지, 기존 웹 프로젝트에 어떻게 붙이는지, 휴대폰 기능은 어떻게 쓰는지, 시작하기 전에 무엇을 준비해야 하는지 차례로 정리합니다.

핵심 요약

• Capacitor는 웹앱을 앱 속 웹뷰에서 실행하고, 카메라·알림 같은 휴대폰 기능은 플러그인을 통해 네이티브 코드로 이어 줍니다.
• 기존 웹 프로젝트에 설치한 뒤 "웹 빌드 → npx cap sync → 기기 실행"을 반복하며 개발합니다.
• iOS·안드로이드 프로젝트를 내 저장소에 그대로 두고 직접 고칠 수 있다는 점이 예전 Cordova와 가장 큰 차이입니다.

Capacitor는 웹앱과 휴대폰 사이에 다리를 놓습니다

그림 1

Capacitor로 만든 앱을 열면, 화면은 앱 안의 웹뷰(앱 속에 들어 있는 브라우저 창)가 그립니다. React, Vue, Angular, Svelte 등 어떤 프레임워크로 만든 웹앱이든 빌드한 파일을 그대로 넣을 수 있습니다.

웹 코드가 카메라나 위치처럼 브라우저 밖의 기능을 쓰려고 하면 브리지가 나섭니다. 브리지는 JavaScript 함수 호출을 받아 iOS의 Swift 코드나 안드로이드의 Kotlin·Java 코드로 넘기고, 결과를 다시 JavaScript로 돌려주는 통역사 역할을 합니다. 웹 쪽에서 보면 평범한 비동기 함수를 부르는 것과 같습니다.

네이티브 프로젝트를 내 코드처럼 직접 관리합니다

Capacitor는 iOS·안드로이드 프로젝트를 빌드할 때마다 새로 만드는 결과물이 아니라 내 소스 코드로 취급합니다. ios와 android 폴더가 저장소에 남고, Xcode와 Android Studio로 열어 직접 고칠 수 있습니다. 앱 권한이나 아이콘 같은 설정도 각 플랫폼의 원래 설정 파일에서 바꿉니다.

이 점이 예전에 많이 쓰던 Cordova와 가장 큰 차이입니다. Cordova는 공통 설정 파일 하나로 네이티브 프로젝트를 매번 만들어 냈기 때문에, 네이티브 쪽을 손대기가 까다로웠습니다. Capacitor에서는 필요한 화면 하나만 네이티브로 만들거나 네이티브 개발자가 같은 프로젝트에서 함께 일할 수 있습니다. 또 Capacitor CLI는 전역이 아니라 프로젝트마다 설치되므로, 앱마다 다른 버전을 써도 충돌하지 않습니다.

기존 웹 프로젝트에 몇 줄만 더하면 시작할 수 있습니다

웹 프로젝트 폴더에서 Capacitor를 설치하고 초기화합니다. 초기화할 때 앱 이름과 앱 ID(예: com.example.app)를 묻습니다.

npm i @capacitor/core
npm i -D @capacitor/cli
npx cap init

설정은 capacitor.config.ts 한 파일에 모입니다. 가장 중요한 값은 webDir로, 웹 빌드 결과가 저장되는 폴더(Vite는 보통 dist)를 적어야 합니다.

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
};

export default config;

그다음 필요한 플랫폼을 추가합니다. 실행하면 프로젝트에 android, ios 폴더가 생깁니다.

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

개발은 빌드, 동기화, 실행을 반복합니다

그림 2

Capacitor 앱 개발은 네 단계를 반복합니다. 먼저 npm run build로 웹을 빌드하고, npx cap sync로 빌드한 파일을 네이티브 프로젝트에 복사하면서 플러그인도 설치합니다. 그다음 npx cap run android나 npx cap run ios로 에뮬레이터나 실제 휴대폰에서 실행합니다.

자주 하는 실수는 동기화를 빼먹는 것입니다. 웹 코드를 고치고 빌드만 하면 앱에는 예전 화면이 그대로 남습니다. 스토어에 올릴 때는 npx cap open android로 Android Studio를, npx cap open ios로 Xcode를 열어 빌드하거나, npx cap build android로 터미널에서 서명된 파일을 만듭니다.

휴대폰 기능은 플러그인으로 부릅니다

카메라, 파일, 위치, 푸시 알림, 공유, 진동 같은 기능은 Capacitor 팀이 만든 공식 플러그인으로 씁니다. 플러그인을 설치하고 동기화한 뒤 JavaScript에서 함수를 부르면 됩니다.

npm i @capacitor/camera
npx cap sync

import { Camera, CameraResultType } from '@capacitor/camera';

const photo = await Camera.getPhoto({ resultType: CameraResultType.Uri });

주의할 점은 권한 설정을 직접 해야 한다는 것입니다. Capacitor는 네이티브 설정 파일을 자동으로 고치지 않으므로, 카메라를 쓰려면 iOS의 Info.plist에 사용 목적 문구를, 안드로이드의 AndroidManifest.xml에 권한을 플러그인 문서대로 추가해야 합니다. 공식 플러그인에 없는 기능은 커뮤니티 플러그인이나 기존 Cordova 플러그인 상당수로 채울 수 있고, 그래도 없으면 Swift·Kotlin으로 직접 플러그인을 만들 수 있습니다.

앱 안에 데이터를 저장할 때도 위치를 잘 골라야 합니다. 웹뷰의 IndexedDB는 iOS에서 지워질 수 있으므로, 어떤 데이터를 어디에 두어야 하는지는 IndexedDB 글에서 따로 정리했습니다.

시작하기 전에 개발 환경부터 확인해야 합니다

Capacitor 8 기준으로 Node.js 22 이상이 필요합니다. 안드로이드 앱은 Android Studio(Otter 2025.2.1 이상)만 있으면 Windows, macOS, Linux 어디서나 만들 수 있고, 안드로이드 7.0(API 24) 이상에서 실행됩니다.

iOS는 조건이 더 까다롭습니다. iOS 앱을 빌드하려면 macOS와 Xcode 26 이상이 반드시 필요하고, 앱은 iOS 15 이상에서 실행됩니다. Capacitor 8부터는 iOS 라이브러리 관리 도구의 기본값이 CocoaPods에서 Swift Package Manager로 바뀌었습니다. 이전 버전 프로젝트는 npx cap migrate 명령으로 대부분 자동으로 올릴 수 있습니다.

구분	내용	시사점
작동 방식	웹뷰에서 웹앱 실행, 브리지와 플러그인으로 네이티브 기능 호출	웹 코드를 거의 그대로 앱에 쓸 수 있습니다
네이티브 프로젝트	ios, android 폴더를 저장소에서 직접 관리	필요한 부분만 네이티브로 고칠 수 있습니다
개발 흐름	웹 빌드 → npx cap sync → 기기 실행	웹 코드를 고칠 때마다 동기화가 필요합니다
기기 기능	공식·커뮤니티·Cordova 플러그인, 직접 만든 플러그인	권한 설정은 네이티브 파일에 직접 추가해야 합니다
개발 환경 (v8)	Node.js 22+, Android Studio, iOS는 macOS + Xcode 26+	iOS 앱을 내려면 Mac이 필요합니다

정리하며

Capacitor는 웹앱을 웹뷰에 넣고, 휴대폰 기능은 브리지와 플러그인으로 이어 주는 도구입니다. 웹 프로젝트에 설치하고 빌드와 동기화를 반복하는 것만으로 iOS·안드로이드 앱을 만들 수 있고, 네이티브 프로젝트를 직접 관리하므로 나중에 필요한 부분만 네이티브로 옮기기도 쉽습니다.

이미 웹앱이 있고 앱스토어에도 올리고 싶다면 가장 먼저 검토해 볼 만한 선택지입니다. 다만 애플은 웹사이트를 감싸기만 한 앱을 심사에서 거절할 수 있으므로, 푸시 알림이나 오프라인 사용처럼 앱에서만 할 수 있는 기능을 함께 넣는 것이 좋습니다.

Capacitor 말고 다른 방법과 비교하고 싶다면 웹사이트를 앱으로 만드는 네 가지 방법을, 반대로 네이티브 앱을 중심에 두고 웹을 함께 제공하는 방법은 네이티브 앱과 웹서비스를 함께 운영하는 글을 참고하세요.

원본: Capacitor · Ionic 팀 · MIT 라이선스 · github.com/ionic-team/capacitor. 버전과 개발 환경 요구 사항은 2026년 10월 26일 기준 npm 배포 정보와 공식 문서를 바탕으로 정리했습니다.

한마디로 정리하면

Capacitor는 해외여행용 전원 어댑터와 비슷합니다. 웹앱은 한국에서 쓰던 전자제품이고, 휴대폰은 콘센트 모양이 다른 외국입니다.

어댑터를 끼우면 전자제품을 고치지 않고도 외국 콘센트에서 그대로 쓸 수 있습니다. Capacitor도 웹앱을 고치지 않고 휴대폰 앱으로 돌아가게 해 줍니다. 카메라나 알림처럼 특별한 전원이 필요한 기기는 용도별 플러그(플러그인)를 하나씩 더 꽂아 씁니다.

다만 어댑터를 꽂았다고 해서 전기를 쓸 수 있는 허락까지 저절로 받는 것은 아닙니다. 권한 설정은 직접 해야 하고, 웹 코드를 고치면 동기화로 새 제품을 다시 꽂아야 합니다. 가진 제품을 그대로 들고 새 나라에 가고 싶다면, 가장 먼저 챙길 어댑터가 Capacitor입니다.