Capacitor CLI를 사용한 빌드 스크립트 커스터마이즈 방법

Capacitor CLI를 사용하면 iOS, Android, 웹 플랫폼의 앱 빌드 프로세스를 커스텀할 수 있습니다. 빌드 스크립트를 조정하면 다음과 같은 작업이 가능합니다:

업데이트 속도 향상: 앱 스토어 심사 대기 없이 변경 사항을 즉시 반영할 수 있습니다.
배포 제어: 업데이트를 롤백하거나 특정 사용자 그룹을 대상으로 배포할 수 있습니다.
앱 보안 강화: 암호화를 사용하여 업데이트를 보호하세요.
빌드 최적화: 플랫폼별 요구 사항에 맞춰 설정을 조정하세요.

주요 기능 요약:

설정 파일: capacitor.config.json 및 package.json 빌드 설정을 관리합니다.
커스텀 스크립트: 자동화를 위한 prebuild 및 postbuild 작업을 추가하세요.
빌드 훅: 빌드 프로세스의 특정 단계에서 code를 실행합니다.
환경 변수: 다음을 통해 환경별 빌드 과정을 단순화하세요: .env 파일.

Capgo, 배포 도구로서 다음 기능을 통해 이 프로세스를 강화합니다: 자동 업데이트를 가능하게 합니다, 버전 추적 및 글로벌 성능 최적화를 지원합니다. 효율성을 극대화하기 위해 빌드 스크립트를 설정하고 커스텀하는 방법을 계속 알아보세요.

소개합니다: Capacitor 구성하세요:

Capacitor 프레임워크 문서 사이트

Capacitor의 기본 빌드 프로세스

효과적으로 커스터마이즈하려면 Capacitor가 기본 빌드 프로세스를 어떻게 처리하는지 이해하는 것이 중요합니다. 아래에서 Capacitor CLI의 빌드 프로세스와 주요 설정 파일을 자세히 살펴보겠습니다.

표준 빌드 단계

Capacitor는 단계별 프로세스로 웹 앱을 플랫폼별 빌드로 변환합니다. 기본 빌드 프로세스에서 일어나는 일은 다음과 같습니다:

단계	설명	결과물
웹 빌드	framework 도구로 웹 에셋 컴파일	최적화된 웹 bundle
에셋 복사	웹 에셋을 네이티브 플랫폼 폴더로 이동	플랫폼별 에셋 디렉토리
Native Build	플랫폼별 빌드 명령 실행	배포 가능한 바이너리
검증	빌드 무결성 및 의존성 확인	빌드 상태 및 경고

주요 설정 파일

Capacitor의 빌드 방식은 다음 두 가지 핵심 설정 파일에 의해 결정됩니다:

capacitor.config.json
Capacitor 프로젝트의 핵심 설정 파일입니다. 빌드에 필요한 주요 파라미터를 설정합니다:

{
  "appId": "com.example.app",
  "appName": "MyApp",
  "webDir": "dist",
  "bundledWebRuntime": false,
  "plugins": {
    "SplashScreen": {
      "launchShowDuration": 3000
    }
  }
}

appId: 앱의 고유 식별자입니다.
appName: 앱의 이름입니다.
webDir: Capacitor가 웹 에셋을 찾을 위치를 지정합니다 (예: dist).
plugins: SplashScreen 옵션과 같은 플러그인별 설정을 구성할 수 있습니다.

package.json
이 파일에는 빌드 프로세스에 영향을 미치는 빌드 스크립트와 의존성이 포함되어 있습니다:

{
  "scripts": {
    "build": "npm run build:web && cap sync",
    "build:web": "vite build",
    "cap:build": "cap build"
  }
}

이 webDir 설정 내 capacitor.config.json 는 Capacitor가 Native Build에 포함할 컴파일된 웹 에셋의 위치를 알려줍니다.
변경 사항을 적용한 후, capacitor.config.json를 실행해야 cap sync 하여 네이티브 프로젝트가 업데이트되었는지 확인할 수 있습니다.

다음으로, 빌드를 더욱 세밀하게 커스텀하기 위해 이러한 설정을 어떻게 수정할 수 있는지 알아보겠습니다.

Build Scripts 수정하기

Capacitor의 기본 빌드 프로세스를 프로젝트 요구 사항에 맞춰 조정할 수 있습니다. 방법은 다음과 같습니다.

