Vue+Cordova混合开发：扫码拍照定位原生插件集成与避坑-平芜编程栈

简介：面向Vue前端开发者与需要将Web应用迁移到移动端的团队，聚焦Vue与Cordova集成后的原生能力调用，覆盖地理位置获取、手机振动、相机拍照与相册选取、二维码扫描等常见场景，并涉及插件配置、权限申请、平台兼容与真机调试等实践要点。压缩包约14.48MB，文件总数显示为0，文件类型明细暂未提供，因此更适合按已有目录与说明自行核对内容。已有534人学习，说明该主题在跨平台移动开发中具有一定关注度。读者可从中了解Cordova插件与Vue组件结合的典型组织方式，梳理定位、相机、振动和扫码功能的接入思路，并参考权限处理、不同平台参数调整及真机运行中的排错方向，适合具备Vue基础、希望补齐原生能力集成经验的中级开发者查阅。

1. 从 H5 退到原生壳：Vue 项目拿不到扫一扫时的那条路

产品需求评审上写得很轻松：页面里加个「扫码签到」和「拍照上传」，定位顺手带一下。真到 Vue 里写的时候才发现，浏览器给的navigator.geolocation精度看运气，室内漂个几百米很正常；getUserMedia拍照在部分 WebView 里被拦；扫一扫更是没什么可用的原生入口，BarcodeDetector的兼容面窄得没法上生产。这时候把 Vue 打包产物塞进 Cordova 壳，用插件去调系统相机、扫码组件和定位服务，是成本最低的一条路——前端代码几乎不动，能力却从浏览器沙箱换到了系统层。这套方案适合已经在用 Vue 做业务、又必须落地到安卓和 iOS 安装包里的团队，尤其是做巡检、门店签到、仓储盘点这类「拍照 + 扫码 + 定位」三件套都要的场景。下面就按我实际搭过一遍的顺序，从工程接进去讲到参数怎么调、坑在哪。

2. 把 Vue 产物塞进 Cordova 壳：构建链改造与插件注入

2.1 为什么让 Vue 直接输出到 www，而不是每次手动拷 dist

很多人第一步是把npm run build出来的dist整个复制进 Cordova 工程的www目录，跑一次可以，跑三次就开始出问题：忘了删旧文件、多份 hash 资源堆在一起、index.html引用的还是上一次的 chunk 名。正确的做法是让 Vue 的构建产物直接落到壳工程的www，让 Cordova 的prepare阶段看到的就是最新的东西。

改动集中在vue.config.js，核心是两处：输出目录指向壳工程的www，以及publicPath必须改成相对路径。

// vue.config.js const path = require('path') module.exports = { // 关键点一：Cordova 用 file:// 或自定义 scheme 加载页面， // 绝对路径 /js/app.js 会解析失败，必须走相对路径 publicPath: '', // 关键点二：产物直接写进壳工程，省掉手动拷贝 outputDir: path.resolve(__dirname, '../cordova-shell/www'), // 调试期关掉 sourcemap，避免 www 里堆一堆 .map 拖慢 prepare productionSourceMap: false, // 资源文件名带 hash，防止 WebView 缓存住旧版本 filenameHashing: true, }

publicPath设成空字符串是这套组合里最容易被跳过的一步。它决定了打包后index.html里引用资源的前缀，默认的/在浏览器里没问题，在 Cordova 的本地容器里就是 404，页面白屏但控制台不一定报得清楚。改成空串后引用变成js/chunk-vendors.xxxx.js这种相对形式，壳才能找到文件。outputDir用绝对路径是因为vue.config.js的执行目录是 Vue 工程根目录，写相对路径容易算错一层。

如果团队用的是 Vite，对应的是base: './'和build.outDir，逻辑一样。改完之后每次构建完成，壳工程里就是最新的静态资源，cordova prepare会自动把它们同步到各平台的工程目录。

2.2 从空目录到真机可跑：命令逐条拆

壳工程本身不需要什么模板，cordova create生成的骨架够用。下面这串命令是我每次起新项目都会走一遍的，顺序不要乱，插件必须在平台添加之后再装，否则部分插件的原生配置钩子不会执行。

