跳转至正文

在 Windows 上用 WSL2 开发 Capacitor

在 WSL2 中运行 Capacitor Web 工具链,同时把 Android 模拟器和设备留在 Windows 上:adb 桥接、镜像网络、文件系统性能、live reload,以及用 Capgo Build 构建 iOS。

Capacitor 在 Windows 上使用 WSL2 开发 Capgo 博客插图

WSL2 为 Windows 开发者提供了真正的 Linux shell,当团队的脚本、Dockerfile 和 CI 都默认用 bash 时,这一点很重要。对 Capacitor 来说,这套方案很好用,但有一个原则:把 web 工具链放在 WSL2,把 Android 模拟器、USB 设备和 Android Studio 留在 Windows,然后用 adb 把两者桥接起来。

本指南会介绍这套配置、容易踩坑的网络细节,以及 iOS 如何通过 Capgo 构建.

何时值得使用 WSL2

在以下场景使用 WSL2:

  • 你的仓库里有在 PowerShell 中无法正常运行的 bash 脚本、Makefile 或 Husky hooks。
  • 你在本地和 CI 中运行相同的 Docker 镜像。
  • 希望使用 Linux node_modules 目录结构,让 lockfiles 与 Linux CI 保持一致。

如果只需要 Android Studio 和终端,可以跳过 WSL2。此时, 原生 Windows 指南 会更简单。

1) 安装 WSL2 及发行版

在管理员权限的 PowerShell 中:

wsl --install -d Ubuntu

重启,打开 Ubuntu,创建你的 Linux 用户。更新并安装基础工具:

sudo apt update && sudo apt install -y build-essential unzip openjdk-21-jdk
curl -fsSL https://bun.sh/install | bash

2) 把项目放在 Linux 文件系统中

在 Linux home 目录下创建项目,而不是在 /mnt/c:

mkdir -p ~/dev && cd ~/dev
bun create vite@latest my-app
cd my-app
bun install

用 Windows 工具访问这些文件,可以通过 \\wsl$\Ubuntu\home\you\dev\my-app. 装了 WSL 扩展的 VS Code 可以直接通过 code ..

为什么这很重要:通过 /mnt/c 的跨文件系统访问,对于以下目录中成千上万个小文件来说很慢: node_modules,而且 Vite 使用的 inotify 监听器无法可靠地监听 Windows 驱动器上的文件变化。

3) 确定 Android SDK 的存放位置

两种可行的方案:

方案 A(推荐):SDK 在 Windows 上,WSL2 中的 Gradle 指向 Linux 上的 SDK 副本。 在 Windows 上安装 Android Studio 以使用模拟器和 GUI 工具,并在 WSL2 里另外安装一套命令行 SDK 供 Gradle 使用:

mkdir -p ~/Android/Sdk/cmdline-tools && cd ~/Android/Sdk/cmdline-tools
# download commandlinetools-linux-*.zip from the Android developer site
unzip commandlinetools-linux-*.zip && mv cmdline-tools latest
echo 'export ANDROID_HOME=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools' >> ~/.bashrc
source ~/.bashrc
sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0"
sdkmanager --licenses

是的,这会多复制几百 MB 的数据。作为交换,Gradle 以 Linux 速度运行,而且完全不会触碰 /mnt/c.

方案 B:所有内容都放在 Windows 上,WSL2 只用于 Web 构建。 你在 bun run build WSL2 中运行,并 cap sync 加 gradlew 通过 PowerShell 对同一批文件执行 \\wsl$。这种方式可行,但速度更慢,而且混用了两种 shell。只有在 WSL2 中无法安装任何东西时才选它。

本指南其余部分均假设采用方案 A。

4) 在 WSL2 与 Windows 之间桥接 adb

模拟器和 USB 手机连接在 Windows 上。WSL2 中的 Gradle 构建和 cap run android 需要访问它们。在 Windows 上只保留一个 adb server,并让 WSL2 作为客户端。

在 Windows 上,启动监听所有接口的 adb server。使用 Windows SDK 中的 adb:

adb kill-server
adb -a -P 5037 nodaemon server

让该窗口保持打开。如果弹出提示,请允许 5037 端口通过 Windows 防火墙供 WSL 虚拟适配器使用。

在 WSL2 中,将 adb 客户端指向 Windows 宿主机:

export WSL_HOST=$(ip route show default | awk '{print $3}')
export ADB_SERVER_SOCKET=tcp:$WSL_HOST:5037
adb devices