설정 파일 옵션

다음 파일을 편집하여 빌드 프로세스를 조정할 수 있습니다. capacitor.config.json 아래는 설정 예시입니다.

{
  "appId": "com.example.app",
  "webDir": "www",
  "server": {
    "hostname": "localhost",
    "androidScheme": "https",
    "iosScheme": "https",
    "allowNavigation": ["*.example.com"]
  },
  "android": {
    "buildOptions": {
      "keystorePath": "release.keystore",
      "keystorePassword": "mypassword",
      "keystoreAlias": "release",
      "keystoreAliasPassword": "mypassword"
    }
  },
  "ios": {
    "scheme": "App",
    "automaticProvisioning": true
  }
}

수정 가능한 주요 설정은 다음과 같습니다.

webDir: 컴파일된 웹 에셋의 위치를 지정합니다.
server: 호스트 이름 및 네비게이션 권한을 포함한 개발 서버를 설정합니다.
android/ios: Android의 keystore 정보나 iOS의 provisioning 옵션 등 플랫폼별 빌드 설정을 지원합니다.

NPM 스크립트 생성하기

워크플로우를 간소화하려면 다음 항목에 커스텀 NPM 스크립트를 추가하세요. package.json 파일입니다. 예시는 다음과 같습니다:

{
  "scripts": {
    "prebuild": "node ./scripts/prepare-env.js",
    "build": "npm run build:web && cap sync",
    "build:web": "vite build",
    "build:ios": "cap build ios --release",
    "build:android": "cap build android --release",
    "postbuild": "node ./scripts/notify-completion.js"
  }
}

prebuild 및 postbuild: 환경 설정이나 빌드 완료 시 알림 전송과 같은 작업에 사용하세요.
build:platform: Android 또는 iOS 앱 빌드를 위한 플랫폼별 명령입니다.

빌드 훅(build hooks)을 추가하면 자동화 수준을 더 높일 수 있습니다.

빌드 훅 설정하기

더 세밀한 제어가 필요하다면 빌드 훅을 사용하여 빌드 프로세스의 특정 시점에 커스텀 code를 실행할 수 있습니다. 다음은 예시 설정입니다: capacitor.config.ts:

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

const config: CapacitorConfig = {
  appId: 'com.example.app',
  plugins: {
    CapacitorHooks: {
      beforeBuild: async () => {
        console.log('Running pre-build tasks...');
        // Add your pre-build tasks here
      },
      afterBuild: async () => {
        console.log('Running post-build tasks...');
        // Add your post-build tasks here
      }
    }
  }
};

export default config;

빌드 훅을 사용하면 다음과 같은 작업이 가능합니다:

빌드 시작 전 요구 사항 검증
프로세스 중 에셋 변환
주요 시점에 알림 트리거
버전 번호 자동 업데이트
자동화된 테스트를 원활하게 실행하세요

이 방식을 사용하면 전체 빌드 라이프사이클을 더욱 유연하고 정밀하게 제어할 수 있습니다.

고급 빌드 커스텀 설정

규모가 큰 프로젝트일수록 빌드 프로세스를 미세하게 조정하는 것이 매우 중요합니다. 환경별 빌드와 플랫폼별 커스텀을 효과적으로 처리하는 방법을 소개합니다.

환경 변수

각 환경에 맞는 별도의 파일을 생성하여 .env 환경 변수를 설정하세요:

.env.development
.env.staging
.env.production

그 다음, 환경에 따라 적절한 파일을 불러오도록 빌드 스크립트를 구성합니다:

import { defineConfig } from '@capacitor/cli';

export default defineConfig({
  ios: {
    buildConfig: {
      environment: process.env.BUILD_ENV || 'development',
      configurations: {
        development: {
          signing: {
            debug: true,
            automaticProvisioning: true
          }
        },
        production: {
          signing: {
            release: true,
            provisioningProfile: 'dist/profile.mobileprovision'
          }
        }
      }
    }
  }
});

플랫폼별 요구 사항에 맞춰 이 설정들을 더욱 세밀하게 조정할 수 있습니다.

플랫폼별 빌드

Android 및 iOS 빌드를 커스텀하려면 다음 구조를 사용하세요:

const platformConfig = {
  android: {
    buildType: process.env.BUILD_TYPE || 'debug',
    keystoreConfig: {
      path: process.env.KEYSTORE_PATH,
      password: process.env.KEYSTORE_PASSWORD,
      alias: process.env.KEYSTORE_ALIAS
    }
  },
  ios: {
    scheme: process.env.APP_SCHEME || 'App',
    xcodePreferences: {
      automaticSigning: false,
      developmentTeam: process.env.DEVELOPMENT_TEAM
    }
  }
};

이 설정을 통해 각 플랫폼에 최적화된 빌드를 구성하고, 더욱 원활한 배포를 보장할 수 있습니다.

기능	Android	iOS
디버그 심볼	ProGuard mapping 파일	dSYM 파일
빌드 변형(Build Variants)	디버그, 릴리스, 스테이징	디버그, 릴리스
Code 서명	Keystore 관리	Provisioning 프로파일
에셋 관리	res/drawable 최적화	에셋 카탈로그

빌드 최적화를 위한 추가 팁은 다음과 같습니다:

배포 시간을 단축하기 위한 partial updates 활용
빠른 이슈 파악을 위한 에러 트래킹 설정
베타 테스트 버전을 위한 채널 시스템 구축
안전한 배포를 위한 종단간 암호화 활성화

분석 및 보안 업데이트를 위해 Capgo와 같은 도구를 함께 사용하면 배포 프로세스를 더욱 정밀하게 제어할 수 있습니다. [1].

빌드 스크립트 문제 및 해결

커스텀 빌드 설정을 다룰 때는 빌드 프로세스를 원활하게 유지하기 위해 에러를 빠르게 해결하는 것이 매우 중요합니다.

흔한 오류 해결

많은 빌드 스크립트 문제는 환경 설정이나 의존성 문제에서 발생합니다. 흔히 발생하는 문제들의 해결 방법은 다음과 같습니다:

환경 변수 누락

다음과 같은 에러가 발생한다면:

error: Cannot find environment configuration for BUILD_ENV

프로젝트 루트 디렉토리에 .env.local 파일을 생성하여 해결할 수 있습니다. 예시는 다음과 같습니다:

BUILD_ENV=development
CAPACITOR_PLATFORM=ios
BUILD_TYPE=debug

플랫폼별 빌드 실패

Android 서명 에러의 경우, 다음 명령어를 사용하세요:

npx cap build android --keystorePassword=$KEYSTORE_PASSWORD --keystoreAlias=$KEYSTORE_ALIAS

iOS 프로비저닝 프로파일 문제의 경우, 다음을 시도해 보세요:

npx cap build ios --configuration=release --type=development

에러 유형	흔한 원인	솔루션
서명 설정	Keystore 정보 누락	설정 `KEYSTORE_PATH` 및 인증 정보
빌드 환경	정의되지 않은 변수	플랫폼별 생성 `.env` 파일 다운로드
의존성 확인	버전 불일치	업데이트 `package.json` 및 동기화

수정 사항을 적용한 후에는 철저한 빌드 테스트를 통해 변경 사항이 안정적인지 확인하세요.

빌드 스크립트 테스트

오류를 해결했다면 다음 단계에 따라 빌드 스크립트를 검증하세요:

자동 검증: 주요 명령어를 실행해 빌드 프로세스가 예상대로 작동하는지 확인하세요.

npm run build
npx cap sync
npx cap copy

환경 검증: 빌드를 시작하기 전에 누락된 환경 변수가 없는지 확인하세요.

const requiredVars = ['BUILD_ENV', 'KEYSTORE_PATH'];
requiredVars.forEach(varName => {
  if (!process.env[varName]) {
    throw new Error(`Missing required env var: ${varName}`);
  }
});

빌드 스크립트 디버깅: 빌드 중 발생할 수 있는 문제를 잡아낼 수 있도록 상세 스크립트를 추가하세요.

{
  "scripts": {
    "build:debug": "NODE_ENV=development npx cap build --verbose",
    "build:release": "NODE_ENV=production npx cap build --verbose"
  }
}

테스트를 위한 추가 팁:

사용 Docker 빌드를 격리하는 컨테이너.
프로세스 시작 전 설정 파일을 검증하세요.
여러 Node.js 버전으로 테스트하세요.
플랫폼별 요구 사항 충족 여부를 확인하세요.
빌드 성능을 모니터링하여 개선 사항을 찾아보세요.