# 1. 全局装命令行工具，版本锁在 12.x，更高版本对旧安卓 SDK 支持反而差 npm install -g cordova@12 # 2. 建壳工程，包名用反域名格式，后面签名和上架都靠它 cordova create cordova-shell com.example.hybrid HybridShell cd cordova-shell # 3. 先加平台，再加插件 cordova platform add android cordova platform add ios # 4. 本轮要用的四个核心插件 cordova plugin add cordova-plugin-geolocation # 定位 cordova plugin add cordova-plugin-vibration # 振动 cordova plugin add cordova-plugin-camera # 拍照 / 相册 cordova plugin add cordova-plugin-barcodescanner # 扫一扫 # 5. 权限与白名单辅助插件，安卓 6.0+ 运行时权限绕不开 cordova plugin add cordova-plugin-android-permissions cordova plugin add cordova-plugin-whitelist # 6. 构建，先跑 debug 包验证功能 cordova build android --debug

几个参数值得说清楚。包名com.example.hybrid里不要出现连字符和大写，安卓的applicationId对字符有要求，改了包名之后所有插件的原生注册也要重来一遍，所以最好一开始就定死。cordova platform add时不带版本号会拉最新，如果团队里有人的 JDK 是 11，而最新平台要求 17，构建会直接失败，稳妥点的做法是显式写cordova platform add android@12。

cordova-plugin-barcodescanner这个名字要注意，社区里还有个phonegap-plugin-barcodescanner，那个已经多年不维护，在新版安卓上编译会报 Gradle 相关错误。我一般统一用前者，接口是cordova.plugins.barcodeScanner.scan，下面的调用代码都按这个来。

构建完成后产物在platforms/android/app/build/outputs/apk/debug/，装到真机上跑。模拟器上定位和相机都是假的，验证不了任何东西，这一点后面还会再提。

2.3 config.xml 与权限声明：插件装完不等于能用

插件安装只是把原生代码链接进来，真正决定「能不能用」的是平台配置文件里的权限声明。安卓侧在platforms/android/app/src/main/AndroidManifest.xml，iOS 侧在platforms/ios/*/项目名-Info.plist。这两处如果缺声明，调用会静默失败或者直接崩，而且报错信息往往和真实原因差得很远。

config.xml里可以集中写一部分偏好设置，省得每次prepare都被覆盖：

<!-- config.xml 片段 --> <widget id="com.example.hybrid" version="1.0.0"> <content src="index.html" /> <!-- 允许 WebView 加载 https 和本地 file 资源 --> <allow-navigation href="https://*/*" /> <allow-intent href="tel:*" /> <allow-intent href="mailto:*" /> <!-- 安卓：允许混合内容，老项目 http 接口多的时候要开 --> <preference name="scheme" value="app" /> <preference name="hostname" value="localhost" /> <!-- iOS：相机与相册的用途描述，缺了会直接被系统拒绝 --> <edit-config file="*-Info.plist" mode="merge" target="NSCameraUsageDescription"> <string>用于拍摄现场照片并上传</string> </edit-config> <edit-config file="*-Info.plist" mode="merge" target="NSPhotoLibraryUsageDescription"> <string>用于从相册选择照片</string> </edit-config> <edit-config file="*-Info.plist" mode="merge" target="NSLocationWhenInUseUsageDescription"> <string>用于记录当前签到位置</string> </edit-config> </widget>

edit-config这个写法比手动改 plist 靠谱，因为cordova prepare会重写平台目录，手改的内容下一次构建就没了，写进config.xml才会持续生效。安卓那侧的权限也可以这样声明：

<!-- 安卓权限，写在 config.xml 的 platform 节点里 --> <platform name="android"> <config-file target="AndroidManifest.xml" parent="/*"> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.CAMERA" /> <uses-feature android:name="android.hardware.camera" android:required="false" /> </config-file> </platform>

uses-feature那行的required="false"是个细节：如果不写，Google Play 会认为你的应用强依赖相机硬件，没有摄像头的平板和部分设备就装不了。业务上如果相机只是可选项，这里必须设成 false。

2.4 deviceready 之前调用插件都是白搭