现在模拟器或手机会出现在 WSL2 中。两个 adb 二进制文件的主版本必须一致,因此请同时 platform-tools 更新两端。

镜像网络可简化此过程

在 Windows 11 22H2 或更高版本上,启用镜像网络,让 WSL2 共享 Windows 网络栈。创建或编辑 %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

运行 wsl --shutdown,重新打开 Ubuntu,然后使用 ADB_SERVER_SOCKET=tcp:127.0.0.1:5037。宿主机 IP 不再每次重启都变化,live reload 也更简单了。

备选方案:将 USB 设备直通到 WSL2

如果想让 adb 完全在 WSL2 里连接真机,请使用 usbipd-win:

winget install usbipd
usbipd list
usbipd bind --busid 2-3
usbipd attach --wsl --busid 2-3

然后添加来自以下位置的 udev 规则: Linux 指南 在 WSL2 内部。这对模拟器没有帮助,模拟器仍然走网络连接。

5) 运行应用

通过 adb 桥接后,Capacitor 就能像在 Linux 上一样工作:

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
bunx cap run android

cap open android 需要 Android Studio 在同一台机器上。改为打开 android/ Windows 版 Android Studio 中的文件夹,通过 \\wsl$\Ubuntu\home\you\dev\my-app\android。Studio 自带的 Gradle 随后会在 Windows 上构建,而你的终端在 WSL2 中构建;两者共用同一份源文件。

6) 跨边界实现 Live reload

Vite 运行在 WSL2 中,应用运行在 Windows 模拟器或手机上。模拟器必须能访问开发服务器。

启动 Vite 并绑定到所有接口:

bun run dev -- --host 0.0.0.0

在配置中将 Capacitor 指向该地址 capacitor.config.ts:

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  server: {
    url: 'http://10.0.2.2:5173',
    cleartext: true,
  },
};

10.0.2.2 这是模拟器指向宿主机的别名。启用镜像网络后,WSL2 的端口在 Windows 主机上可见,因此该地址可以访问 Vite。若未启用镜像网络,请先在 Windows 上转发端口:

netsh interface portproxy add v4tov4 listenport=5173 listenaddress=0.0.0.0 connectport=5173 connectaddress=$(wsl hostname -I)

对于 USB 连接的手机,请将 URL 替换为 Windows 局域网 IP,并在 Windows 防火墙中放行 5173 端口。运行 bunx cap sync android 修改配置后,并移除 server 该块,然后再进行 release build。

7) 在 WSL2 中用 Capgo Build 构建 iOS

Xcode 需要 macOS,所以 WSL2 负责到原生编译为止的所有工作,剩下的交给 Capgo:

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

CLI 会上传准备好的 ios/ 项目,并将日志流式传回你的 WSL2 终端。无需 Mac,签名材料可用 OpenSSL 或 iOS 证书生成器其他工具创建。详情请参阅 在 Linux 上用 Capacitor 和 Capgo Build 构建 iOS 应用,这同样适用于 WSL2。

8) 日常改动避免原生构建

两个应用都上架商店后, Capgo Live Update 从 WSL2 推送 Web 更改,无需碰 Gradle 或 Capgo Build:

bunx @capgo/cli@latest bundle upload --channel production

WSL2 常见问题

  • adb: device offline 或 WSL2 中列表为空:Windows adb 服务器未以该参数运行 -a,或版本不一致。重启后对比 adb version 两侧。
  • 重启后主机 IP 变了:未启用镜像网络时属正常。把 WSL_HOST export 写进 ~/.bashrc 以便重新计算,或切到镜像模式。
  • Vite 看不到文件更改:项目位于 /mnt/c。把它移到 Linux 主目录。
  • Gradle 极慢:原因相同,或者 Gradle 缓存位于 /mnt/c。保留 ~/.gradle 在 WSL2 中。
  • 时钟漂移会导致 Apple API 认证在以下过程中失败 build init:WSL2 休眠后时钟会漂移。运行 sudo hwclock -s 然后重试。
  • cap open android 失败时触发:Studio 在 Windows 上。请改为从 Studio 打开该文件夹。

总结

如果你的团队日常离不开 bash,WSL2 很适合承载 Capacitor Web 工具链。把模拟器和设备留在 Windows 上,用一个 adb server 把它们桥接起来,文件放在 Linux 文件系统里,iOS 编译交给 Capgo Build。这样就能在 Windows 笔记本上跑 Linux 工作流,同时仍能发布到两个应用商店。

为 Capacitor 应用提供 Live Updates

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

博客最新动态

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