Can I build a Capacitor app on Windows?

Yes. Windows runs the full web toolchain and the full Android toolchain, including Android Studio, the emulator and Gradle release builds. iOS compilation needs macOS, so Windows developers use a cloud macOS build such as Capgo Build to produce the signed IPA and submit to TestFlight.

Do I need WSL to develop Capacitor apps on Windows?

No. Native Windows with PowerShell or Windows Terminal works for Node, Bun, Gradle and Android Studio. WSL2 is optional and mostly useful if your team scripts assume a Linux shell. If you use WSL2, keep the Android emulator on the Windows side and bridge adb.

Can I build an iOS app on Windows?

Not locally. Xcode does not run on Windows. Generate the ios/ project with Capacitor, run cap sync, and send it to Capgo Build. It compiles and signs on macOS hardware in the cloud and can upload straight to TestFlight.

Why does bunx cap or npx cap fail with 'running scripts is disabled' on Windows?

PowerShell blocks .ps1 shims by default. Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, or use the .cmd shims by calling bunx.cmd or npx.cmd.

在 Windows 上进行 Capacitor 开发：完整配置指南

大多数 Capacitor 文档都是基于 Mac 环境编写的。如果你在 Windows 上开发，Web 层和 Android 的开发体验基本一致，但在 PowerShell、路径长度和模拟器方面会有一些 Windows 特有的坑。iOS 是 Windows 无法直接编译的部分，解决方案是使用云端 macOS 进行构建。

This guide is the complete Windows 11 setup, from a blank machine to an Android build on a device and an iOS build in TestFlight through Capgo 构建.

Windows 环境下的兼容性指南

任务	Windows
Web 开发、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 上的内核隔离（内存完整性）未拦截该功能。

在 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 Manager（SDK Tools 选项卡）安装 Google USB 驱动，或安装三星设备的厂商驱动。

adb devices

首次连接时，请在手机上接受指纹授权提示。

6) Windows 特有的项目修复

在 Windows 上节省数小时的三个设置：

长路径。 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"

将项目放在较短的路径下，例如 C:\dev\my-app，而不是 OneDrive 同步的“文档”文件夹下。

换行符。 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/ 文件夹仍会被生成并提交，随后云端 build 会 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 中并进行云端 build；详见 Capgo Android 端构建.

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 Build 指南。分发证书不需要使用 Keychain Access：只需创建 CSR 并 .p12 使用 OpenSSL (winget install ShiningLight.OpenSSL.Light) 或通过浏览器 iOS 证书生成器。详细步骤请参阅使用 Capacitor 和 Capgo Build 从 Windows 构建 iOS 应用.

构建完成后，Capgo 可以将其推送到 TestFlight，让你在几分钟内就能在真实的 iPhone 上安装。

10) 无需重新构建即可发布 Web 端变更

当两个应用商店都上线后，可以使用 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：执行策略。参见步骤 1。
SDK location not found: ANDROID_HOME 未在运行 Gradle 的终端中设置。设置后请重启终端，或创建 android\local.properties 配合 sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk.
Filename too long 通过 Git 或 Gradle：启用长路径，参见步骤 6。
模拟器卡在启动界面：未启用 hypervisor 或 BIOS 未开启虚拟化。
gradlew: bad interpreter 在 CI 中: gradlew 使用了 CRLF 换行符。请使用 .gitattributes 进行修复并重新规范化。
EPERM 或在过程中文件被锁定： bun install: Defender 或正在运行的 Gradle daemon 占用了文件。请使用 .\gradlew.bat --stop 停止 daemon 并添加排除项。

总结

Windows 可以端到端覆盖 Android 和 Web 层。对于 iOS，请在本地生成项目、同步，然后将 ios/ 文件夹交给 Capgo Build。配合 Live Updates 使用，你的 Windows 团队无需在办公室配备任何 Mac 即可向两大应用商店发布应用。如果你更喜欢在 Windows 上使用 Linux shell，请阅读关于使用 WSL2 进行 Capacitor 开发的配套指南.