这是整个集成里最经典的翻车点。Cordova 的原生桥接是异步注入的，页面DOMContentLoaded触发的时候，cordova.plugins这个对象可能还不存在。直接写着navigator.camera.getPicture(...)，在快的机器上偶尔能跑，在慢的机器上就是undefined is not a function。

标准做法是等deviceready事件，但在 Vue 里到处写事件监听太散，我一般把它封成一个只 resolve 一次的 Promise，挂到全局或者通过 provide 注入。

// src/native/bridge.js let readyPromise = null export function whenReady() { if (readyPromise) return readyPromise readyPromise = new Promise((resolve) => { // 非 Cordova 环境（比如浏览器里跑 dev），直接放行，走降级逻辑 if (!window.cordova) { resolve(false) return } // deviceready 可能在脚本加载前就触发过了，用 document 上的事件兜底 document.addEventListener( 'deviceready', () => resolve(true), { once: true } ) }) return readyPromise }

这个函数返回布尔值而不是抛错，是故意的。本地开发时在浏览器里跑 Vue，window.cordova为 undefined，返回 false，上层逻辑就知道该走 H5 降级路径，而不是让整个页面挂掉。{ once: true }保证监听只执行一次，避免热更新时重复注册。

在main.js里，可以在new Vue()之前先启动这个 Promise，但不阻塞渲染：

// src/main.js import Vue from 'vue' import App from './App.vue' import { whenReady } from './native/bridge' // 挂到原型上，业务组件里通过 this.$nativeReady 取用 whenReady().then((isNative) => { Vue.prototype.$isNative = isNative }) new Vue({ render: (h) => h(App) }).$mount('#app')

注意这里没有await阻塞挂载，原因是混合应用首屏白屏时间本来就敏感，等桥接就绪再渲染会明显拖长。让页面先出来，原生能力在需要的时候再判断，体验会好很多。

3. 定位：三条取点路径与精度参数

3.1 三种取点方式，选哪个取决于你要什么

Cordova 体系里能拿到位置的方式有三条，接口长得像，实际行为差别不小。

第一条是直接用navigator.geolocation.getCurrentPosition。装了cordova-plugin-geolocation之后，这个 Web API 会被插件接管，底层走的是系统的定位服务，而不是浏览器的粗略实现。这是最省事的一条，单次取点，成功就返回，失败给错误码。

第二条是navigator.geolocation.watchPosition，持续监听位置变化。适合做轨迹记录、导航或者「距离目标还有多少米」的实时提示。它的代价是持续耗电，而且在高精度模式下会把 GPS 一直唤醒，用户手机发烫就是这么来的。

第三条是插件额外暴露的原生能力，比如安卓上的navigator.geolocation.getCurrentPosition配合enableHighAccuracy会走 GPS provider，而关掉它走的是网络 provider。某些版本里插件还提供了LocationServices相关接口去做开关检测，但跨平台一致性一般，我不太依赖。

选型上我的一般原则：签到、打卡、上报位置这类只取一次的场景，用第一条加合理的超时；需要显示「边走边更新距离」的，用第二条但把maximumAge设成 5 秒以上，不要timeout: 0那种写法，否则回调会疯狂触发；只做城市级别展示的，直接关掉高精度，用网络定位，速度快、耗电低，用户感知不到那点精度差。

3.2 封装一个带超时、缓存与降级的定位服务

直接用原生回调写业务代码，错误处理会散得到处都是。我习惯包一层 Promise，并且内置一次降级重试：高精度拿不到的时候自动退到低精度再试一次，绝大多数「定位失败」的报障都靠这一步救回来。