Capgo 빌드 기능

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

Capgo는 자동화된 배포로 빌드 스크립트를 한 단계 끌어올려 효율성을 높이고 프로세스를 단순화합니다.

빠른 앱 업데이트

Capgo의 업데이트 성능은 놀랍습니다:

활성 사용자의 95% 24시간 이내에 업데이트를 수신합니다.
82%의 성공률 전 세계 어디든 업데이트를 전달합니다.
API의 평균 응답 시간은 전 세계 기준 434ms입니다.

이 플랫폼은 변경 사항만 다운로드하는 partial updates 방식을 사용합니다. 이 방식은 대역폭 사용량을 줄이고 업데이트 속도를 높여줍니다. 또한, 전체 빌드 프로세스가 완전히 자동화되어 시간과 노력을 절약할 수 있습니다.

빌드 자동화

Capgo는 주요 CI/CD 플랫폼과 원활하게 연동되며, 다양한 통합 옵션을 제공합니다:

CI/CD 플랫폼	통합 기능	장점
GitHub 작업	자동 빌드, 배포 트리거	지속적 배포
GitLab CI	파이프라인 자동화, 버전 관리	간소화된 워크플로우
Jenkins를	커스텀 워크플로우, 빌드 훅	엔터프라이즈급 확장성

자동 빌드 환경 구축 비용은 보통 월 $300 정도, 이는 비용이 많이 드는 기존 솔루션에 비해 훨씬 경제적입니다. 연간 약 $6,000를.

보안 표준

Capgo는 다음과 같은 강력한 프레임워크를 통해 보안을 최우선으로 합니다:

업데이트 패키지에 대한 종단간 암호화(E2EE).
안전한 키 관리.
Apple 및 Google 가이드라인 준수.

버전 관리 기능

즉각적인 롤백 옵션.
배포 버전 트래킹.
단계적 출시를 위한 업데이트 채널 관리.

이 보안 프레임워크는 수백 개의 엔터프라이즈 애플리케이션에서 엄격한 테스트를 거쳤습니다. 더 높은 수준의 보안이 필요한 팀을 위해 Capgo는 사용자 정의 설정이 가능한 self-hosted 솔루션도 제공합니다.

Capgo의 채널 시스템을 통해 업데이트 배포를 유연하게 관리할 수 있습니다. 개발자는 특정 사용자 그룹을 대상으로 서로 다른 버전을 배포할 수 있어, 베타 테스트나 단계적 롤아웃에 매우 적합합니다.

요약

빌드 단계 개요

커스텀 빌드 스크립트를 사용하면 빌드 훅, 환경 변수, 플랫폼별 명령어를 활용해 자동화되고 일관된 배포가 가능합니다. 이러한 프로세스는 Capgo를 통한 배포 개선의 견고한 기반이 됩니다.

Capgo의 장점

Capgo는 750개 이상의 프로덕션 앱에서 2,350만 건 이상의 업데이트를 성공적으로 전달하며 배포 과정을 간소화했습니다. [1]또한, 부분 업데이트(partial update) 시스템을 통해 대역폭 사용량과 배포 시간을 모두 줄여줍니다.

이 플랫폼은 빠른 업데이트, 글로벌 성능 최적화, 보안을 위한 종단간 암호화, 그리고 유연한 채널 기반 배포 시스템을 제공합니다. 이러한 구성은 강력한 보안 프레임워크를 유지하면서도 타겟 업데이트, 베타 테스트 및 앱 스토어 가이드라인 준수를 지원합니다.

Capacitor CLI로 빌드 스크립트 커스터마이징하는 방법부터 계속 보기

사용 중이라면 Capacitor CLI를 사용한 빌드 스크립트 커스터마이즈 방법 CI/CD 자동화를 계획하려면, 다음을 연결하세요 Capgo CI/CD 설정하기 Capgo CI/CD의 제품 워크플로우용, Capgo Native Build Capgo Native Builds의 제품 워크플로우용, Capgo 연동 서비스 Capgo Integrations의 제품 워크플로우용, CI/CD 통합 CI/CD Integration의 구현 세부 사항은, 그리고 GitHub Actions 연동 GitHub Actions Integration의 구현 세부 사항을 참고하세요.