在 Windows 和 Linux 上为 Android 实现 Capacitor Live Reload

Live reload 将缓慢的 build、sync、run 循环转变为“保存即查看”。在 Mac 上，Capacitor CLI 的 --live-reload flag 通常开箱即用。在 Windows 和 Linux 上，同样的 flag 也能工作，但防火墙、模拟器网络和 USB 路由是导致“无法重载”报告的主要原因。本指南将涵盖所有情况。

Live Reload 在 Capacitor 中的工作原理

原生应用通常从 dist/ APK 内部加载。通过设置 server.url 后，WebView 会改为从 URL 加载，也就是你的 Vite 或框架开发服务器。这样 HMR（热模块替换）的表现就和桌面浏览器完全一致。原生部分没有任何变化，只有页面的 origin 变了。

这会带来两个结果：

• 设备需要能通过网络访问你的电脑。
• 明文 http:// 需要 cleartext: true，因为 Android 默认会拦截明文流量。

方案 A：CLI 标志

Capacitor CLI 可以为单次运行完成这项设置：

bun run dev -- --host 0.0.0.0 &
bunx cap run android --live-reload --host 192.168.1.20 --port 5173

将 host 替换为你电脑的局域网 IP。CLI 会写入临时配置，启动应用，之后再恢复配置。如果你的开发服务器用了其他端口，也要把它传进去。

这是最快的方法。本指南后续部分将使用显式配置，这种方式更易于调试，且兼容任何 framework 的 dev server。

方案 B：显式配置

启动绑定到所有接口的 dev server：

# Vite
bun run dev -- --host 0.0.0.0
# Angular
bunx ng serve --host 0.0.0.0
# Next.js
bun run dev -- -H 0.0.0.0

然后创建一个仅限开发的 Capacitor 配置。Capacitor 会读取 capacitor.config.ts，因此请切换环境变量：

import type { CapacitorConfig } from '@capacitor/cli';

const liveReloadUrl = process.env.CAP_LIVE_RELOAD_URL;

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'my-app',
  webDir: 'dist',
  ...(liveReloadUrl
    ? { server: { url: liveReloadUrl, cleartext: true } }
    : {}),
};

export default config;

设置变量并运行：

CAP_LIVE_RELOAD_URL=http://10.0.2.2:5173 bunx cap sync android
bunx cap run android

在 Windows PowerShell 中：

$env:CAP_LIVE_RELOAD_URL="http://10.0.2.2:5173"; bunx cap sync android
bunx cap run android

如果不设置该变量， cap sync 将写入常规配置，且 release builds 是安全的。

模拟器：使用 10.0.2.2

在 Android emulator 中， 10.0.2.2 即你的电脑。它在 Windows 和 Linux 上无需更改任何防火墙设置即可工作，因为流量不会离开本机。如果仍然失败，请确认 dev server 已绑定到 0.0.0.0 而不只是 127.0.0.1；绑定到 loopback 的服务器无法通过模拟器的虚拟网络访问。

USB 手机：使用 adb reverse

对于真机来说，最简洁的方案无需 Wi-Fi，也无需配置防火墙规则：

adb reverse tcp:5173 tcp:5173

现在 localhost:5173 手机端指向你的电脑。请相应地设置 URL：

CAP_LIVE_RELOAD_URL=http://localhost:5173 bunx cap sync android

adb reverse 会在设备重新连接时清除，因此拔掉数据线后请重新运行。CLI 可以帮你完成： bunx cap run android --live-reload --host localhost --port 5173 --forwardPorts 5173:5173。Linux 用户需要从 Linux 设置指南 在……之前 adb 中获取 udev 规则，这样才能识别手机。

Wi-Fi 手机：局域网 IP 及防火墙设置

如果无法使用 USB，请使用电脑的局域网 IP 并开放端口。

查找 IP：

# Linux
ip -4 addr show | grep inet
# Windows
ipconfig

在 Windows 上开放端口。使用管理员权限运行 PowerShell：

netsh advfirewall firewall add rule name="Vite dev server" dir=in action=allow protocol=TCP localport=5173

在某些公司网络设置中，Windows 的“公用”网络配置文件即使配置了规则也会拦截传入连接；如果手机仍无法连接，请在设置中将 Wi-Fi 网络切换为“专用”。

在 Linux 上使用 ufw：

sudo ufw allow 5173/tcp

在 Fedora 上使用 firewalld：

sudo firewall-cmd --add-port=5173/tcp

然后：

CAP_LIVE_RELOAD_URL=http://192.168.1.20:5173 bunx cap sync android
bunx cap run android

两台设备必须处于同一子网。访客 Wi-Fi 网络通常会隔离客户端，这看起来非常像防火墙问题。

WSL2 特殊配置

当 Vite 在 WSL2 中运行时，Windows 宿主机不会自动暴露端口。请在以下设置中启用镜像网络 (mirrored networking)： .wslconfig 或者在 Windows 上添加端口代理。详情请参阅 WSL2 指南.

HMR websocket 问题

页面能加载但改动不生效？HMR websocket 连到了错误的 host。把公网地址告诉 Vite：

// vite.config.ts
export default defineConfig({
  server: {
    host: '0.0.0.0',
    hmr: {
      host: '192.168.1.20', // or 10.0.2.2 for the emulator
      port: 5173,
    },
  },
});

Angular 和 Next.js 也有对应选项；症状一样，解决办法都是固定 websocket host。

使用 Chrome DevTools 调试

打开 chrome://inspect 在电脑上的 Chrome 或 Edge 中操作。WebView 会显示在设备下方，并带有 dev server URL。无论在 Windows 还是 Linux 上，都能用 console、network、sources 和 breakpoints。如果设备没有出现，请检查 adb devices 并确认已接受 USB 调试。

切勿发布开发配置

包含以下内容的发布版本 build server.url 设置后，它会从不存在的机器加载，应用直接白屏。防范方法：

• 使用上面的环境变量写法，让默认配置里没有 server 代码块。
• 添加一个 CI 检查，如果构建产物 android/app/src/main/assets/capacitor.config.json 包含 "url".
• 如果你也使用 Capgo Live Updates，请注意， server.url 配置会覆盖更新器的 bundle；请让这两套工作流保持独立。

总结

在 Windows 和 Linux 上，只要三个细节正确，Android 的 Live reload 就能正常工作：将 dev server 绑定到所有接口，选择设备实际能访问的地址（10.0.2.2 模拟器用， adb reverse USB 用，Wi-Fi 用 LAN IP 并配置防火墙规则），并确保 dev 配置不进入 release builds。一旦 Android 上的迭代循环变快，共享的 web 层在通过后续流程到达 iOS 之前就已经测试过了。 Capgo 构建.