// src/native/geo.js import { whenReady } from './bridge' // 第一档：高精度，GPS 优先，超时 10 秒 const HIGH = { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 } // 第二档：低精度，网络定位，允许用 5 分钟内的缓存 const LOW = { enableHighAccuracy: false, timeout: 8000, maximumAge: 300000 } function getOnce(options) { return new Promise((resolve, reject) => { navigator.geolocation.getCurrentPosition(resolve, reject, options) }) } export async function getPosition() { const isNative = await whenReady() if (!isNative) { // 浏览器环境走原生 API，行为可能不一致，仅供开发联调 return getOnce(LOW) } try { return await getOnce(HIGH) } catch (err) { // 错误码 3 是 TIMEOUT，2 是 POSITION_UNAVAILABLE，1 是权限拒绝 // 权限拒绝重试没有意义，直接抛出去让上层引导用户去设置页 if (err && err.code === 1) throw err return await getOnce(LOW) } } // 坐标系转换：WGS84 -> GCJ-02，落图前必须做，否则会有几百米偏移 export function wgs84ToGcj02(lng, lat) { const PI = 3.1415926535897932384626 const a = 6378245.0 const ee = 0.00669342162296594323 const outOfChina = lng < 72.004 || lng > 137.8347 || lat < 0.8293 || lat > 55.8271 if (outOfChina) return [lng, lat] const transformLat = (x, y) => { let ret = -100.0 + 2.0 * x + 3.0 * y + 0.2 * y * y + 0.1 * x * y + 0.2 * Math.sqrt(Math.abs(x)) ret += ((20.0 * Math.sin(6.0 * x * PI) + 20.0 * Math.sin(2.0 * x * PI)) * 2.0) / 3.0 ret += ((20.0 * Math.sin(y * PI) + 40.0 * Math.sin((y / 3.0) * PI)) * 2.0) / 3.0 ret += ((160.0 * Math.sin((y / 12.0) * PI) + 320 * Math.sin((y * PI) / 30.0)) * 2.0) / 3.0 return ret } const transformLng = (x, y) => { let ret = 300.0 + x + 2.0 * y + 0.1 * x * x + 0.1 * x * y + 0.1 * Math.sqrt(Math.abs(x)) ret += ((20.0 * Math.sin(6.0 * x * PI) + 20.0 * Math.sin(2.0 * x * PI)) * 2.0) / 3.0 ret += ((20.0 * Math.sin(x * PI) + 40.0 * Math.sin((x / 3.0) * PI)) * 2.0) / 3.0 ret += ((150.0 * Math.sin((x / 12.0) * PI) + 300.0 * Math.sin((x / 30.0) * PI)) * 2.0) / 3.0 return ret } let dLat = transformLat(lng - 105.0, lat - 35.0) let dLng = transformLng(lng - 105.0, lat - 35.0) const radLat = (lat / 180.0) * PI let magic = Math.sin(radLat) magic = 1 - ee * magic * magic const sqrtMagic = Math.sqrt(magic) dLat = (dLat * 180.0) / (((a * (1 - ee)) / (magic * sqrtMagic)) * PI) dLng = (dLng * 180.0) / ((a / sqrtMagic) * Math.cos(radLat) * PI) return [lng + dLng, lat + dLat] }

降级逻辑的关键在错误码判断。code === 1是用户明确拒绝了权限，这种情况重试一万次也没用，必须引导用户去系统设置里开权限，所以直接抛。code === 2是位置不可用，通常是室内信号差或者刚开机 GPS 还没热起来。code === 3是超时。后两种都值得用低精度再试一次，网络定位在室内反而更稳。

坐标系那段是另一个必须做的事。系统定位给的是 WGS84，国内地图服务商在地图上展示时用的是经过偏移的坐标系，直接把原始经纬度打到地图上，人会显示在几百米外的另一条街上。outOfChina那段判断是为了境外场景不误伤，境外不偏移。这个转换函数对流式接口来说有点长，实际项目里可以抽成单独的 utils 文件按需引入。

3.3 enableHighAccuracy 什么时候该关掉

三个参数的组合基本决定了定位体验的好坏，我把常用配置整理成一张表，实际调参的时候对照着改就行。

参数	含义	签到场景推荐值	轨迹场景推荐值	说明
enableHighAccuracy	是否优先使用 GPS	true（失败降 false）	true	开启后首次定位明显变慢，室内可能失败
timeout	超时毫秒数	10000	15000	设太短会频繁超时，设太长用户干等
maximumAge	可接受的缓存年龄	0	5000	0 表示必须重新取，适合签到防作弊
watchPosition 间隔	仅在持续监听时有意义	不适用	3000~5000	太密会导致高频率回调与耗电

maximumAge: 0在签到类业务里是硬要求。如果允许用缓存，用户拿着五分钟前的位置在另一个地方打卡，业务上就算作弊。但在「附近的店」这种查询类场景，缓存五到十分钟完全没问题，还能省一次 GPS 唤醒。

