$q.capacitor

在 Capacitor 模式下，$q.capacitor 在 Vue 组件中提供 Capacitor 全局对象。在应用代码中，您也可以直接从 @capacitor/core 或已安装的 Capacitor 插件中导入所需的 API。

开发应用显示白屏

在 quasar dev -m capacitor 期间，原生应用从 Quasar 开发服务器加载 UI。所选的开发服务器地址必须能从模拟器或真机设备访问。

请检查：

• 设备和开发机器能够通过网络互相访问
• 选择的主机地址属于正确的网络接口
• 防火墙允许 Quasar 开发服务器端口的连接
• VPN、代理、访客 Wi-Fi 或客户端隔离设置没有阻止设备间通信
• 开发 URL 可以从设备的浏览器中打开

检查原生 WebView 控制台以获取确切的连接或证书错误。如果启用了 HTTPS，设备必须信任开发证书。

Android

远程调试

使用 Chrome 的 WebView 远程调试 来检查运行在 Android 设备或模拟器上的应用。在开发机器上开启 USB 调试并连接设备后，打开 chrome://inspect。

SDK 许可证和环境

使用以下命令接受 Android SDK 许可证：

sdkmanager --licenses

在当前版本的命令行工具中，sdkmanager 通常位于 $ANDROID_HOME/cmdline-tools/latest/bin。按照 准备工作 页面的说明，将 ANDROID_HOME 设置为 SDK 目录，并将该目录和 $ANDROID_HOME/platform-tools 添加到 PATH 中。

使用 adb devices 确认已连接的设备可见且已授权。在 Linux 上，请按照当前的 Android 硬件设备设置 说明配置 USB 权限，而不是使用通用的宽泛 udev 规则集。

原生工具链升级

不要自动接受 Android Studio 的升级建议。Gradle、Android Gradle Plugin、Java 和 SDK 的要求与 Capacitor 主版本绑定。在更改之前，请先遵循 Capacitor 的升级指南并提交原生项目。

如果 Android Studio 报告陈旧的索引或同步错误，首先重新运行配置的 Capacitor 同步命令。如果生成的项目是正确的但 IDE 状态仍然陈旧，可以尝试 File > Invalidate Caches。

iOS

远程调试

使用 Safari Web Inspector 检查运行在 iOS 设备或模拟器上的应用。在设备上启用 Web Inspector 并在 Safari 中启用"开发"菜单，然后从已连接的设备或模拟器中选择应用的 WebView。

CocoaPods 和原生依赖

如果 Capacitor 报告 CocoaPods 不可用或 Xcode 无法加载 Pods 配置文件，请使用适合您环境的方式安装 CocoaPods，然后在 /src-capacitor 目录中运行 pnpm exec cap sync ios。当存在 CocoaPods 依赖时，打开生成的 .xcworkspace 文件。

状态栏和安全区域

设备可能为状态栏、圆角、相机挖孔和 Home 指示条保留空间。Quasar 组件如 QHeader、QFooter 和 Notify 会处理常见的安全区域情况，但请在多种设备形态和方向上测试应用。

在 Android 上，Quasar 使用由 Capacitor 8 System Bars API 提供的 --safe-area-inset-* 变量，并回退到标准的 CSS 环境变量。如果你的应用自行处理 Android 安全区域，可以禁用 Quasar 的自动组件内边距：

framework: {
  config: {
    capacitor: {
      androidStatusBarPadding: false
    }
  }
}

对于自定义布局元素，使用相同的回退方式：

.top-element {
  padding-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
}

.bottom-element {
  padding-bottom: var(
    --safe-area-inset-bottom,
    env(safe-area-inset-bottom, 0px)
  );
}

具体使用 padding 还是 margin，取决于布局以及您是否想让背景延伸到安全区域中。