简介Vue 与 Cordova 原生能力集成的实践型参考资料面向已有 Vue 基础、希望将 Web 页面封装为移动应用并调用设备功能的前端开发者。内容围绕地理位置获取、手机振动、相机与相册取图、二维码扫描等常见场景展开涉及 camera、geolocation、vibration、barcode-scanner 等 Cordova 插件的接入方式并提示权限申请、平台兼容、参数配置与真机调试等易错点适合搭建跨平台功能验证 demo也可作为项目中的插件调用与排错清单。对移动端混合开发初学者可据此梳理插件接入、页面调用、回调处理、权限声明与联调流程对已有项目也可对照检查 Android/iOS 平台差异。压缩包为 zip 格式约 14.48MB文件总数显示为 0、类型明细暂无数据具体以实际包内内容为准。已有 534 人学习或下载可用于快速了解 Vue 与 Cordova 结合后的原生能力边界及工程组织方式。1. Vue 页面调不起相机先看清 Cordova 桥接层的四个原生入口Vue 项目接 Cordova 的原生能力最常被点名的就是定位、振动、拍照和扫一扫。页面在浏览器里跑得好好的一进真机就露馅navigator.camera是 undefined扫码回调不回来定位失败码挂在 1 上不动。Cordova 不是“把网页打包成 App”的壳它真正值钱的是 JS 到原生的桥接层插件只有在deviceready之后才可用。这套组合适合已经有 Vue 页面、不想重写一套原生 UI、又需要补上定位、振动、拍照、扫码四类能力的团队。下面按工程装配、定位与振动、调取图片、扫一扫与避坑、composable 封装六段拆每一步都落代码和参数真机上调不通时能直接对照排查。2. 把 Vue 构建产物塞进 Cordova 壳目录、插件与 deviceready 时序2.1 目录约定Vue 负责页面Cordova 只负责容器常见做法是 Vue 项目单独构建再把dist的内容复制到 Cordova 工程的www目录。不要让 Vue 的开发服务器直接跑在 Cordova 里热更新和原生插件调试会互相打架。构建时要把base设成相对路径Cordova 用file://加载页面绝对路径/assets/...会直接 404白屏十有八九从这里来。# 建一个 Vue 项目构建产物后面拷进 Cordova 的 www npm create vitelatest vue-cordova-demo -- --template vue cd vue-cordova-demo npm install这一步只生成 Vue 工程还没有任何原生能力。项目名用虚构的vue-cordova-demo实际落地时换成自己的业务名即可。// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], base: ./, // Cordova 用 file:// 加载绝对路径会 404 build: { outDir: dist, assetsDir: assets }, server: { host: 0.0.0.0, port: 5173 } })base: ./是关键参数它让构建后的index.html用相对路径引 JS 和 CSS。outDir保持dist后面复制脚本按这个目录取文件。server.host只影响浏览器调试和真机无关保留是为了局域网内用手机浏览器看样式。2.2 建 Cordova 壳并装插件四个能力对应五个包Cordova 工程单独建包名用虚构的com.demo.nativeapp不要拿真实公司域名。平台先加 Android有 mac 环境再加 iOS。插件安装不要图省事一次性堆在config.xml里命令行装完会写进package.json和config.xml后面排查插件是否真的进包看这两个文件比看记忆可靠。# 建 Cordova 壳包名是虚构的 npx cordova create cordova-shell com.demo.nativeapp NativeShell cd cordova-shell npx cordova platform add android # 有 mac 环境再加 iOS # npx cordova platform add ioscordova create的三个参数分别是目录名、包名、应用显示名。包名一旦上架后不好改测试阶段可以用虚构包名正式发布前统一替换。# 四个原生能力对应的插件另加 file 插件处理拍照后的本地路径 npx cordova plugin add cordova-plugin-geolocation npx cordova plugin add cordova-plugin-vibration npx cordova plugin add cordova-plugin-camera npx cordova plugin add cordova-plugin-barcode-scanner npx cordova plugin add cordova-plugin-filecordova-plugin-geolocation负责定位cordova-plugin-vibration负责振动cordova-plugin-camera负责拍照和相册cordova-plugin-barcode-scanner负责扫一扫。cordova-plugin-file不是拍照必需但 Camera 返回file://路径后要在 WebView 里读成 Blob 或 base64绕不开它。插件装完执行一次npx cordova prepare让平台工程同步插件声明。2.3 同步构建产物别手动复制漏文件Vue 构建完把dist里的内容同步到 Cordova 的www。手动拖文件容易漏assets下的 chunk表现是页面能开、某个路由白屏。用命令删干净再复制比“覆盖粘贴”稳。# Vue 项目构建后同步到 Cordova 的 www cd vue-cordova-demo npm run build rm -rf ../cordova-shell/www/* cp -r dist/* ../cordova-shell/www/rm -rf只删www下的旧产物不动 Cordova 工程根目录的配置。复制完成后检查www/index.html是否存在www/assets下是否有 JS/CSS 文件。如果用了 Vue Router路由模式选 hashcreateWebHistory在file://下刷新会 404这不是 Cordova 的 bug是浏览器对本地文件路径的限制。2.4 deviceready 与 cordova.js插件注入的时间点Cordova 容器加载页面后会先注入cordova.js再触发deviceready。插件对象在这个事件之后才挂到window上。Vue 的main.js如果直接mount组件里的onMounted可能早于插件就绪表现就是“浏览器正常、真机 undefined”。!-- Cordova 平台工程里的 www/index.html保留 cordova.js 引用 -- script srccordova.js/scriptcordova.js不在 Vue 源码里手写实现它由 Cordova 平台工程生成并注入。构建复制时不要把它覆盖掉复制完dist后确认www/cordova.js还在。少了这个文件deviceready永远不会触发。// main.js import { createApp } from vue import App from ./App.vue const app createApp(App) function mountApp() { app.mount(#app) window.__APP_READY__ true } if (window.cordova) { document.addEventListener(deviceready, mountApp, { once: true }) } else { // 浏览器里没有 Cordova 注入直接挂载只用于调样式 mountApp() }window.cordova是判断是否在 Cordova 容器内的低成本方式浏览器里它是 undefined。{ once: true }避免deviceready重复触发导致 Vue 重复挂载。window.__APP_READY__是给后续插件等待逻辑用的标记不是框架要求但排查时序时很好用。// src/native/bridge.js export function waitForPlugin(check, timeout 8000, interval 120) { return new Promise((resolve, reject) { const start Date.now() const timer setInterval(() { if (check()) { clearInterval(timer) resolve(true) } else if (Date.now() - start timeout) { clearInterval(timer) reject(new Error(等待原生插件超时)) } }, interval) }) } export function hasCamera() { return Boolean(window.navigator window.navigator.camera) }waitForPlugin接收一个检查函数轮询到条件成立或超时。timeout默认 8000 毫秒低端机冷启动可能更慢可以调到 12000。interval控制轮询间隔太小耗电太大反应慢120 毫秒在真机上比较平衡。hasCamera只是示例扫码、定位可以按同样方式写检查函数。3. 定位与振动Geolocation 的三个参数和 Vibration 的降级写法3.1 定位参数精度、超时、缓存分别管什么navigator.geolocation.getCurrentPosition在 Cordova 里由插件代理到系统定位服务。三个参数最常被忽略enableHighAccuracy、timeout、maximumAge。高精度不是永远更好户外签到需要它室内频繁取点反而费电maximumAge设 0 表示不吃缓存设 60000 表示一分钟内的位置可以直接复用。参数常用值作用容易踩的点enableHighAccuracytrue / false是否请求高精度定位室内开高精度可能更慢失败码更容易出现timeout10000超过这个毫秒数走失败回调设得太短冷启动必失败maximumAge0 或 60000允许使用多久内的缓存位置设 0 不代表一定拿新点系统仍可能复用定位失败回调里的err.code比err.message有用1 是权限拒绝2 是位置不可用3 是超时。真机上先看系统定位开关再看应用权限里是“仅使用期间”还是“不允许”最后才怀疑代码。3.2 定位代码拿一次位置和持续监听要分开封装// src/native/geolocation.js export function getCurrentPosition(options {}) { const defaultOptions { enableHighAccuracy: true, // 户外签到用高精度室内可传 false timeout: 10000, maximumAge: 0 } return new Promise((resolve, reject) { if (!navigator.geolocation) { reject(new Error(当前容器不支持 geolocation)) return } navigator.geolocation.getCurrentPosition( (pos) resolve({ latitude: pos.coords.latitude, longitude: pos.coords.longitude, accuracy: pos.coords.accuracy, timestamp: pos.timestamp }), (err) reject(new Error(定位失败: code${err.code}, message${err.message})), { ...defaultOptions, ...options } ) }) } export function watchPosition(onChange, onError, options {}) { const watchId navigator.geolocation.watchPosition( (pos) onChange({ latitude: pos.coords.latitude, longitude: pos.coords.longitude, accuracy: pos.coords.accuracy }), (err) onError(new Error(监听定位失败: code${err.code})), { enableHighAccuracy: true, timeout: 15000, maximumAge: 3000, ...options } ) return () navigator.geolocation.clearWatch(watchId) }getCurrentPosition返回 Promise调用方用await拿经纬度和精度。accuracy单位是米值越大越不准展示给用户时可以四舍五入到 10 米。watchPosition返回一个清理函数组件卸载时必须调用否则页面切走后定位监听还在跑电量和日志都会很难看。maximumAge: 3000表示三秒内的缓存点可以接受适合轨迹类场景不适合打卡。3.3 振动Android 可控时长iOS 只保证“震一下”Cordova 的振动插件会往navigator.vibrate上挂方法。传数字表示振动毫秒数传数组表示“振-停-振”交替奇数位是振动偶数位是暂停。Android 上时长基本按参数走iOS 上常见只触发一次固定震动不保证你传的 200 毫秒被精确执行。所以振动只能当反馈增强不能当业务信号。// src/native/vibration.js export function vibrateOnce(duration 200) { if (!navigator.vibrate) { return false } return navigator.vibrate(duration) } export function vibratePattern(pattern [100, 60, 100]) { if (!navigator.vibrate) { return false } return navigator.vibrate(pattern) } export function stopVibrate() { if (navigator.vibrate) { navigator.vibrate(0) } }vibrateOnce返回布尔值表示当前容器是否支持振动调用方可以据此决定要不要补一个视觉提示。vibratePattern的数组长度最好是偶数[100, 60, 100]这种奇数结尾在部分实现里会多震一下。stopVibrate传 0 是取消振动的通用写法长振动场景要留这个后悔药。注意iOS 上振动通常要求调用发生在用户手势之后页面加载完自动调用很可能没反应。把振动挂在按钮点击事件里比在onMounted里调用可靠。4. 调取手机图片Camera 的三种返回格式与 file:// 路径处理4.1 destinationType 怎么选FILE_URI、DATA_URL、NATIVE_URICamera 插件最关键的参数是destinationType。FILE_URI返回本地文件路径适合上传和后续压缩DATA_URL返回 base64 字符串适合直接塞进img预览但大图会撑爆内存NATIVE_URI返回平台原生 URIAndroid 上常见content://WebView 直接显示不稳定。工程里我一般默认FILE_URI预览时再转 Blob URL内存可控。参数常用值作用建议quality80JPEG 压缩质量0 到 100上传用 70 到 80头像可更低destinationTypeCamera.DestinationType.FILE_URI返回文件路径默认选它别直接返回 base64sourceTypeCAMERA / PHOTOLIBRARY拍照或相册两个入口分开封装encodingTypeCamera.EncodingType.JPEG编码格式JPEG 兼容性最好correctOrientationtrue纠正照片旋转不加这个部分机型照片会躺倒saveToPhotoAlbumfalse是否存系统相册拍照上传场景一般关掉targetWidth和targetHeight可以限制输出尺寸但会改变宽高比证件类图片不要用。correctOrientation在 Android 上尤其重要很多机型拍出来的 JPEG 带旋转 EXIFWebView 不认页面里就是横着的。4.2 拍照与相册两个入口共用一套参数// src/native/camera.js export function takePhoto(options {}) { const defaultOptions { quality: 80, destinationType: Camera.DestinationType.FILE_URI, sourceType: Camera.PictureSourceType.CAMERA, encodingType: Camera.EncodingType.JPEG, mediaType: Camera.MediaType.PICTURE, correctOrientation: true, saveToPhotoAlbum: false } return new Promise((resolve, reject) { if (!navigator.camera) { reject(new Error(Camera 插件未就绪检查 deviceready 和插件安装)) return } navigator.camera.getPicture( (imageUrl) resolve(imageUrl), (message) reject(new Error(拍照失败: ${message})), { ...defaultOptions, ...options } ) }) } export function pickFromAlbum(options {}) { return takePhoto({ sourceType: Camera.PictureSourceType.PHOTOLIBRARY, ...options }) }Camera是插件注入的全局对象浏览器里不存在所以先判断navigator.camera。getPicture成功回调拿到的是字符串FILE_URI模式下是file://路径。pickFromAlbum复用takePhoto只改sourceType参数不要在两处各写一份后面改质量容易漏。4.3 file:// 转 Blob预览和上传都走这一层img srcfile:///...在部分 WebView 里被安全策略拦住页面显示裂图。稳妥做法是用resolveLocalFileSystemURL读文件转成 Blob再URL.createObjectURL预览、FormData上传。用完记得revokeObjectURL否则连续拍照会堆内存。// src/native/file.js export function fileUriToBlob(fileUri) { return new Promise((resolve, reject) { window.resolveLocalFileSystemURL( fileUri, (entry) { entry.file( (file) { const reader new FileReader() reader.onloadend () { const blob new Blob( [new Uint8Array(reader.result)], { type: file.type || image/jpeg } ) resolve({ blob, file }) } reader.onerror () reject(new Error(读取文件失败)) reader.readAsArrayBuffer(file) }, (err) reject(new Error(获取文件失败: code${err.code})) ) }, (err) reject(new Error(解析路径失败: code${err.code})) ) }) } export async function uploadImage(fileUri, url) { const { blob, file } await fileUriToBlob(fileUri) const form new FormData() form.append(file, blob, file.name || photo-${Date.now()}.jpg) const res await fetch(url, { method: POST, body: form }) if (!res.ok) { throw new Error(上传失败: status${res.status}) } return res.json() }resolveLocalFileSystemURL由 file 插件提供entry.file拿到File对象。readAsArrayBuffer比readAsDataURL更适合大图base64 会多出约三分之一体积。FormData上传时不要手动设Content-Type浏览器会自动补 boundary手动设反而会让服务端解析失败。file.name在部分机型上为空兜底用时间戳拼文件名。5. 扫一扫与避坑排查BarcodeScanner 接入和 5 个真机翻车记录5.1 扫码接入formats 参数决定能不能扫出一维码BarcodeScanner 的调用入口是cordova.plugins.barcodeScanner.scan成功回调里的result.cancelled要先判断用户点返回也会进成功回调。formats不传时插件用默认格式集想扫一维码要显式加CODE_128、EAN_13只写QR_CODE就只能扫二维码。iOS 和 Android 支持的格式集合不完全一样跨端项目取交集更稳。// src/native/scanner.js export function scanCode(options {}) { const defaultOptions { preferFrontCamera: false, showFlipCameraButton: true, showTorchButton: true, torchOn: false, prompt: 将二维码放入框内, resultDisplayDuration: 800, formats: QR_CODE,CODE_128,EAN_13, orientation: portrait } return new Promise((resolve, reject) { if (!window.cordova || !window.cordova.plugins?.barcodeScanner) { reject(new Error(扫码插件未就绪)) return } window.cordova.plugins.barcodeScanner.scan( (result) { if (result.cancelled) { resolve({ cancelled: true }) return } resolve({ text: result.text, format: result.format }) }, (err) reject(new Error(扫码失败: ${err})), { ...defaultOptions, ...options } ) }) }prompt是扫码框下方的提示文案别写太长小屏会截断。resultDisplayDuration控制扫中后结果停留时间单位毫秒设 0 在部分版本里等于不停留。orientation锁竖屏可以减少横竖屏切换导致的预览拉伸。返回值统一成{ cancelled, text, format }页面层不用关心插件原始结构。5.2 权限与连续扫码相机资源要等回调结束再释放Android 上相机权限通常由插件在清单里声明但系统仍会弹授权框iOS 必须在平台工程里补NSCameraUsageDescription文案写清楚“用于扫描二维码和拍照上传”否则真机直接闪退。连续扫码最常见的翻车是扫完一次立刻再调scan相机预览还没释放第二次就黑屏或没回调。加一个状态锁等上一次 Promise 结束再允许下一次。!-- config.xml 里补相机权限描述文案按实际用途写 -- platform nameios edit-config file*-Info.plist modemerge targetNSCameraUsageDescription string用于扫描二维码和拍照上传/string /edit-config /platform这段配置放在 Cordova 工程的config.xml里edit-config会在平台准备阶段合并进Info.plist。文案不要写“需要相机权限”这种空话审核和用户都看不懂。Android 侧如果目标版本较高还要确认清单里是否声明了相机硬件特性缺失时应用商店可能过滤掉设备。5.3 避坑记录五个真机翻车现场现象一浏览器里一切正常真机上navigator.camera是 undefined。原因插件只在 Cordova 容器内注入而且必须等deviceready之后。浏览器没有cordova.js自然不会挂插件对象。 解决确认www/cordova.js存在Vue 挂载放在deviceready回调里调用前用navigator.camera做存在性判断不要靠try/catch兜底。现象二定位一直失败err.code是 1。原因应用没有定位权限或者系统定位总开关关着。高精度模式还会受室内信号影响但 code 1 优先看权限。 解决到系统设置里看应用权限Android 高版本要区分“精确”和“大致”位置iOS 看“使用期间”是否允许。权限拒绝后不要反复弹系统框引导用户去设置页。现象三拍照返回file://路径页面img显示裂图。原因WebView 对本地文件路径有安全限制直接当src不一定放行。 解决用resolveLocalFileSystemURL读成 Blob再URL.createObjectURL预览上传走FormData。组件卸载时revokeObjectURL别让 Blob URL 越堆越多。现象四扫码第一次成功第二次黑屏或没有回调。原因上一次扫码的相机预览没释放页面又立刻发起第二次调用或者扫码容器被 Vue 的v-if销毁后插件仍持有旧引用。 解决在扫码方法外层加scanning状态锁Promise 未结束前不响应按钮扫码完成后先关闭结果层再允许下一次。不要在成功回调里同步递归调用scan。现象五构建后白屏控制台报资源 404。原因Vite 的base没设成./或者 Vue Router 用了 history 模式file://下刷新找不到路径。 解决base改相对路径路由换 hash 模式复制构建产物时确认assets目录完整index.html里的引用路径不是/assets/...。6. 封装成 Vue composable四个原生能力的验证清单与调用边界页面里到处写navigator.camera和cordova.plugins.barcodeScanner维护成本会越来越高。我一般把四个能力收进一个useNative统一处理 loading、错误信息和调用边界页面只关心“点按钮、拿结果”。// src/composables/useNative.js import { ref } from vue import { getCurrentPosition } from /native/geolocation import { vibrateOnce } from /native/vibration import { takePhoto, pickFromAlbum } from /native/camera import { scanCode } from /native/scanner export function useNative() { const loading ref(false) const error ref() async function run(task) { loading.value true error.value try { return await task() } catch (e) { error.value e.message || String(e) throw e } finally { loading.value false } } return { loading, error, locate: (options) run(() getCurrentPosition(options)), vibrate: (duration) vibrateOnce(duration), photo: (options) run(() takePhoto(options)), album: (options) run(() pickFromAlbum(options)), scan: (options) run(() scanCode(options)) } }run只包异步能力振动是同步返回布尔值不放进 loading。error保存最后一条错误信息页面可以统一 toast不用每个按钮各写一套。locate、photo、album、scan都返回 Promise调用方用try/catch或.catch接住避免未处理拒绝。真机联调时按下面这张表走一遍比在代码里猜快得多。检查项预期表现失败先看devicereadywindow.cordova存在cordova.js是否在 www 根目录定位返回经纬度和 accuracy系统定位开关、应用权限振动点击后设备震动是否在用户手势里调用拍照返回file://路径Camera 插件是否进包、存储权限相册能选图并返回路径相册权限、sourceType 是否写对扫码返回 text 和 format相机权限、formats 是否匹配从那以后我每次接入新插件都先把deviceready、权限和真机日志走一遍再谈页面联调。这套顺序看着笨但能少熬几个晚上。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/11/2 15:59:32 · 阅读 1.2k Vue+Cordova 原生能力接入：定位、拍照、扫码与真机避坑
简介Vue 与 Cordova 原生能力集成的实践型参考资料面向已有 Vue 基础、希望将 Web 页面封装为移动应用并调用设备功能的前端开发者。内容围绕地理位置获取、手机振动、相机与相册取图、二维码扫描等常见场景展开涉及 camera、geolocation、vibration、barcode-scanner 等 Cordova 插件的接入方式并提示权限申请、平台兼容、参数配置与真机调试等易错点适合搭建跨平台功能验证 demo也可作为项目中的插件调用与排错清单。对移动端混合开发初学者可据此梳理插件接入、页面调用、回调处理、权限声明与联调流程对已有项目也可对照检查 Android/iOS 平台差异。压缩包为 zip 格式约 14.48MB文件总数显示为 0、类型明细暂无数据具体以实际包内内容为准。已有 534 人学习或下载可用于快速了解 Vue 与 Cordova 结合后的原生能力边界及工程组织方式。1. Vue 页面调不起相机先看清 Cordova 桥接层的四个原生入口Vue 项目接 Cordova 的原生能力最常被点名的就是定位、振动、拍照和扫一扫。页面在浏览器里跑得好好的一进真机就露馅navigator.camera是 undefined扫码回调不回来定位失败码挂在 1 上不动。Cordova 不是“把网页打包成 App”的壳它真正值钱的是 JS 到原生的桥接层插件只有在deviceready之后才可用。这套组合适合已经有 Vue 页面、不想重写一套原生 UI、又需要补上定位、振动、拍照、扫码四类能力的团队。下面按工程装配、定位与振动、调取图片、扫一扫与避坑、composable 封装六段拆每一步都落代码和参数真机上调不通时能直接对照排查。2. 把 Vue 构建产物塞进 Cordova 壳目录、插件与 deviceready 时序2.1 目录约定Vue 负责页面Cordova 只负责容器常见做法是 Vue 项目单独构建再把dist的内容复制到 Cordova 工程的www目录。不要让 Vue 的开发服务器直接跑在 Cordova 里热更新和原生插件调试会互相打架。构建时要把base设成相对路径Cordova 用file://加载页面绝对路径/assets/...会直接 404白屏十有八九从这里来。# 建一个 Vue 项目构建产物后面拷进 Cordova 的 www npm create vitelatest vue-cordova-demo -- --template vue cd vue-cordova-demo npm install这一步只生成 Vue 工程还没有任何原生能力。项目名用虚构的vue-cordova-demo实际落地时换成自己的业务名即可。// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], base: ./, // Cordova 用 file:// 加载绝对路径会 404 build: { outDir: dist, assetsDir: assets }, server: { host: 0.0.0.0, port: 5173 } })base: ./是关键参数它让构建后的index.html用相对路径引 JS 和 CSS。outDir保持dist后面复制脚本按这个目录取文件。server.host只影响浏览器调试和真机无关保留是为了局域网内用手机浏览器看样式。2.2 建 Cordova 壳并装插件四个能力对应五个包Cordova 工程单独建包名用虚构的com.demo.nativeapp不要拿真实公司域名。平台先加 Android有 mac 环境再加 iOS。插件安装不要图省事一次性堆在config.xml里命令行装完会写进package.json和config.xml后面排查插件是否真的进包看这两个文件比看记忆可靠。# 建 Cordova 壳包名是虚构的 npx cordova create cordova-shell com.demo.nativeapp NativeShell cd cordova-shell npx cordova platform add android # 有 mac 环境再加 iOS # npx cordova platform add ioscordova create的三个参数分别是目录名、包名、应用显示名。包名一旦上架后不好改测试阶段可以用虚构包名正式发布前统一替换。# 四个原生能力对应的插件另加 file 插件处理拍照后的本地路径 npx cordova plugin add cordova-plugin-geolocation npx cordova plugin add cordova-plugin-vibration npx cordova plugin add cordova-plugin-camera npx cordova plugin add cordova-plugin-barcode-scanner npx cordova plugin add cordova-plugin-filecordova-plugin-geolocation负责定位cordova-plugin-vibration负责振动cordova-plugin-camera负责拍照和相册cordova-plugin-barcode-scanner负责扫一扫。cordova-plugin-file不是拍照必需但 Camera 返回file://路径后要在 WebView 里读成 Blob 或 base64绕不开它。插件装完执行一次npx cordova prepare让平台工程同步插件声明。2.3 同步构建产物别手动复制漏文件Vue 构建完把dist里的内容同步到 Cordova 的www。手动拖文件容易漏assets下的 chunk表现是页面能开、某个路由白屏。用命令删干净再复制比“覆盖粘贴”稳。# Vue 项目构建后同步到 Cordova 的 www cd vue-cordova-demo npm run build rm -rf ../cordova-shell/www/* cp -r dist/* ../cordova-shell/www/rm -rf只删www下的旧产物不动 Cordova 工程根目录的配置。复制完成后检查www/index.html是否存在www/assets下是否有 JS/CSS 文件。如果用了 Vue Router路由模式选 hashcreateWebHistory在file://下刷新会 404这不是 Cordova 的 bug是浏览器对本地文件路径的限制。2.4 deviceready 与 cordova.js插件注入的时间点Cordova 容器加载页面后会先注入cordova.js再触发deviceready。插件对象在这个事件之后才挂到window上。Vue 的main.js如果直接mount组件里的onMounted可能早于插件就绪表现就是“浏览器正常、真机 undefined”。!-- Cordova 平台工程里的 www/index.html保留 cordova.js 引用 -- script srccordova.js/scriptcordova.js不在 Vue 源码里手写实现它由 Cordova 平台工程生成并注入。构建复制时不要把它覆盖掉复制完dist后确认www/cordova.js还在。少了这个文件deviceready永远不会触发。// main.js import { createApp } from vue import App from ./App.vue const app createApp(App) function mountApp() { app.mount(#app) window.__APP_READY__ true } if (window.cordova) { document.addEventListener(deviceready, mountApp, { once: true }) } else { // 浏览器里没有 Cordova 注入直接挂载只用于调样式 mountApp() }window.cordova是判断是否在 Cordova 容器内的低成本方式浏览器里它是 undefined。{ once: true }避免deviceready重复触发导致 Vue 重复挂载。window.__APP_READY__是给后续插件等待逻辑用的标记不是框架要求但排查时序时很好用。// src/native/bridge.js export function waitForPlugin(check, timeout 8000, interval 120) { return new Promise((resolve, reject) { const start Date.now() const timer setInterval(() { if (check()) { clearInterval(timer) resolve(true) } else if (Date.now() - start timeout) { clearInterval(timer) reject(new Error(等待原生插件超时)) } }, interval) }) } export function hasCamera() { return Boolean(window.navigator window.navigator.camera) }waitForPlugin接收一个检查函数轮询到条件成立或超时。timeout默认 8000 毫秒低端机冷启动可能更慢可以调到 12000。interval控制轮询间隔太小耗电太大反应慢120 毫秒在真机上比较平衡。hasCamera只是示例扫码、定位可以按同样方式写检查函数。3. 定位与振动Geolocation 的三个参数和 Vibration 的降级写法3.1 定位参数精度、超时、缓存分别管什么navigator.geolocation.getCurrentPosition在 Cordova 里由插件代理到系统定位服务。三个参数最常被忽略enableHighAccuracy、timeout、maximumAge。高精度不是永远更好户外签到需要它室内频繁取点反而费电maximumAge设 0 表示不吃缓存设 60000 表示一分钟内的位置可以直接复用。参数常用值作用容易踩的点enableHighAccuracytrue / false是否请求高精度定位室内开高精度可能更慢失败码更容易出现timeout10000超过这个毫秒数走失败回调设得太短冷启动必失败maximumAge0 或 60000允许使用多久内的缓存位置设 0 不代表一定拿新点系统仍可能复用定位失败回调里的err.code比err.message有用1 是权限拒绝2 是位置不可用3 是超时。真机上先看系统定位开关再看应用权限里是“仅使用期间”还是“不允许”最后才怀疑代码。3.2 定位代码拿一次位置和持续监听要分开封装// src/native/geolocation.js export function getCurrentPosition(options {}) { const defaultOptions { enableHighAccuracy: true, // 户外签到用高精度室内可传 false timeout: 10000, maximumAge: 0 } return new Promise((resolve, reject) { if (!navigator.geolocation) { reject(new Error(当前容器不支持 geolocation)) return } navigator.geolocation.getCurrentPosition( (pos) resolve({ latitude: pos.coords.latitude, longitude: pos.coords.longitude, accuracy: pos.coords.accuracy, timestamp: pos.timestamp }), (err) reject(new Error(定位失败: code${err.code}, message${err.message})), { ...defaultOptions, ...options } ) }) } export function watchPosition(onChange, onError, options {}) { const watchId navigator.geolocation.watchPosition( (pos) onChange({ latitude: pos.coords.latitude, longitude: pos.coords.longitude, accuracy: pos.coords.accuracy }), (err) onError(new Error(监听定位失败: code${err.code})), { enableHighAccuracy: true, timeout: 15000, maximumAge: 3000, ...options } ) return () navigator.geolocation.clearWatch(watchId) }getCurrentPosition返回 Promise调用方用await拿经纬度和精度。accuracy单位是米值越大越不准展示给用户时可以四舍五入到 10 米。watchPosition返回一个清理函数组件卸载时必须调用否则页面切走后定位监听还在跑电量和日志都会很难看。maximumAge: 3000表示三秒内的缓存点可以接受适合轨迹类场景不适合打卡。3.3 振动Android 可控时长iOS 只保证“震一下”Cordova 的振动插件会往navigator.vibrate上挂方法。传数字表示振动毫秒数传数组表示“振-停-振”交替奇数位是振动偶数位是暂停。Android 上时长基本按参数走iOS 上常见只触发一次固定震动不保证你传的 200 毫秒被精确执行。所以振动只能当反馈增强不能当业务信号。// src/native/vibration.js export function vibrateOnce(duration 200) { if (!navigator.vibrate) { return false } return navigator.vibrate(duration) } export function vibratePattern(pattern [100, 60, 100]) { if (!navigator.vibrate) { return false } return navigator.vibrate(pattern) } export function stopVibrate() { if (navigator.vibrate) { navigator.vibrate(0) } }vibrateOnce返回布尔值表示当前容器是否支持振动调用方可以据此决定要不要补一个视觉提示。vibratePattern的数组长度最好是偶数[100, 60, 100]这种奇数结尾在部分实现里会多震一下。stopVibrate传 0 是取消振动的通用写法长振动场景要留这个后悔药。注意iOS 上振动通常要求调用发生在用户手势之后页面加载完自动调用很可能没反应。把振动挂在按钮点击事件里比在onMounted里调用可靠。4. 调取手机图片Camera 的三种返回格式与 file:// 路径处理4.1 destinationType 怎么选FILE_URI、DATA_URL、NATIVE_URICamera 插件最关键的参数是destinationType。FILE_URI返回本地文件路径适合上传和后续压缩DATA_URL返回 base64 字符串适合直接塞进img预览但大图会撑爆内存NATIVE_URI返回平台原生 URIAndroid 上常见content://WebView 直接显示不稳定。工程里我一般默认FILE_URI预览时再转 Blob URL内存可控。参数常用值作用建议quality80JPEG 压缩质量0 到 100上传用 70 到 80头像可更低destinationTypeCamera.DestinationType.FILE_URI返回文件路径默认选它别直接返回 base64sourceTypeCAMERA / PHOTOLIBRARY拍照或相册两个入口分开封装encodingTypeCamera.EncodingType.JPEG编码格式JPEG 兼容性最好correctOrientationtrue纠正照片旋转不加这个部分机型照片会躺倒saveToPhotoAlbumfalse是否存系统相册拍照上传场景一般关掉targetWidth和targetHeight可以限制输出尺寸但会改变宽高比证件类图片不要用。correctOrientation在 Android 上尤其重要很多机型拍出来的 JPEG 带旋转 EXIFWebView 不认页面里就是横着的。4.2 拍照与相册两个入口共用一套参数// src/native/camera.js export function takePhoto(options {}) { const defaultOptions { quality: 80, destinationType: Camera.DestinationType.FILE_URI, sourceType: Camera.PictureSourceType.CAMERA, encodingType: Camera.EncodingType.JPEG, mediaType: Camera.MediaType.PICTURE, correctOrientation: true, saveToPhotoAlbum: false } return new Promise((resolve, reject) { if (!navigator.camera) { reject(new Error(Camera 插件未就绪检查 deviceready 和插件安装)) return } navigator.camera.getPicture( (imageUrl) resolve(imageUrl), (message) reject(new Error(拍照失败: ${message})), { ...defaultOptions, ...options } ) }) } export function pickFromAlbum(options {}) { return takePhoto({ sourceType: Camera.PictureSourceType.PHOTOLIBRARY, ...options }) }Camera是插件注入的全局对象浏览器里不存在所以先判断navigator.camera。getPicture成功回调拿到的是字符串FILE_URI模式下是file://路径。pickFromAlbum复用takePhoto只改sourceType参数不要在两处各写一份后面改质量容易漏。4.3 file:// 转 Blob预览和上传都走这一层img srcfile:///...在部分 WebView 里被安全策略拦住页面显示裂图。稳妥做法是用resolveLocalFileSystemURL读文件转成 Blob再URL.createObjectURL预览、FormData上传。用完记得revokeObjectURL否则连续拍照会堆内存。// src/native/file.js export function fileUriToBlob(fileUri) { return new Promise((resolve, reject) { window.resolveLocalFileSystemURL( fileUri, (entry) { entry.file( (file) { const reader new FileReader() reader.onloadend () { const blob new Blob( [new Uint8Array(reader.result)], { type: file.type || image/jpeg } ) resolve({ blob, file }) } reader.onerror () reject(new Error(读取文件失败)) reader.readAsArrayBuffer(file) }, (err) reject(new Error(获取文件失败: code${err.code})) ) }, (err) reject(new Error(解析路径失败: code${err.code})) ) }) } export async function uploadImage(fileUri, url) { const { blob, file } await fileUriToBlob(fileUri) const form new FormData() form.append(file, blob, file.name || photo-${Date.now()}.jpg) const res await fetch(url, { method: POST, body: form }) if (!res.ok) { throw new Error(上传失败: status${res.status}) } return res.json() }resolveLocalFileSystemURL由 file 插件提供entry.file拿到File对象。readAsArrayBuffer比readAsDataURL更适合大图base64 会多出约三分之一体积。FormData上传时不要手动设Content-Type浏览器会自动补 boundary手动设反而会让服务端解析失败。file.name在部分机型上为空兜底用时间戳拼文件名。5. 扫一扫与避坑排查BarcodeScanner 接入和 5 个真机翻车记录5.1 扫码接入formats 参数决定能不能扫出一维码BarcodeScanner 的调用入口是cordova.plugins.barcodeScanner.scan成功回调里的result.cancelled要先判断用户点返回也会进成功回调。formats不传时插件用默认格式集想扫一维码要显式加CODE_128、EAN_13只写QR_CODE就只能扫二维码。iOS 和 Android 支持的格式集合不完全一样跨端项目取交集更稳。// src/native/scanner.js export function scanCode(options {}) { const defaultOptions { preferFrontCamera: false, showFlipCameraButton: true, showTorchButton: true, torchOn: false, prompt: 将二维码放入框内, resultDisplayDuration: 800, formats: QR_CODE,CODE_128,EAN_13, orientation: portrait } return new Promise((resolve, reject) { if (!window.cordova || !window.cordova.plugins?.barcodeScanner) { reject(new Error(扫码插件未就绪)) return } window.cordova.plugins.barcodeScanner.scan( (result) { if (result.cancelled) { resolve({ cancelled: true }) return } resolve({ text: result.text, format: result.format }) }, (err) reject(new Error(扫码失败: ${err})), { ...defaultOptions, ...options } ) }) }prompt是扫码框下方的提示文案别写太长小屏会截断。resultDisplayDuration控制扫中后结果停留时间单位毫秒设 0 在部分版本里等于不停留。orientation锁竖屏可以减少横竖屏切换导致的预览拉伸。返回值统一成{ cancelled, text, format }页面层不用关心插件原始结构。5.2 权限与连续扫码相机资源要等回调结束再释放Android 上相机权限通常由插件在清单里声明但系统仍会弹授权框iOS 必须在平台工程里补NSCameraUsageDescription文案写清楚“用于扫描二维码和拍照上传”否则真机直接闪退。连续扫码最常见的翻车是扫完一次立刻再调scan相机预览还没释放第二次就黑屏或没回调。加一个状态锁等上一次 Promise 结束再允许下一次。!-- config.xml 里补相机权限描述文案按实际用途写 -- platform nameios edit-config file*-Info.plist modemerge targetNSCameraUsageDescription string用于扫描二维码和拍照上传/string /edit-config /platform这段配置放在 Cordova 工程的config.xml里edit-config会在平台准备阶段合并进Info.plist。文案不要写“需要相机权限”这种空话审核和用户都看不懂。Android 侧如果目标版本较高还要确认清单里是否声明了相机硬件特性缺失时应用商店可能过滤掉设备。5.3 避坑记录五个真机翻车现场现象一浏览器里一切正常真机上navigator.camera是 undefined。原因插件只在 Cordova 容器内注入而且必须等deviceready之后。浏览器没有cordova.js自然不会挂插件对象。 解决确认www/cordova.js存在Vue 挂载放在deviceready回调里调用前用navigator.camera做存在性判断不要靠try/catch兜底。现象二定位一直失败err.code是 1。原因应用没有定位权限或者系统定位总开关关着。高精度模式还会受室内信号影响但 code 1 优先看权限。 解决到系统设置里看应用权限Android 高版本要区分“精确”和“大致”位置iOS 看“使用期间”是否允许。权限拒绝后不要反复弹系统框引导用户去设置页。现象三拍照返回file://路径页面img显示裂图。原因WebView 对本地文件路径有安全限制直接当src不一定放行。 解决用resolveLocalFileSystemURL读成 Blob再URL.createObjectURL预览上传走FormData。组件卸载时revokeObjectURL别让 Blob URL 越堆越多。现象四扫码第一次成功第二次黑屏或没有回调。原因上一次扫码的相机预览没释放页面又立刻发起第二次调用或者扫码容器被 Vue 的v-if销毁后插件仍持有旧引用。 解决在扫码方法外层加scanning状态锁Promise 未结束前不响应按钮扫码完成后先关闭结果层再允许下一次。不要在成功回调里同步递归调用scan。现象五构建后白屏控制台报资源 404。原因Vite 的base没设成./或者 Vue Router 用了 history 模式file://下刷新找不到路径。 解决base改相对路径路由换 hash 模式复制构建产物时确认assets目录完整index.html里的引用路径不是/assets/...。6. 封装成 Vue composable四个原生能力的验证清单与调用边界页面里到处写navigator.camera和cordova.plugins.barcodeScanner维护成本会越来越高。我一般把四个能力收进一个useNative统一处理 loading、错误信息和调用边界页面只关心“点按钮、拿结果”。// src/composables/useNative.js import { ref } from vue import { getCurrentPosition } from /native/geolocation import { vibrateOnce } from /native/vibration import { takePhoto, pickFromAlbum } from /native/camera import { scanCode } from /native/scanner export function useNative() { const loading ref(false) const error ref() async function run(task) { loading.value true error.value try { return await task() } catch (e) { error.value e.message || String(e) throw e } finally { loading.value false } } return { loading, error, locate: (options) run(() getCurrentPosition(options)), vibrate: (duration) vibrateOnce(duration), photo: (options) run(() takePhoto(options)), album: (options) run(() pickFromAlbum(options)), scan: (options) run(() scanCode(options)) } }run只包异步能力振动是同步返回布尔值不放进 loading。error保存最后一条错误信息页面可以统一 toast不用每个按钮各写一套。locate、photo、album、scan都返回 Promise调用方用try/catch或.catch接住避免未处理拒绝。真机联调时按下面这张表走一遍比在代码里猜快得多。检查项预期表现失败先看devicereadywindow.cordova存在cordova.js是否在 www 根目录定位返回经纬度和 accuracy系统定位开关、应用权限振动点击后设备震动是否在用户手势里调用拍照返回file://路径Camera 插件是否进包、存储权限相册能选图并返回路径相册权限、sourceType 是否写对扫码返回 text 和 format相机权限、formats 是否匹配从那以后我每次接入新插件都先把deviceready、权限和真机日志走一遍再谈页面联调。这套顺序看着笨但能少熬几个晚上。希望帮到你。本文还有配套的精品资源点击获取