timeout和enableHighAccuracy是互相牵制的。开了高精度又只给 5 秒超时，室内基本必然失败。我的经验值是高精度配 10 到 15 秒，低精度配 5 到 8 秒，让降级链条有足够时间走完。

还有一点容易忽略：连续调用getPosition时，如果上一次请求还没返回就又发起新的，部分安卓机型上会出现回调错乱，返回的是第一次的位置。常见做法是加一个正在请求中的标记，前一次没结束就复用同一个 Promise，别并发。

3.4 国内坐标系这件事，别等到上线才发现偏移

前面代码里已经带了转换，这里补充一下判断依据。插件和系统返回的经纬度是 WGS84；国内的地图 SDK 在渲染时会做一次非线性偏移，得到 GCJ-02。如果你的业务是「把坐标展示在地图上」或者「用坐标做逆地理编码查地址」，那必须转。如果只是「把坐标原样存库、后续两个坐标算距离」，反而不需要转，因为两点都在同一坐标系里，距离差是自洽的。

判断方法很简单：拿同一个点，一次显示在系统自带地图上，一次显示在业务用的地图组件里，如果相差几百米，那就是坐标系没对齐。这个坑的麻烦之处在于它在开发阶段不暴露——开发同学在办公室测，位置本来就飘，看不出是偏移还是精度问题。等到了外场才发现，返工成本高。

4. 振动、拍照、扫一扫：三个原生能力的调用与降级

4.1 振动：一行调用，三种失败姿态

振动是这几个能力里代码最短的，但兼容性反而是最容易踩的。接口本身很简单：

// src/native/haptic.js import { whenReady } from './bridge' /** * @param {number[]} pattern 振动序列，单位毫秒 * 奇数位是振动时长，偶数位是间隔时长 * @returns {Promise<boolean>} 是否真正触发 */ export async function vibrate(pattern = [200]) { const isNative = await whenReady() // 优先走插件接口，Cordova 环境下 navigator.vibrate 会被插件接替 if (isNative && navigator.vibrate) { try { const ok = navigator.vibrate(pattern) return ok !== false } catch (e) { return false } } // 浏览器环境：部分桌面浏览器支持，多数不支持，静默失败 if (navigator.vibrate) { return navigator.vibrate(pattern) } return false }

pattern的语义要记牢：数组里奇数下标是「振多久」，偶数下标是「停多久」。[200, 100, 200]表示振 200 毫秒、停 100 毫秒、再振 200 毫秒。只传一个数字就是一次连续振动。传 0 或者空数组是取消当前振动，扫码成功后想中断一个长振动就用这个。

三种失败姿态分别对应三类设备。第一种是设备根本没有振动马达，比如部分低端平板和模拟器，navigator.vibrate存在但返回 false，代码里必须判断返回值，不能假定一定成功。第二种是 iOS 的限制，较老的 iPhone 机型对网页触发的振动支持很差，振动时长会被系统裁剪得很短，看起来像「没反应」。第三种是系统设置里用户关了「振动反馈」，这种属于用户主动选择，不该报错打扰。

所以振动这个能力，正确的用法是当作战术反馈，而不是当作信息传递。扫码成功振一下、提交失败振两下，用户能感知到就够了；如果业务要求「必须让用户知道」，还是得配一个视觉提示，别指望振动。

4.2 拍照与相册：destinationType 选错，内存直接爆

相机插件的参数比想象中多，其中影响最大的就是返回格式。Camera.DestinationType有两个常用值：DATA_URL返回 base64 字符串，FILE_URI返回本地文件路径。新手最容易顺手选DATA_URL，因为可以直接塞进<img src>，但一张 4000×3000 的照片转成 base64 之后字符串长度能到十几兆，iOS WebView 在这种量级下很容易被系统回收。

