大多数 Capacitor 文档默认使用 Mac。如果你在 Windows 上开发,Web 层和 Android 的工作方式相同,但 PowerShell、路径长度和模拟器有一些 Windows 特有的坑。iOS 是 Windows 无法编译的部分,解决方案是使用云端 macOS 构建。
本指南涵盖完整的 Windows 11 环境搭建,从空白机器到在设备上构建 Android 应用,再到在 TestFlight 中构建 iOS 应用 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 中是否已启用虚拟化,以及 Core Isolation(内存完整性)是否在较旧的 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 管理器(SDK 工具选项卡)安装 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 脚本必须保留 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 中并在云端构建;参见 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 上,App Store Connect API 密钥需在 Apple 门户中手动创建,按照 iOS Build 指南。分发证书无需 Keychain Access:创建 CSR 并 .p12 使用 OpenSSL(winget install ShiningLight.OpenSSL.Light)或基于浏览器的 iOS 证书生成器。详细步骤见 在 Windows 上使用 Capacitor 和 Capgo Build 构建 iOS 应用.
构建完成后,Capgo 可将其推送到 TestFlight,几分钟后即可在真机 iPhone 上安装。
10) 无需重新构建即可发布 Web 端变更
两个商店都上线后,使用 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_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 守护进程占用了文件。使用.\gradlew.bat --stop停止守护进程并添加排除项。
总结
Windows 可端到端覆盖 Android 和 Web 层。对于 iOS,请在本地生成项目、同步,然后将 ios/ 文件夹到 Capgo Build。再叠加 Live Updates,你的 Windows 团队就能把应用发布到两个商店,办公室里一台 Mac 都不用。如果你更喜欢在 Windows 上用 Linux shell,请阅读配套指南: 使用 WSL2 进行 Capacitor 开发.