Quasar 混合移动应用开发指南:深入理解 Apache Cordova 集成与实战配置
Quasar 混合移动应用开发指南:深入理解 Apache Cordova 集成与实战配置
Quasar Framework 通过 @quasar/app-vite 为开发者提供了一条快速构建混合移动应用(hybrid mobile app)的路径,其核心支撑正是 Apache Cordova。本篇指南以 Cordova 模式(-m cordova)为主线,系统讲解 Cordova 混合应用的本质、环境准备、Quasar 与 Cordova 的集成原理、config.xml 与 quasar.config 的配置要点,以及通过 Cordova 插件调用原生设备 API 的完整实战流程。读完本文,你将能够独立完成 Cordova 模式下的项目初始化、开发调试、构建打包与插件集成。
Cordova 是什么:混合应用的基石
Apache Cordova 是一个移动应用开发框架,最初由 Nitobi 创建,2011 年被 Adobe Systems 收购并重新命名为 PhoneGap,随后 Adobe 将软件的开放源代码版本以 Apache Cordova 的名义发布。它允许软件开发者使用 CSS3、HTML5 和 JavaScript 构建移动设备应用,而无需依赖 Android、iOS 或 Windows Phone 等平台特定的原生 API。
Cordova 的工作方式是根据目标设备平台,将 CSS、HTML 和 JavaScript 代码进行"包装"(wrapping),并扩展 HTML 和 JavaScript 的能力使其能够与设备硬件交互。最终生成的应用属于混合应用(hybrid app),它有两个显著特征:
- 既不是真正的原生应用:所有界面布局渲染都通过 Web 视图(Web view)完成,而不是使用平台的原生 UI 框架;
- 也不是纯 Web 应用:它被打包为可分发的应用(如
.apk、.ipa),并且可以访问原生设备 API。
借助 Cordova 插件(Cordova Plugins),开发者可以接入相机、电池状态、联系人、地理位置、设备信息、振动、状态栏等原生设备能力,相关实战方法见后续章节。
环境准备:搭建 Cordova 开发工具链
在开始开发 Quasar 混合应用之前,需要先完成 Cordova CLI、Android 与 iOS 工具链的安装配置。
安装 Cordova CLI
Quasar 会直接调用 cordova 可执行文件,因此需要全局安装 Cordova CLI,可以使用你选定的任意 Node 包管理器:
# PNPM
pnpm add -g cordova
# Yarn
yarn global add cordova
# NPM
npm i -g cordova
# Bun
bun install -g cordova
安装完成后验证版本:
cordova --version
Android 环境配置
安装 Android Studio 以及项目内 cordova-android 版本所要求的 Android SDK 组件。Cordova 官方的 Android 平台指南列出了兼容的 Java、Gradle、Android Gradle Plugin、SDK 与 build-tools 版本组合,务必按版本对应关系安装。
设置 ANDROID_HOME 环境变量指向 Android SDK 位置,并将命令行工具与 platform-tools 加入 PATH:
export ANDROID_HOME="$HOME/Android/Sdk"
export PATH="$PATH:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools"
不同系统下 SDK 的默认位置不同:macOS 通常在 $HOME/Library/Android/sdk,Windows 通常在 %LOCALAPPDATA%\Android\Sdk。
[!TIP]
ANDROID_SDK_ROOT已被弃用。如果较老的工具仍然需要它,可将其设置为与ANDROID_HOME相同的位置。
接受已安装 SDK 的许可证并验证工具链:
sdkmanager --licenses
cordova requirements android
iOS 环境配置
iOS 开发需要 macOS 与兼容的 Xcode 安装。首次需要打开一次 Xcode 以完成组件安装并接受其许可证。请查阅 Cordova iOS 平台指南,确认已安装的 cordova-ios 版本对应的系统要求。
添加 Cordova 模式
在 Quasar 项目中添加 Cordova 项目(生成到 /src-cordova 目录):
quasar mode add cordova
# 或者跳过 app id 交互提示(适用于脚本/CI 场景):
quasar mode add cordova --app-id org.cordova.quasar.app
在非交互环境(如 CI)中无法回答提示时,除非显式指定 --app-id 参数,否则 app id 默认取 org.cordova.quasar.app。从源码看,这个默认值定义在 cordova-installation.js 的 defaultAppId 常量中,同时该文件还展示了模式安装的完整流程:校验 package.json 的 productName(不能以数字开头)、通过 cordova create src-cordova <appId> <appName> 创建原生工程、并重置 /src-cordova/www 占位内容。
Quasar 会在你首次针对某目标平台执行开发或构建命令时,按需自动安装 Android 或 iOS 平台;也可以手动添加:
cd src-cordova
cordova platform add [android|ios]
请将 /src-cordova 视为一个原生 Cordova 项目来对待,对配置、插件、资源或原生代码的预期改动都应提交到版本控制。需要特别注意的是,/src-cordova/www 目录是由 Quasar 构建生成并覆盖的,不要直接编辑其中的内容(模板文件 app-vite/templates/cordova/www/index.html 中的占位页明确标注了 "This file will be auto-generated. Do not edit.")。
启动开发
quasar dev -m cordova -T [android|ios]
Quasar 会启动开发服务器、准备原生项目,并自动打开 Android Studio 或 Xcode。从 IDE 中选择模拟器、模拟器(simulator)或已连接的设备即可运行。
[!WARNING] 不要自动接受原生工具链的升级建议。首先确认建议的 Java、Gradle、Android 或 Xcode 版本与已安装的 Cordova 平台版本兼容。
理解 Quasar 与 Cordova 的集成原理
从源码层面看,Cordova 模式在 @quasar/app-vite 中由 app-vite/lib/modes/cordova 目录下的模块支撑,其中几个核心模块值得关注:
- cordova-installation.js:负责
quasar mode add cordova时的模式安装、平台添加与www目录重置; - cordova-devserver.js:负责
quasar dev时启动 Vite 开发服务器、执行cordova prepare <target>并调用openIDE打开 Android Studio / Xcode; - cordova-builder.js:负责
quasar build时先用 Vite 构建 UI,再执行cordova build并回拷构建产物到/dist; - cordova-config.js:生成 Cordova 模式下的 Vite 配置,开发时注入平台注入插件,生产时把输出目录指向
src-cordova/www; - config-file.js:在每次构建/开发前动态改写
config.xml; - android-cleartext.js:开发模式下为 Android 清单临时开启明文流量(cleartext traffic)支持。
开发模式:Vite + cordova prepare 的双进程协同
quasar dev -m cordova 的核心流程记录在 cordova-devserver.js 中:
- 构造函数中为 Android 目标调用
fixAndroidCleartext(appPaths, 'add'),临时在platforms/android/app/src/main/AndroidManifest.xml的<application>标签上注入android:usesCleartextTraffic="true",以便真机/模拟器访问本机开发服务器(HTTP 明文)流量; - 注册运行步骤:先
#runVite启动 Vite 开发服务器,再#runCordova执行cordova prepare <target>(将 Web 资源同步进原生工程),随后调用openIDE打开对应 IDE; - 进程关闭时通过
onShutdown回调停止 Cordova 进程并执行#cleanup,还原被改写的配置。
开发模式下 Cordova 平台注入插件(vite-plugin.dev.cordova-platform-inject.js)负责处理 cordova.js 的注入逻辑;而在生产构建时,cordova-builder.js 会在 Vite 构建完成后,把 <script src="cordova.js"></script> 直接注入到 index.html 的 <head> 中——源码注释解释了这样做的原因:避免 Vite 因无法打包无 type="module" 属性的脚本标签而报警告。
构建模式:cordova build 与产物回拷
quasar build -m cordova 的流程记录在 cordova-builder.js 中:
- 先用 Vite 构建 UI(产物输出到
/src-cordova/www,见 cordova-config.js 中的cfg.build.outDir = appPaths.resolve.cordova('www')); - 为 Android 目标移除开发期注入的 cleartext 标记;
- 调用
getCordovaBuildOutputFolder(或使用内置默认值)确定产物目录,并清空旧产物; - 执行
cordova build [--debug|--release] --device <target>(默认参数); - 将 Cordova 构建产物从
platforms/...复制到项目/dist/<target>目录。
内置的默认输出目录(cordovaOutputFolders)覆盖了 iOS 7+ 与旧版的多种布局:platforms/ios/build/Release-iphoneos、Debug-iphoneos、Release-iphonesimulator、Debug-iphonesimulator、platforms/ios/build/device、platforms/ios/build/emulator,以及 Android 的 platforms/android/app/build/outputs。如果没有找到任何输出目录,构建会给出警告并提示需要手动提取 Cordova 分发包。
核心配置文件一:/src-cordova/config.xml
对移动应用而言最重要的配置文件是 /src-cordova/config.xml。/src-cordova 本身就是一个完整的 Cordova 项目,其中各文件的含义应参考 Cordova 官方文档;但需要特别留意,config.xml 中的部分属性会被 Quasar 在构建前覆盖。
Quasar 在每次构建/开发前都会通过 config-file.js 中的 CordovaConfigFile.prepare() 动态改写 config.xml,具体动作包括:
- 将根节点的
version更新为quasar.config > cordova > version或package.json > version; - 若有配置则设置
android-versionCode属性; - 更新
<content>的src指向开发服务器地址(开发模式),生产模式恢复为index.html; - 为开发服务器地址与
about:*注入<allow-navigation>白名单(后者用于QResizeObserver,直到所有平台支持原生ResizeObserverWeb API); - 当 iOS 使用 HTTPS 开发服务器时,还会临时修改
AppDelegate.m与 WKWebView 引擎的 Objective-C 源码以放行自签名 SSL 证书(reset()时会恢复原文件)。
核心配置文件二:quasar.config 中的 cordova 配置
quasar.config 文件中的 cordova 对象用于控制版本信息与构建行为。Quasar CLI 会在 Cordova 运行前更新 config.xml 中的应用版本(version)、描述(description)以及可选的 Android version code。widget id 在 Cordova 项目创建时设定,不会被 Quasar 配置重写。
取值规则如下:
- 首先查找
/quasar.config文件中的cordova对象,看是否包含version、description和/或androidVersionCode,有则采用; - 否则回退到
/package.json > version和/package.json > description。
cordova 配置对象完整定义如下(TypeScript 注释即官方语义):
cordova: {
/** If not present, will look for `package.json > version` */
version?: string;
/** If not present, will look for `package.json > description` */
description?: string;
androidVersionCode?: string;
/**
* Function to return the Cordova build command parameters that
* will be executed after the UI has compiled.
*
* @param context.debug - True if in debug mode
* @param context.target - The target platform
* @returns Array of strings (command parameters)
*
* @default: [ 'build', '--debug'/'--release', '--device', 'ios'/'android' ]
* @example: ({ debug, target }) => [ 'build', `--${debug ? 'debug' : 'release'}`, '--device', target ]
*/
getCordovaBuildParams?: (context: { debug: boolean; target: string }) => string[];
/**
* Function to return the Cordova output folder after the "cordova build"
* command is executed.
* The relative to /src-cordova path is used to copy the Cordova output
* to the /dist folder.
*
* @param context.debug - True if in debug mode
* @param context.target - The target platform
* @returns string | string[] | undefined - (relative path(s) from /src-cordova)
*
* @default ios: platforms/ios/build/... and android: platforms/android/app/build/outputs
* @example:
* ({ debug, target }) => {
* return target === 'ios'
* ? `platforms/ios/build/${debug ? 'Debug' : 'Release'}-iphoneos`
* : 'platforms/android/app/build/outputs'
* }
* @example: (when interested in only one platform, leaving the other to the default value)
* ({ debug, target }) => {
* if (target === 'ios') {
* return `platforms/ios/build/${debug ? 'Debug' : 'Release'}-iphoneos`
* }
* }
* @example: ()
* ({ debug, target }) => {
* if (target === 'ios') {
* // try these two folders
* return [ 'platforms/ios/build/device', 'platforms/ios/build/emulator' ]
* }
* }
*/
getCordovaBuildOutputFolder?: (context: { debug: boolean; target: string }) => string | string[] | undefined;
}
getCordovaBuildParams 允许你在 UI 编译完成后自定义传给 cordova 的构建参数(默认 ['build', '--debug'|'--release', '--device', target]);getCordovaBuildOutputFolder 则允许你自定义从 /src-cordova 相对路径出发的产物目录,返回字符串或字符串数组(数组表示"逐个尝试,命中即复制"),用于将产物回拷到 /dist。
此外,framework > config > cordova 下还提供一组移动端运行时行为选项:
return {
framework: {
config: {
cordova: {
// add the dynamic top padding on iOS mobile devices
iosStatusBarPadding?: boolean,
// account for Android safe areas (defaults to true)
androidStatusBarPadding?: boolean,
// Quasar handles app exit on mobile phone back button.
backButtonExit?: boolean | '*' | ['/login', '/home', '/my-page'],
// On the other hand, the following completely
// disables Quasar's back button management.
backButton?: boolean
}
}
}
}
各选项说明:
iosStatusBarPadding:为 iOS 移动设备动态增加顶部内边距(针对刘海屏状态栏遮挡问题);androidStatusBarPadding:适配 Android 安全区域,默认值为true;backButtonExit:控制 Quasar 对手机返回键退出应用的处理策略,可配置为布尔值,'*'表示任意路由均可退出,或传入路由路径数组(如['/login', '/home', '/my-page'])限定仅在这些页面可退出;backButton:设为false可完全禁用 Quasar 的返回键管理,交由应用自行处理。
以上选项在 ui/src/plugins/private.body/Body.js 与 ui/src/plugins/private.history/History.js 等运行时实现中生效。
针对 Cordova 模式扩展 Vite 配置
若需要在 Cordova 模式下调整 /src 中 UI 的 Vite 配置,可在 quasar.config 中使用 build > extendViteConf:
export default defineConfig(ctx => {
return {
build: {
extendViteConf(viteConf) {
if (ctx.mode.cordova) {
// do something with viteConf
// or return an object to deeply merge with current viteConf
}
}
}
}
})
Cordova 插件与 deviceready 事件
Cordova 插件是接入原生设备 API 的唯一通道。Quasar 官方文档推荐的常用插件包括:Battery Status(电池状态)、Camera(相机)、Contacts(联系人)、Device(设备信息)、Device Motion(设备运动)、Geolocation(地理位置)、Media(媒体播放)、Media Capture(媒体采集)、Network Information(网络信息)、Splashscreen(启动屏)、Vibration(振动)、Statusbar(状态栏)等。
deviceready 事件与应用的挂载时机
部分 Cordova 插件只有在 deviceready 事件触发后才可用。在 Cordova 模式下,Quasar 会等待该事件触发后才挂载根 Vue 应用,因此组件 setup 与生命周期钩子中可以直接使用已初始化的插件 API。
这一点可以从 app-vite/templates/entry/client-entry.js 的入口模板中得到印证:在非 SSR 且 ctx.mode.cordova 的条件下,代码先 document.addEventListener('deviceready', ...),在回调中把 window.cordova 挂到 $q.cordova,随后才执行 app.mount('#q-app')。
模块级代码的注意事项(Caveat)
虽然组件内可以放心使用插件 API,但模块级代码(module-level code)仍可能在 Vue 文件被导入、应用挂载之前执行,此时 deviceready 尚未触发,应避免在模块作用域访问 Cordova 插件全局对象。如果确实需要在模块级做初始化,就必须显式监听 deviceready 事件:
<template> ... we are sure 'deviceready' has been triggered here ... </template>
<script>
// outside of the default export,
// we need to listen to the event for ourselves:
document.addEventListener(
'deviceready',
() => {
// it's only now that we are sure
// the event has triggered
},
false
)
export default {
// we are sure 'deviceready' has been triggered here
}
</script>
实战:在 Quasar 应用中使用 Cordova 插件
使用任意 Cordova 插件的通用流程分为三步:查阅插件文档 → 在 /src-cordova 下执行安装命令 → 在 Vue 文件中调用插件 API。安装命令必须从 /src-cordova 目录(Cordova 生成的工程目录)执行,因为插件需要写入该原生工程。
示例一:Battery Status(电池状态)
首先查阅 Cordova Plugins 列表 中 Battery Status 插件的文档页,然后安装:
# from /src-cordova:
cordova plugin add cordova-plugin-battery-status
在 Quasar 项目的任意页面/布局/组件 Vue 文件中使用:
<template>
<div> Battery status is: <strong>{{ batteryStatus }}</strong> </div>
</template>
<script setup>
import { ref, onBeforeUnmount } from 'vue'
const batteryStatus = ref('determining...')
function updateBatteryStatus(status) {
batteryStatus.value = `Level: ${status.level}, plugged: ${status.isPlugged}`
}
// we register the event like on plugin's doc page
window.addEventListener('batterystatus', updateBatteryStatus, false)
onBeforeUnmount(() => {
// we do some cleanup;
// we need to remove the event listener
window.removeEventListener('batterystatus', updateBatteryStatus, false)
})
</script>
要点:插件通过 window 事件(batterystatus)推送状态,回调参数 status 包含 level(电量百分比)与 isPlugged(是否充电);组件卸载时务必移除事件监听,避免内存泄漏。
示例二:Camera(相机)
安装相机插件:
# from /src-cordova:
cordova plugin add cordova-plugin-camera
Camera 插件的文档会提及 deviceready 事件,处理方式与前文一致。在 Vue 组件中通过 navigator.camera.getPicture 调用,成功回调拿到 Base64 图片数据:
<template>
<div>
<q-btn color="primary" label="Get Picture" @click="captureImage" />
<img :src="imageSrc" />
</div>
</template>
<script setup>
import { useQuasar } from 'quasar'
import { ref } from 'vue'
const $q = useQuasar()
const imageSrc = ref('')
function captureImage() {
navigator.camera.getPicture(
data => {
// on success
imageSrc.value = `data:image/jpeg;base64,${data}`
},
() => {
// on fail
$q.notify('Could not access device camera.')
},
{
// camera options
}
)
}
</script>
这里展示了与 Quasar UI 的联动:失败时用 $q.notify()(来自 useQuasar())弹出提示,成功时将 Base64 数据拼成 data:image/jpeg;base64,... 作为图片源。getPicture 的第三个参数可传入相机选项对象(如 quality、destinationType、sourceType 等,具体以插件文档为准)。
示例三:Device(设备信息)
安装设备插件:
# from /src-cordova:
cordova plugin add cordova-plugin-device
该插件会初始化一个名为 device 的全局变量,用于描述设备的硬件与软件信息,可通过 window.device 访问。若需要在应用启动时获取设备信息,需在组件初始化阶段捕获:
<template>
<div>
<div>Model: {{ model }}</div>
<div>Manufacturer: {{ manufacturer }}</div>
</div>
</template>
<script setup>
import { ref } from 'vue'
const model = ref(window.device?.model ?? 'Unavailable')
const manufacturer = ref(window.device?.manufacturer ?? 'Unavailable')
</script>
使用可选链 ?. 与空值合并 ?? 对 window.device 做防御性取值,在插件尚未初始化(如运行在桌面浏览器调试时)给出兜底文案。
常见问题排查与发布
在实际开发中还有两点值得注意:
- 不要轻易升级原生工具链:Cordova 各平台对 Java、Gradle、Android SDK 及 Xcode 版本有严格兼容矩阵,升级前务必确认兼容性(参考 preparation.md 的警告)。
- 构建产物位置:
quasar build -m cordova后,产物默认复制到项目/dist/<android|ios>目录;如果自定义了getCordovaBuildOutputFolder且返回多个候选目录,Quasar 会按顺序尝试复制第一个存在的目录。
关于 Android 应用图标与启动屏配置、发布到应用商店(含签名与版本号管理)、以及更多疑难杂症,可继续阅读仓库 docs 目录下的相关章节:app-icons-cordova.md、publishing-to-store.md、troubleshooting-and-tips.md 与 managing-google-analytics.md。
小结
Quasar 的 Cordova 模式提供了一套"一套代码、多端打包"的混合应用方案:/src-cordova 作为原生 Cordova 工程与 /src 中的 Vue 界面分离,quasar.config 中的 cordova 对象控制版本注入与构建参数,deviceready 事件保证插件 API 在应用挂载前就绪。结合本文给出的环境准备、配置详解与三个完整插件实战示例,你已经可以在自己的 Quasar 项目中直接落地混合移动应用开发。