// src/native/camera.js import { whenReady } from './bridge' /** * @param {'camera'|'gallery'} source 拍摄来源 * @param {object} opts 覆盖默认参数 */ export async function takePhoto(source = 'camera', opts = {}) { await whenReady() const defaults = { quality: 70, // 压缩质量，70 是肉眼几乎无损的平衡点 targetWidth: 1280, // 限制长边，直接决定最终文件大小 targetHeight: 1280, correctOrientation: true, // 修正拍照方向，安卓上必须开 saveToPhotoAlbum: false, // 拍照后是否存入系统相册 destinationType: Camera.DestinationType.FILE_URI, sourceType: source === 'camera' ? Camera.PictureSourceType.CAMERA : Camera.PictureSourceType.PHOTOLIBRARY, encodingType: Camera.EncodingType.JPEG, mediaType: Camera.MediaType.PICTURE, } const options = { ...defaults, ...opts } return new Promise((resolve, reject) => { navigator.camera.getPicture( (result) => resolve({ path: result, isFileUri: options.destinationType === Camera.DestinationType.FILE_URI }), (err) => { // 用户主动取消不是错误，单独标记，避免上层弹错误提示 if (typeof err === 'string' && err.indexOf('cancel') > -1) { resolve(null) return } reject(err) }, options ) }) }

targetWidth和targetHeight是控制体积最有效的手段，比事后压缩靠谱得多。1280 这个值对上传凭证照片足够，如果业务要看细节（比如设备铭牌），可以提到 1920，但别超过 2048，再大安卓的低内存机型在解码时就会出问题。

correctOrientation: true这行在安卓上不开的话，竖着拍的照片显示时会是横的。原因是相机传感器方向和屏幕方向不一致，系统把方向信息写进了 EXIF，但很多 WebView 不读 EXIF。开了之后插件会在原生侧把图像旋转好再返回，代价是多一次处理耗时。

FILE_URI返回的路径形如file:///storage/emulated/0/...，在 Vue 里直接绑定到img的src，在 Cordova 的 WebView 里通常能显示。但如果项目用了cordova-plugin-ionic-webview或者自定义了 scheme，file://会被拦截，显示成白板。这时候要用cordova-plugin-file的resolveLocalFileSystemURL转成本地 URL，或者干脆读成 base64 再展示。这个坑后面还会展开。

4.3 扫一扫：从插件选型到扫码格式约束

扫一扫的接口调用很短，难点全在参数和权限上：

// src/native/scanner.js import { whenReady } from './bridge' /** * @param {object} opts 覆盖项 * @returns {Promise<{text: string, format: string, cancelled: boolean}|null>} */ export async function scanCode(opts = {}) { await whenReady() const defaults = { preferFrontCamera: false, showFlipCameraButton: true, // 允许切前后摄，仓库盘点经常要扫高处 showTorchButton: true, // 暗光环境必备 torchOn: false, saveHistory: false, // 扫码历史涉及业务数据，默认不存 prompt: '把二维码放入框内', resultDisplayDuration: 200, // 结果显示时长，0 表示不显示直接返回 orientation: 'portrait', // 限定格式可以明显提速，格式列表越长识别越慢 formats: 'QR_CODE,CODE_128,EAN_13', } const options = { ...defaults, ...opts } return new Promise((resolve, reject) => { cordova.plugins.barcodeScanner.scan( (result) => { if (result.cancelled) { resolve(null) return } resolve({ text: result.text, format: result.format, cancelled: false, }) }, (err) => reject(err), options ) }) }

formats这个参数值得单独说。默认情况下插件会尝试识别所有支持的码制，识别率是上去了，但速度会慢，尤其在光线不好的时候。仓库场景里码制是固定的（一般是 Code128 或 QR），把列表收窄到两三种，识别速度能快一截，误识别的概率也低。

resultDisplayDuration设成 200 毫秒是我自己的习惯。设成 0 的话扫码框闪一下就关，用户来不及确认扫到的是不是对的那个；设太大又要多点一次。200 毫秒刚好能看清结果又不卡流程。

权限这块，安卓 6.0 以后 CAMERA 是危险权限，必须运行时申请。虽然扫码插件内部通常会自己弹，但如果应用启动时已经申请过相机权限（比如拍照功能先触发），重复申请可能被系统忽略。稳妥做法是在应用启动后主动检查一次权限状态：

