대부분의 Capacitor 문서는 Mac을 기준으로 작성되어 있습니다. Windows에서 개발하는 경우 웹 레이어와 Android는 동일하게 작동하지만, PowerShell, 경로 길이, 에뮬레이터 관련 Windows 특유의 함정이 몇 가지 있습니다. iOS는 Windows에서 컴파일할 수 없는 유일한 부분이며, 이를 해결하려면 클라우드 macOS 빌드를 사용해야 합니다.
이 가이드는 빈 머신에서 시작해 실기기에서의 Android 빌드와 TestFlight에서의 iOS 빌드까지, Windows 11 설정 전 과정을 다룹니다. Capgo 빌드.
Windows에서 작동하는 것과 작동하지 않는 것
| 작업 | Windows |
|---|---|
| 웹 개발, Vite, 프레임워크 툴링 | 지원 |
cap add android, cap sync, Gradle 빌드 |
지원 |
| Android 에뮬레이터 | 네, Hyper-V 또는 WHPX 사용 시 |
| USB로 연결된 실물 Android 기기 | 지원 |
| Chrome DevTools 원격 디버깅 | 지원 |
cap add ios, cap sync ios (생성 및 복사) |
네, CocoaPods 경고가 함께 표시됩니다 |
| iOS 컴파일, 서명, 아카이브 | 아니요, macOS가 필요합니다. Capgo Build를 사용하세요 |
| iOS 시뮬레이터 | 아니요 |
| iOS WebView용 Safari Web Inspector | 아니요 |
1) Node 또는 Bun 설치
사용 winget PowerShell에서:
winget install OpenJS.NodeJS.LTS
# Or Bun
winget install Oven-sh.Bun
새 터미널을 열고 확인하세요:
node --version
bun --version
PowerShell 실행 정책 수정
bunx cap, npx cap 그리고 대부분의 CLI shim은 .ps1 스크립트입니다. 새로 설치한 Windows는 이를 차단합니다 running scripts is disabled on this system로컬 스크립트를 한 번 허용하세요:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
2) JDK 21 설치
Capacitor 7 및 8에는 JDK 21이 필요합니다. Android Studio에 자체 JBR이 포함되어 있지만, 터미널에서 Gradle을 실행할 때는 시스템 JDK를 쓰면 예상치 못한 문제를 피할 수 있습니다.
winget install Microsoft.OpenJDK.21
설정 JAVA_HOME 사용자 계정에 적용합니다. PowerShell에서:
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-21.0.8.9-hotspot", "User")
설치한 버전에 맞게 폴더 경로를 수정하세요. 그런 다음 터미널을 재시작하세요.
3) Android Studio 및 SDK 설치
winget install Google.AndroidStudio
Android Studio를 실행하고 설정 마법사에서 SDK 설치를 진행하도록 합니다 C:\Users\<you>\AppData\Local\Android\Sdk. 그런 다음 Gradle 및 Capacitor에서 사용하는 환경 변수를 설정하세요:
$sdk = "$env:LOCALAPPDATA\Android\Sdk"
[Environment]::SetEnvironmentVariable("ANDROID_HOME", $sdk, "User")
$path = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$path;$sdk\platform-tools;$sdk\emulator", "User")
Android Studio의 SDK Manager를 열고 Capacitor 버전에 맞는 플랫폼을 설치하세요: Capacitor 8에는 API 36, Capacitor 7에는 API 35.
4) 에뮬레이터 속도 높이기
에뮬레이터에는 하드웨어 가상화가 필요합니다. Windows 11에서는 에뮬레이터가 Windows Hypervisor Platform을 사용합니다. 활성화하려면:
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform
재부팅합니다. Android Studio의 Device Manager에서 여전히 가속 관련 경고가 표시되면, BIOS 또는 UEFI에서 가상화가 활성화되어 있는지, 그리고 구형 CPU에서 Core Isolation(Memory Integrity)이 이를 차단하지 않는지 확인하세요.
Device Manager에서 기기를 생성하거나 터미널에서:
sdkmanager "system-images;android-36;google_apis;x86_64"
avdmanager create avd -n pixel8 -k "system-images;android-36;google_apis;x86_64" -d pixel_8
emulator -avd pixel8
5) Windows에서 USB 디버깅
휴대폰에서 개발자 옵션과 USB 디버깅을 활성화하세요. 대부분의 휴대폰은 더 이상 드라이버가 필요하지 않지만, 만약 adb devices 이 비어 있다면, SDK 매니저(SDK Tools 탭)를 통해 Google USB 드라이버를 설치하거나 Samsung 기기의 경우 벤더 드라이버를 설치하세요.
adb devices
처음에는 휴대폰에서 지문 확인 프롬프트를 허용하세요.
6) Windows 전용 프로젝트 수정 사항
Windows에서 시간을 절약해 주는 세 가지 설정:
긴 경로(Long paths). Gradle 및 node_modules 은 260자 경로 제한을 초과할 수 있습니다. 한 번만 긴 경로 활성화:
git config --global core.longpaths true
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
두 번째 명령은 관리자 권한 PowerShell이 필요합니다.
Defender 예외 설정. 의 실시간 스캔 node_modules, Gradle 캐시 및 Android SDK 스캔은 빌드를 눈에 띄게 늦춥니다. Windows 보안에서 해당 폴더를 제외하거나, 관리자 권한 PowerShell에서 제외하세요:
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.gradle"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\Android\Sdk"
Add-MpPreference -ExclusionPath "C:\dev"
프로젝트는 OneDrive 동기화 문서 폴더가 아닌 C:\dev\my-app과 같은 짧은 경로에 두세요.
줄 끝 문자. Gradle의 gradlew shell script는 LF 줄 바꿈을 유지해야 합니다. 그렇지 않으면 Linux CI가 깨집니다. 다음을 추가하세요 .gitattributes:
*.sh text eol=lf
gradlew text eol=lf
7) Capacitor 프로젝트 생성
bun create vite@latest my-app
cd my-app
bun install
bun add @capacitor/core @capacitor/android @capacitor/ios
bun add -d @capacitor/cli
bunx cap init
bun run build
bunx cap add android
bunx cap add ios
cap add ios Windows에서 실행하면 CocoaPods를 사용할 수 없다는 경고가 뜹니다. 이는 정상이며, ios/ 폴더는 여전히 생성되어 커밋되며, 클라우드 빌드는 pod install 나중에 실행됩니다.
에뮬레이터 또는 USB 기기에서 실행:
bunx cap run android
Chrome에서 WebView 디버깅: chrome://inspect.
8) Android 릴리스 빌드
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
cd android
.\gradlew.bat bundleRelease
AAB는 다음 위치에 있습니다: android\app\build\outputs\bundle\release\. 팀이라면 keystore를 Capgo에 한 번 저장해 두고 클라우드에서 빌드하는 편이 좋습니다. 자세한 내용은 Android용 Capgo Build.
9) Windows에서 Capgo Build로 iOS 빌드
Xcode는 macOS 전용이므로 iOS 컴파일은 Capgo의 Mac 인프라에서 진행됩니다. Windows 터미널에서 실행하세요:
bun run build
bunx cap sync ios
bunx @capgo/cli@latest login
bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release
build init 서명 자료를 수집합니다. Windows에서는 Apple 포털에서 App Store Connect API 키를 수동으로 생성하며, 다음 절차를 따릅니다: iOS 빌드 가이드. 배포 인증서는 Keychain Access가 필요하지 않습니다. CSR을 생성하고 .p12 OpenSSL로 (winget install ShiningLight.OpenSSL.Light) 또는 브라우저 기반의 iOS 인증서 생성기. 단계별 가이드는 다음에서 확인하세요. Capacitor 및 Capgo Build를 사용하여 Windows에서 iOS 앱 빌드하기.
빌드가 끝나면 Capgo가 TestFlight로 푸시할 수 있어, 몇 분 후 실제 iPhone에 설치할 수 있습니다.
10) 재빌드 없이 웹 변경 사항 배포하기
양쪽 스토어가 모두 출시된 상태라면, 다음을 사용하세요: Capgo Live Update JavaScript, HTML 및 CSS 변경 사항에 대해:
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production
네이티브 리빌드는 플러그인, 권한 및 Capacitor 업그레이드 시에만 필요합니다.
Windows에서 흔히 발생하는 문제
running scripts is disabled on this system: 실행 정책. 1단계 참고.SDK location not found:ANDROID_HOMEGradle을 실행하는 터미널에 설정되지 않았습니다. 설정 후 터미널을 재시작하거나android\local.properties포함sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.Filename too longGit 또는 Gradle에서: 긴 경로 활성화, 6단계.- 에뮬레이터 부팅 시 멈춤: 하이퍼바이저가 비활성화되었거나 BIOS에서 가상화가 꺼져 있습니다.
gradlew: bad interpreterCI에서:gradlewCRLF 줄바꿈으로 커밋되었습니다. 다음으로 수정.gitattributes위 방법대로 수정하고 다시 정규화하세요.EPERM또는 잠긴 파일이 발생하는 동안bun install: Defender 또는 실행 중인 Gradle 데몬이 파일을 점유하는 경우입니다. 데몬을 중지하려면.\gradlew.bat --stop을(를) 실행하고 예외를 추가하세요.
요약
Windows는 Android와 웹 레이어를 끝에서 끝까지 지원합니다. iOS의 경우 프로젝트를 로컬에서 생성하고 동기화한 뒤 ios/ 폴더를 Capgo Build에 전달하세요. Live Update를 추가하면 Windows 팀은 사무실에 Mac이 하나도 없어도 두 스토어에 모두 배포할 수 있습니다. Windows에서 Linux 셸을 선호한다면 WSL2를 사용하여 Capacitor 개발하는 동반 가이드를 읽어보세요.