跳转至正文

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

在 Windows 11 上配置 Capacitor:Node 或 Bun、JDK 21、Android Studio 和模拟器、USB 调试、PowerShell 修复、长路径问题,以及用 Capgo Build 在没有 Mac 的情况下构建 iOS。

Capacitor Windows 开发环境搭建指南 Capgo 博客插图

大多数 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 开发.

为 Capacitor 应用提供 Live Updates

当 Web 层出现线上 Bug 时,通过 Capgo 发布修复,而不用等 App Store 审核好几天。用户会在后台收到更新,原生变更则仍走正常审核流程。

博客最新动态

Capgo 为你提供打造真正专业的移动应用所需的最有价值的洞察。