// src/native/permission.js export function ensureCameraPermission() { return new Promise((resolve) => { // 非安卓平台直接放行，iOS 由系统弹窗接管 if (!window.cordova || !cordova.plugins.permissions) { resolve(true) return } const perms = cordova.plugins.permissions perms.checkPermission(perms.CAMERA, (status) => { if (status.hasPermission) { resolve(true) return } perms.requestPermission(perms.CAMERA, (s) => resolve(!!s.hasPermission), () => resolve(false)) }, () => resolve(false)) }) }

这里没有用async/await混写，是因为权限插件的回调风格在部分版本里不太稳定，用最朴素的回调包一层 Promise 反而更可靠。返回布尔值而不是抛异常，上层就能决定是提示用户去设置页，还是直接降级成手动输入编码。

4.4 把四个能力收进一个 native 服务

业务组件里直接import四个文件有点散，我一般再包一层统一出口，顺便把「非原生环境」的降级逻辑集中处理：

// src/native/index.js export { whenReady } from './bridge' export { getPosition, wgs84ToGcj02 } from './geo' export { vibrate } from './haptic' export { takePhoto } from './camera' export { scanCode } from './scanner' export { ensureCameraPermission } from './permission' // 统一的错误码翻译，避免每个页面各写一套提示文案 export function describeError(err) { const map = { 1: '定位权限被拒绝，请到系统设置中开启', 2: '暂时无法获取位置，请到空旷处重试', 3: '定位超时，请检查网络或稍后重试', } if (typeof err === 'number') return map[err] || '未知错误' if (err && err.code) return map[err.code] || err.message || '未知错误' return String(err || '未知错误') }

这层出口的价值在于改一处、全站生效。比如后来发现某机型上超时时间要统一调长，只改geo.js里的常量就行，业务页面完全不用动。错误文案集中在一处，也避免了「同一个定位失败，三个页面三种说法」的尴尬。

5. 避坑与排查：真机上五个高频翻车现场

5.1 插件装了、代码也写了，回调就是不进

现象：真机上点按钮毫无反应，控制台干干净净，加console.log也打不出来，像是函数根本没被调用。

原因：九成是deviceready之前就执行了插件调用。Vue 的组件mounted触发时机远早于原生桥接就绪，尤其首屏组件，几乎必然踩中。另一种可能是插件安装时没加平台，cordova plugin add在platform add之前执行，原生代码没有链接进去，JS 侧的对象存在但调用是空壳。

解决：所有插件调用前统一走whenReady()，这一点前面已经封好了。排查时可以打开 Safari 或 Chrome 的远程调试，看window.cordova是否存在；不存在就是桥接没就绪，存在但cordova.plugins.xxx是 undefined，就回去检查cordova plugin list的输出，确认插件和平台都在。

5.2 安卓 10 以上定位一直返回权限拒绝

现象：getPosition每次都进错误回调，错误码 1，但应用设置里明明给了定位权限。

原因：安卓 10 引入了「仅在使用中允许」的分级，安卓 12 之后又多了「精确位置」和「粗略位置」两个开关。如果用户只给了粗略位置，而代码里请求的是enableHighAccuracy: true，部分机型会直接判为权限不足。另一个常见原因是清单里只声明了ACCESS_COARSE_LOCATION没声明ACCESS_FINE_LOCATION，系统按最小权限授予。

解决：清单里两个权限都写上，运行时申请时也两个一起要。代码层面把高精度请求失败后的降级路径保留好，前面那段封装已经处理了。测试时必须用真机，模拟器的定位是伪造的，权限弹窗行为也不一致，测不出这个问题。

5.3 拍照返回 FILE_URI，img 标签显示白板

现象：相机能打开、能拍、回调也拿到了路径，但页面上<img :src="path">是空白，控制台报「Not allowed to load local resource」。

原因：WebView 的安全策略不允许页面直接加载file://资源，尤其在改过 scheme 或者装了自定义 WebView 插件之后。另外安卓 10 的分区存储也让部分路径的访问权限收紧了。

解决：两条路。一是改用DATA_URL返回 base64，代价是内存，必须配合targetWidth压到 1280 以内；二是保留FILE_URI，用cordova-plugin-file的resolveLocalFileSystemURL拿到FileEntry，再file()读成 Blob，用URL.createObjectURL生成可访问地址。后一种内存占用低，适合一次选多张图的场景，但要多引一个插件。

