대부분의 Capacitor 문서는 Mac을 기준으로 작성되어 있습니다. Windows에서 개발하더라도 웹 레이어와 Android는 동일하게 작동하지만, PowerShell, 경로 길이, 에뮬레이터와 관련된 Windows 특유의 문제들이 발생할 수 있습니다. Windows에서 직접 컴파일할 수 없는 유일한 부분은 iOS이며, 해결책은 클라우드 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 --versionPowerShell 실행 정책 수정
bunx cap, npx cap 그리고 대부분의 CLI shim은 .ps1 스크립트입니다. 새로 설치한 Windows는 이를 차단합니다 running scripts is disabled on this system로컬 스크립트를 한 번 허용하세요:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned2) 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.AndroidStudioAndroid 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에서 코어 격리(메모리 무결성)가 이를 차단하고 있지 않은지 확인하세요.
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 pixel85) Windows USB 디버깅 설정
휴대전화에서 개발자 옵션과 USB 디버깅을 활성화하세요. 대부분의 최신 기기는 드라이버가 필요 없지만, adb devices 항목이 비어 있다면 SDK Manager(SDK Tools 탭)를 통해 Google USB 드라이버를 설치하거나, Samsung 기기의 경우 제조사 드라이버를 설치하세요.
adb devices처음 연결 시 휴대전화에 뜨는 지문 승인 프롬프트를 수락하세요.
6) Windows 전용 프로젝트 수정 사항
Windows에서 시간을 아껴주는 3가지 설정:
긴 경로(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가 동기화되는 Documents 폴더가 아닌, C:\dev\my-app다음과 같이 짧은 경로에 보관하세요.
줄 바꿈(Line endings). Gradle의 gradlew shell script는 LF 줄 바꿈을 유지해야 합니다. 그렇지 않으면 Linux CI가 깨집니다. 다음을 추가하세요 .gitattributes:
*.sh text eol=lf
gradlew text eol=lf7) 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 ioscap add ios Windows에서 실행하면 CocoaPods를 사용할 수 없다는 경고가 뜹니다. 이는 정상이며, ios/ 폴더는 여전히 생성되어 커밋되며, 클라우드 빌드는 pod install 나중에 실행됩니다.
에뮬레이터 또는 USB 기기에서 실행:
bunx cap run androidChrome에서 WebView 디버깅: chrome://inspect.
8) Android 릴리스 빌드
keytool -genkeypair -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
cd android
.\gradlew.bat bundleReleaseAAB는 다음 위치에 있습니다: 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 releasebuild init 서명 자료를 수집합니다. Windows에서는 Apple 포털에서 다음 절차에 따라 App Store Connect API 키를 수동으로 생성해야 합니다. iOS 빌드 가이드. 배포 인증서(distribution certificate)는 Keychain Access가 필요하지 않습니다. CSR을 생성하고 .p12 OpenSSL을 사용하여winget install ShiningLight.OpenSSL.Light) 또는 브라우저 기반의 iOS 인증서 생성기를 사용하세요. Capacitor 및 Capgo Build를 사용하여 Windows에서 iOS 앱 빌드하기.
단계별 가이드는 Capgo에 있습니다.
10) Native Build 없이 웹 변경 사항 배포하기
10) 재빌드 없이 웹 변경 사항 배포하기 Capgo Live Updates JavaScript, HTML, CSS 변경 사항의 경우:
bunx @capgo/cli@latest init
bun run build
bunx @capgo/cli@latest bundle upload --channel production플러그인, 권한 및 Capacitor 업그레이드 시에만 Native Build가 필요합니다.
Windows 주요 이슈
running scripts is disabled on this system: 실행 정책(execution policy). 1단계를 참조하세요.SDK location not found:ANDROID_HOMEGradle을 실행하는 터미널에 설정되지 않았습니다. 설정 후 터미널을 재시작하거나 새로 만드세요.android\local.properties포함sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.Filename too longGit 또는 Gradle에서: 긴 경로(long paths)를 활성화하세요. 6단계를 참조하세요.- 에뮬레이터 부팅 중 멈춤: 하이퍼바이저가 활성화되지 않았거나 BIOS 가상화가 꺼져 있습니다.
gradlew: bad interpreterCI 환경에서:gradlewCRLF 엔딩으로 커밋되었습니다. 다음 방법으로.gitattributes문제를 해결하고 다시 정규화하세요.EPERM또는 작업 중 파일이 잠겨 있습니다:bun installDefender 또는 실행 중인 Gradle daemon이 파일을 점유하고 있습니다. 다음 명령어로 daemon을 중지하고.\gradlew.bat --stop제외 항목을 추가하세요.
요약
Windows에서는 Android와 웹 레이어를 엔드 투 엔드로 지원합니다. iOS의 경우, 로컬에서 프로젝트를 생성 및 sync한 뒤 ios/ Capgo Build 폴더를 전달하세요. 여기에 Live Updates를 더하면, 사무실에 Mac이 한 대도 없어도 Windows 팀이 양대 스토어에 모두 배포할 수 있습니다. Windows에서 Linux shell을 선호한다면, 다음 가이드를 참고하세요: Capacitor 개발을 위한 WSL2 사용법.