5.4 扫一扫打开黑屏，关掉再打开就正常

现象：第一次点扫码，摄像头预览区域全黑，退出重进就好了，或者切一下前后摄像头也能恢复。

原因：摄像头资源被上一次的页面占用还没完全释放。Vue 的组件销毁不等于原生相机释放，如果扫码页是路由跳转进来的，上一个页面里如果也开过相机（比如拍照组件），资源冲突就出现了。部分机型上还和orientation参数有关，横竖屏切换时预览尺寸计算错误。

解决：在扫码页的beforeDestroy里加一个延迟，确保原生侧完全退出后再允许下一次调用；或者把扫码和拍照做成互斥的，同一时间只允许一个相机能力存在。orientation显式写成portrait，别依赖默认值。

5.5 debug 包一切正常，release 包反而崩

现象：开发阶段用 debug 包测了半个月都没问题，打出 release 包给测试，一进去就闪退或者功能失效。

原因：release 构建会开启代码压缩和资源混淆，Vue 打包时的 chunk 名、插件注册的反射类名都可能被改。另一个常见原因是签名变了，部分系统能力（比如某些权限组）对签名有校验。还有一种是config.xml里的偏好设置在 release 下走了不同分支。

解决：release 包必须单独回归一遍，不能拿 debug 的结论直接用。打 release 前把vue.config.js里的productionSourceMap打开一次，出问题能定位到源码行；发布时再关掉。安卓侧检查build.gradle里的minifyEnabled，如果开了混淆，插件用到的类要加 keep 规则。

6. 最后一步：把插件返回值摊开看

调试这类混合应用，最省时间的做法不是猜，而是把每个插件的真实返回值打印出来。我在每个项目的首页都留了一个隐藏入口（连点标题五次触发），点开是一个自检面板，把设备信息、权限状态、定位原始返回、相机能力逐条列出来。这个面板救过我很多次——有次定位一直失败，面板里显示enableHighAccuracy请求下返回的coords.accuracy是 3000 米，才意识到是那台测试机根本没有 GPS 模块，一直在走网络定位。

// src/components/DebugPanel.vue 的核心逻辑片段 export default { data() { return { rows: [], } }, methods: { async runSelfCheck() { const rows = [] // 1. 环境 rows.push({ key: 'cordova', value: String(!!window.cordova) }) rows.push({ key: 'platform', value: window.cordova?.platformId || 'web' }) rows.push({ key: 'version', value: window.cordova?.platformVersion || '-' }) // 2. 定位原始返回，不做任何加工 try { const pos = await new Promise((res, rej) => navigator.geolocation.getCurrentPosition(res, rej, { enableHighAccuracy: true, timeout: 10000, maximumAge: 0, }) ) rows.push({ key: 'lat/lng', value: `${pos.coords.latitude},${pos.coords.longitude}` }) rows.push({ key: 'accuracy', value: `${pos.coords.accuracy} m` }) rows.push({ key: 'provider', value: pos.coords.altitudeAccuracy ? 'gps' : 'network' }) } catch (e) { rows.push({ key: 'geo_error', value: `code=${e.code}` }) } // 3. 相机能力探测 rows.push({ key: 'camera', value: window.Camera ? Object.keys(Camera.DestinationType).join('/') : 'unavailable', }) this.rows = rows }, }, }

把coords.accuracy打出来这个习惯，是从一次外场排查里养成的。当时业务反馈「定位不准」，开发在办公室复现不了，到了现场才发现精度值一直是 2000 以上，说明设备压根没拿到 GPS 信号，一直在用基站定位。如果只看经纬度，永远看不出这个问题。

打包前的自检清单，我贴在项目根目录的 README 里，每次发版前对着走一遍：

检查项	判断标准	常见疏漏
publicPath	打包后 index.html 引用为相对路径	忘了改，白屏
权限声明	清单与 plist 里定位、相机、相册齐全	只在代码里申请，没写清单
deviceready	所有插件调用前都经过 whenReady	首屏组件直接调
图片尺寸	targetWidth 不超过 2048	原图直传，低端机 OOM
扫码格式	formats 只保留业务需要的	全格式开，慢且误识
release 回归	用正式签名包完整跑一遍	只测 debug 包