Meteor 移动端开发完全指南基于 Cordova 的 iOS/Android 应用构建、调试与发布【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor导读本文以 Meteor 官方指南中的 Cordova 章节为核心系统讲解如何利用 Meteor 与 Apache Cordova 的深度集成从同一套 Web 代码库构建、运行、调试并发布 iOS 与 Android 移动应用。读完本文你将掌握移动开发环境的搭建、meteor run ios/android-device的真机联调流程、移动端热代码推送Hot Code Push的机制与兼容版本控制、Cordova 原生插件的安装与使用以及将应用打包签名并提交至 App Store 和 Play Store 的完整链路。Meteor 与 Cordova 的集成方式Cordova 是 Apache 基金会旗下的知名开源项目Meteor 通过与其集成允许开发者使用与常规 Web 应用完全相同的代码库构建移动应用。guide/source/cordova.md开篇即点明借助 Meteor 的 Cordova 集成你只需要几条命令就能把现有应用运行到 iOS 或 Android 设备上。什么是 Cordova 应用一个 Cordova 应用本质上是使用 HTML、CSS 和 JavaScript 编写的 Web 应用但它不是运行在独立的移动浏览器中而是运行在**原生应用内嵌的 Web View网页视图**中。将 Web 应用打包为 Cordova 应用有两个显著收益资源随包携带所有静态资源都打包在应用内加载速度远快于从远程服务器拉取页面这对慢速移动网络下的用户体验至关重要支持热代码推送Meteor 集成支持热代码推送无需经过应用商店的审核流程即可向用户设备推送代码更新。此外Cordova 通过插件架构开放了 Web 应用通常无法访问的原生设备能力例如相机、本地文件系统、条码/NFC 读取器等。PhoneGap 与 Cordova 的关系文档中特别解释了常被混淆的 PhoneGap 概念PhoneGap 是 Adobe 自 2011 年收购 NitobiCordova 项目的原始创造者后使用的产品名。2012 年 Adobe 将代码捐赠给 Apache 以确保更开放的管理模式开源项目随之更名为 Cordova。如今 PhoneGap 只是 Cordova 的众多发行版之一与 Ionic、Telerik、Monaca、Intel XDK 等并列。这些发行版主要区别在于工具链和云服务集成底层平台与插件是共享的——从这个意义上说Meteor 本身也可以被视为一种 Cordova 发行版。在 Meteor 中的工作原理使用 Meteor 时你无需自行安装 Cordova也不需要直接使用cordova命令。Cordova 项目的创建发生在 Meteor 的run和build命令内部生成的项目位于应用目录下的.meteor/local/cordova-build属于可随时删除重建的构建产物。与直接修改 Cordova 的config.xml不同Meteor 读取应用根目录下的mobile-config.js文件根据其中指定的配置来生成原生项目。值得注意的是Cordova 应用并不通过网络加载 Web 内容而是依赖本地存储的 HTML、CSS、JavaScript 及其他资源。标准 Cordova 默认使用file://URL 加载应用但 Meteor 在设备端集成了文件服务机制同时支持初始资源的打包和热代码推送的增量更新——这意味着你的应用实际从http://localhost:port提供服务。这带来一个额外好处Web View 会将其视为安全源secure origin不会屏蔽诸如摄像头、地理位置等敏感功能这些功能对file://URL 的限制日益严格。服务端口的确定机制本地服务端口由应用 ID 生成该 ID 存储在应用的.meteor/.id文件中。若需在同一设备上基于同一份源码同时运行多个应用必须在run和build命令中通过--cordova-server-port port为每个运行中的应用指定不同端口否则 iOS 上将无法同时运行多个应用常见症状是 Xcode 控制台报错Failed binding IPv4 listening socket: Address already in use (48)。文档还详细解释了为何不采用固定端口或随机端口固定端口会在同一设备运行多个 Meteor Cordova 应用时产生冲突随机端口则存在严重缺陷若每次运行端口都变化依赖 origin 的 Web 特性如缓存、localStorage、IndexedDB将无法在多次运行间持久化也无法指定稳定的 OAuth 重定向 URL。因此 Meteor 从预定范围12000–13000中选取端口依据每个 Meteor 项目独有的appId计算得出确保同一应用始终使用同一端口同时尽可能避免应用间冲突理论上仍存在所选端口被占用的可能此时本地服务器启动会失败。运行环境iOS 与 Android 的 Web ViewCordova 应用运行在 Web View即去掉浏览器界面的浏览器中不同浏览器引擎对 Web 标准的支持差异会直接影响应用性能与可用特性。iOS 端iOS 的浏览器是 Safari基于开源 WebKit 项目。Meteor 在 iOS 8 和 iOS 9 上均默认使用WKWebView——iOS 8 引入的现代 WebKit API取代了自 iOS 诞生即存在的 UIWebView。WKWebView 的核心优势是运行在独立进程中可利用 JIT即时编译获得显著更高的 JavaScript 性能某些基准测试中为 3–4 倍而 UIWebView 因安全原因与应用同进程运行、无法使用 JIT。文档同时提醒iOS 8 的 WKWebView 不允许从本地文件系统加载文件这对使用file://URL 的标准 Cordova 应用是个问题但 Meteor 集成从localhost提供资源因此在 iOS 8 和 iOS 9 上均可正常工作。Android 端Android 5.0 及以上自带基于 Chromium 的 Android System Web View可通过 Play Store 自动更新因此 Web View 的升级频率独立于系统更新可以更及时地获得新特性。添加与移除 Cordova 平台每个 Meteor 项目面向一组平台通过meteor add-platform管理# 为项目添加 iOS 平台 meteor add-platform ios # 为项目添加 Android 平台 meteor add-platform android # 同时移除 iOS 和 Android 平台 meteor remove-platform ios android # 列出项目当前面向的平台 meteor list-platforms若本机尚未满足构建移动平台应用的前置条件命令会打印缺失需求清单但平台仍会被添加。你需要补齐这些需求后才能在本机构建和运行移动应用。安装前置条件要在本机构建和运行移动应用需要预先安装相应平台的开发工具链。iOS安装 Xcode构建 iOS 应用需要一台安装了 Apple Xcode 开发工具的 Mac。建议安装最新版本同时查阅 Meteor 更新历史确认是否存在特定版本依赖文档注明若使用 Xcode 10.2 构建webapp 包版本须为 v1.7.4 或更高。meteor add-platform ios会弹出对话框询问是否安装 command line developer tools此时不要选择 Install——构建和运行 iOS 应用需要完整的 Xcode。应选择 Get Xcode 跳转到 Mac App Store 的 Xcode 页面安装也可直接在 Mac App Store 搜索 Xcode。安装完成后还需接受许可协议首次启动 Xcode 会弹出许可协议对话框更快捷的方式是在命令行执行sudo xcodebuild -license accept仍需阅读并理解 Xcode 与 Apple SDKs 协议。启用命令行工具在终端执行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer。另外自 Cordova iOS 4.3.0 起解析 PhoneGap Push Plugin 等依赖可能需要执行sudo gem install cocoapods。AndroidJDK、Android SDK 与环境变量构建 Android 应用需要安装 Java Development Kit (JDK)安装 Android SDK 并下载所需工具、平台等组件最简单的方式是安装 Android Studio设置ANDROID_HOME并将工具目录加入PATH可选创建 Android Virtual Device (AVD) 以在模拟器上运行应用若找不到 Gradle可通过 Homebrew、apt-get或yum安装系统级独立版本# On Mac OSX: brew install gradle # On Debian/Ubuntu: sudo apt-get install gradle注意若要针对 Android SDK 31 开发需要 Java 11 或更高版本并安装最新的 cmdline-tools。安装 JDK可从 Oracle Java 官网选择 Java Platform (JDK) 下载对应平台安装包按向导完成安装。Linux 用户建议使用发行版包管理器Ubuntu 用户可直接用 Ubuntu Make 同时安装 Android Studio 与全部依赖。安装 Android StudioAndroid Studio 首次启动的设置向导会代为安装 Android SDK 并下载默认工具集。若偏好独立安装只需确保安装最新版本的 Android Command Line Tools。需要留意 Android Studio SDK Tools 的版本选择Meteor 1.4.3.1 起Android SDK Tools v25.2.x 或 v26.0.0 及更高版本v25.3.0 无法工作因大量变更所致参见对应 issueMeteor 1.4.2.x 及更早版本Android SDK Tools v23。如需安装旧版 SDK 工具可下载对应版本后替换~/Library/Android/sdk/下的tools/目录。使用 Ubuntu Make 一键安装Ubuntu 14.04 LTS 需先添加 PPAsudo add-apt-repository ppa:ubuntu-desktop/ubuntu-make sudo apt-get update sudo apt-get install ubuntu-make umake android设置ANDROID_HOME与PATHCordova 会自动检测常见位置的 Android SDK但若要在终端使用android、adb等工具需在~/.bash_profile或~/.zshrc等对应 shell 配置文件中加入# Android export ANDROID_HOME$HOME/Library/Android/sdk export PATH$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools之后执行source ~/.bash_profile或重开终端会话使配置生效。可选创建 AVD。当前 Android 模拟器往往较慢且不稳定官方建议优先使用真机。若确需模拟器请用 AVD Manager 创建虚拟设备并确保其 API 级别与所用 Cordova Android 版本支持的级别匹配。Mac M1 特例需安装 JDK 8aarch64 构建、Android SDK 的 ARM 架构版本在 Android Studio 中创建如 Pixel 4 Android 11 (API 30) 的虚拟设备并在~/.bashrc或~/.zshrc中配置export ANDROID_HOME$HOME/Library/Android/sdk export ANDROID_SDK_ROOT${ANDROID_HOME} export PATH${PATH}:${ANDROID_HOME}/emulator export PATH$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools记得用source ~/.zshrc或source ~/.bashrc重载配置并用brew install gradle安装 Gradle。在设备上开发运行开发阶段Meteor 构建工具与 Cordova 协同工作将应用运行到真机、iOS 模拟器或 Android 模拟器上。meteor run在照常启动开发服务器和 MongoDB 实例之外还接受移动目标参数命令目标作用ios在 iOS 模拟器上运行默认模拟设备可打开 Xcode 安装并选择其他模拟设备ios-device打开 Xcode在已连接的 iOS 真机或模拟器上运行android在 Android 模拟器上运行当前模拟器较慢且不稳定官方建议真机或 Genymotion 等替代方案android-device在已连接的 Android 真机上运行可同时指定多个目标例如meteor run ios android-device会同时在 iOS 模拟器和 Android 真机上运行应用。连接服务器Meteor 应用需要连接服务器以加载数据并支持热代码推送。开发期间设备与运行meteor的电脑必须处于同一 WiFi 网络且网络配置不应阻止设备访问服务器可能需要调整防火墙或路由器设置关闭客户端隔离。meteor run会自动检测本机 IP。若检测失败或希望移动应用连接其他服务器可通过--mobile-server选项指定地址。iOS 真机运行步骤若你此前未开发过 iOS 应用或未用该设备做过开发Xcode 解析代码签名时会弹出系列对话框与警告并可能请求访问钥匙串中的密钥此外要在 Apple iOS App Store 发布应用需加入 Apple Developer Program。用 USB 线连接设备到电脑将设备连接到可与服务器通信的 WiFi 网络运行meteor run ios-device在 Xcode 中打开项目在项目导航器中从 Scheme 工具栏菜单选择你的设备点击 Run 按钮Xcode 将构建应用、安装到设备并启动。Android 真机运行步骤用 USB 线连接设备到电脑将设备连接到可与服务器通信的 WiFi 网络按 Android 官方说明将设备设置为开发者模式设备弹出 Allow USB debugging? 时点击 Allow运行meteor run android-device构建、安装并启动应用。可用adb devices检查设备是否正确连接与配置。日志与远程调试全栈移动应用由大量部件组成诊断问题并不容易。日志是追踪应用运行状态、捕捉遗漏告警与错误的基础手段而远程调试——从 SafariiOS或 ChromeAndroid的调试界面直接操作远程设备上的应用——则更为强大。三类日志Meteor Cordova 应用会涉及三种日志服务端日志Meteor 构建系统打印的消息以及服务端代码中console调用的输出客户端 Web 日志Web View 产生的告警与错误以及客户端代码中console调用的输出客户端原生日志系统组件与 Cordova 插件产生的消息也包括热代码推送所用 Meteor 插件更详细的日志。使用meteor run时服务端日志照常打印在终端运行 Android 设备或模拟器还会把一部分日志含客户端console调用输出到同一终端。iOS 则不会在终端显示客户端日志但 Xcode 的 debug console 会照常显示原生日志。可以添加cordova-plugin-console将console调用输出到原生日志Android 默认如此但不推荐——这会带来显著性能开销且远程调试能提供更好更完整的控制台输出。iOS用 Safari 远程调试在Safari Preferences中勾选 Show Develop menu in menu bar在 iOS 设备的Settings Safari Advanced中启用 Web Inspector启动应用后通过Develop 你的设备 你的应用/localhost打开远程调试器由于只能在应用启动后才能连接可能错过启动时的告警与错误可在 Web Inspector 控制台执行location.reload()重新加载应用这次将带远程调试器连接。Android用 Chrome 远程调试参考 Chrome DevTools 官方远程调试说明。同样地应用启动后才能连接可在 DevTools 控制台执行location.reload()重载以捕获启动信息。注意meteor build产出的.apk无法远程调试除非使用meteor build --debug生成调试构建。移动端热代码推送开发期间Meteor 构建工具检测到相关文件变化后会重新编译并通知所有已连接的客户端有新版本可用客户端自动重载应用切换到新代码——这就是热代码推送Hot Code Push。Meteor 在浏览器与移动端都支持热代码推送但移动端流程略有不同。浏览器重载时会重新向服务器请求资源、获得最新版本而 Cordova 应用依赖本地存储的资源因此移动端热代码推送是两步过程使用原生下载机制从服务器下载更新后的资源并存储在设备上页面重载Web View 向本地 Web 服务器重新请求资源。这带来一个重要好处即便移动网络下下载很慢下载也在后台进行Meteor 会等到所有资源都下载完成后才尝试重载应用。下载是增量式的——基于内容哈希只下载真正发生变化的资源。如果因网络故障或应用被关闭而未能一次性下载完所有变更资源下次启动或网络恢复时会复用已下载完成的部分。生产环境中的热代码推送热代码推送对生产应用同样极有价值可以快速向设备推送更新用户无需通过商店更新也无需经过漫长的审核流程。但必须理解其边界热代码推送只能更新 Web 应用的 HTML、CSS、JavaScript 及其他资源原生代码的变更仍须提交新版本到应用商店为避免依赖新原生代码的 JavaScript 被推送到旧客户端Meteor 会根据 Cordova 平台与插件版本计算兼容版本哈希只有精确匹配时才向设备下载新版本。因此插件列表的任何变更、或升级到包含新平台版本的 Meteor 版本都会阻塞对现有移动客户端的推送直到应用从商店更新。此外服务端代码应兼容旧版客户端的请求例如修改数据 schema 或 publication 函数时需考虑向后兼容性。控制兼容版本兼容版本可在meteor run [ios/android]期间通过ROOT_URL/__cordova/manifest.json的cordovaCompatibilityVersions属性查看。若希望热代码推送触达尚未安装最新原生代码的应用可以覆盖兼容版本。假设你在开发 iOS 应用使用插件cordova-plugin-camera2.4.0兼容版本为3ed5b9318b2916b595f7721759ead4d708dfbd46。若升级到2.4.1服务器会生成新兼容版本用户的旧应用将停止接收推送。此时可强制使用旧版本METEOR_CORDOVA_COMPAT_VERSION_IOS3ed5b9318b2916b595f7721759ead4d708dfbd46 meteor run ios-device # or METEOR_CORDOVA_COMPAT_VERSION_IOS3ed5b9318b2916b595f7721759ead4d708dfbd46 meteor build ../build --server127.0.0.1:3000这样用户仍能持续收到推送但直到从商店更新前不会获得新插件版本。本例中因为只是 patch 版本升级、API 未变这样做是安全的但若新增了cordova-plugin-gyroscope并调用navigator.gyroscope.getCurrent()旧应用收到新 JS 代码时会抛出Uncaught TypeError: Cannot read property getCurrent of undefined。另一个方案是使用METEOR_CORDOVA_COMPAT_VERSION_EXCLUDE环境变量将插件从兼容哈希计算中排除meteor add cordova:cordova-plugin-camera4.1.0 meteor add cordova:cordova-plugin-gyroscope0.1.4 METEOR_CORDOVA_COMPAT_VERSION_EXCLUDEcordova-plugin-camera,cordova-plugin-gyroscope meteor run ios-device此时兼容版本不会变化。METEOR_CORDOVA_COMPAT_VERSION_*环境变量必须在通过run、build或deploy构建应用时设置。从源码看这一机制在 tools/isobuild/bundler.js 中实现构建web.cordova架构时cordovaCompatibilityVersions按平台遍历CORDOVA_PLATFORM_VERSIONS读取METEOR_CORDOVA_COMPAT_VERSION_EXCLUDE从插件依赖中剔除指定项再优先使用METEOR_CORDOVA_COMPAT_VERSION_PLATFORM环境变量、否则调用WebAppHashing.calculateCordovaCompatibilityHash计算哈希。该哈希函数在 packages/webapp-hashing/webapp-hashing.js 中实现对平台版本、排序后的插件名与插件版本依次做 SHA1 哈希排序保证了哈希结果与插件声明顺序无关webapp-hashing-tests.js 中的测试也验证了哈希的确定性、顺序无关性与对输入变化的敏感性。最终cordovaCompatibilityVersions随program.json生成并通过 packages/webapp/webapp_server.js 暴露到manifest.json。在应用内读取兼容版本manifest.json中仅反映 JS bundle 版本的version属性可通过__meteor_runtime_config__.autoupdateVersionCordova访问cordovaCompatibilityVersions.*属性则可用cordova-plugin-file从 manifest 文件读取。配置服务器移动应用需要连接服务器以支持热代码推送。生产环境构建时必须用--server选项指定服务器地址该地址用于设置__meteor_runtime_config__中的ROOT_URL定义于应用 bundle 生成的index.html中。同时服务器端也要配置正确的连接地址使用meteor deploy部署到 Galaxy 时会自动完成部署到自有服务器时必须定义ROOT_URL环境变量Meteor Up 可在mup.json中配置。原因在于热代码推送交付的更新会以新生成的index.html替换初始 bundle 中的那份若服务器未设置ROOT_URL其默认为localhost:3000应用将既无法加载数据也无法继续接收推送。Meteor 1.3 起会阻止把ROOT_URL改为localhost的更新代价是配置正确前热代码推送被禁用。从故障版本中恢复热代码推送可能意外推送含错误的代码导致用户得到损坏的应用最坏情况是白屏死机甚至因负责连接服务器的代码不再运行而禁用后续推送。为此 Meteor 会尝试检测故障版本并回滚到最后一个已知良好版本其原理是期望所有Meteor.startup()回调在设定时间内完成否则判定该版本故障并回滚更新。由于服务器可能再次推送该故障版本设备端会将其加入黑名单以避免重试。默认启动超时为 20 秒可通过App.setPreference设置WebAppStartupTimeout调整// 单位是毫秒 App.setPreference(WebAppStartupTimeout, 30000);这一默认值在cordova-plugin-meteor-webapp的原生实现中可见WebAppLocalServer.java 以preferences.getInteger(WebAppStartupTimeout, 20000)读取配置并作为默认启动超时。原生功能与 Cordova 插件Cordova 的插件架构允许访问 Web 应用通常无法使用的原生能力。插件是同时包含 JavaScript 与原生代码的可安装附加组件负责把 Web 应用的调用翻译成平台专属 API。Apache Cordova 项目维护着一组核心插件提供相机、联系人、文件系统等原生设备能力任何人都可以编写 Cordova 插件实现几乎任何原生能力第三方插件生态丰富可在 Cordova 官网或 npm 上检索。需要注意的是核心插件维护良好、与 Cordova 同步更新但第三方插件质量参差不齐且必须确认插件与 Meteor 内置的 Cordova 平台版本兼容。安装插件插件以名称标识通常与 npm 包名一致目前约定以cordova-plugin-开头但并非所有第三方插件都遵循。向项目添加插件与添加 Meteor 包使用同一meteor add命令只需加cordova:前缀且必须指定精确版本meteor add cordova:cordova-plugin-camera1.2.0Meteor 包则通过Cordova.depends()语法声明对 Cordova 插件的依赖例如在包的package.js中Cordova.depends({ cordova-plugin-camera: 1.2.0 });添加该 Meteor 包即会同时安装指定的 Cordova 插件。若多个 Meteor 包以不同版本添加同一插件无法明确判断最终安装哪个版本但直接添加到项目的插件总是覆盖包依赖的同名插件。由于向已含插件的 Cordova 项目安装插件可能导致不确定结果Meteor 会在项目插件发生任何变更时移除并重新添加全部插件。Cordova 从 npm 下载插件并缓存于~/.cordova/lib/npm_cache重建或在其他项目中复用时无需重复下载。兼容性提醒插件版本与 Cordova 平台版本耦合紧密不兼容插件可能引发构建期或运行期错误。Meteor 将核心插件固定到已知可配合内置 Cordova 版本工作的最低版本但该机制不适用于第三方插件需要自行评估。设置插件参数部分插件要求在构建过程设置参数例如com-phonegap-plugins-facebookconnect需要指定APP_ID与APP_NAME。可在mobile-config.js中使用App.configurePlugin设置。从 Git 安装插件若插件有未发布的改动可让 Cordova 从 Git 仓库下载插件代码。但每次重建都会克隆插件仓库速度较慢应尽量避免。与默认 Cordova 不同Meteor 要求指定确切的提交 SHA 哈希而非分支或标签以保证构建可复现也避免因 SHA 相同而重复重装全部插件。语法是前的名称是插件 ID须与插件plugin.xml中声明一致#后为 Git 仓库 URL 附上 SHAmeteor add cordova:com.phonegap.plugins.facebookconnecthttps://github.com/Wizcorp/phonegap-facebook-plugin.git#5dbb1583168558b4447a13235283803151cb04ecMeteor 包同样可依赖 Git 安装的插件Cordova.depends({ com.phonegap.plugins.facebookconnect: https://github.com/Wizcorp/phonegap-facebook-plugin.git#5dbb1583168558b4447a13235283803151cb04ec });从本地文件系统安装插件开发自有插件时从本地文件系统安装便于跟随代码改动。代价是 Meteor 每次构建都会重装全部插件、拖慢速度。Meteor 会以--link选项添加本地插件Cordova 用符号链接而非复制文件安装因此文件改动会直接反映到生成的原生项目如 Xcode 工程可能无需重建。用file://URL 指定路径相对于项目目录解析meteor add cordova:cordova-plugin-underdevelopmentfile://../plugins/cordova-plugin-underdevelopmentMeteor 包同样可以依赖本地插件通常只对本地包有意义Cordova.depends({ cordova-plugin-underdevelopment: file://../plugins/cordova-plugin-underdevelopment });从 tools/cordova/project.js 的源码可见file://方案会在添加插件时传入link: utils.isUrlWithFileScheme(version)这正是本地插件使用符号链接安装的实现依据。移除直接安装的插件meteor remove cordova:cordova-plugin-camera meteor remove cordova:com.phonegap.plugins.facebookconnect meteor remove cordova:cordova-plugin-underdevelopment使用插件依赖 Cordova 插件的功能应包裹在Meteor.startup()块中确保插件已通过监听deviceready事件完成初始化。例如使用 Cordova 地理定位插件// 此处插件可能尚未初始化 navigator.geolocation.getCurrentPosition(success); Meteor.startup(function() { // 此处可以确定插件已初始化 navigator.geolocation.getCurrentPosition(success); });在 JavaScript 中检测 Cordova 环境与Meteor.isServer、Meteor.isClient类似可用Meteor.isCordova区分 Cordova 专属代码if (Meteor.isServer) { console.log(Printed on the server); } if (Meteor.isClient) { console.log(Printed in browsers and mobile apps); } if (Meteor.isCordova) { console.log(Printed only in mobile Cordova apps); }该标志在 packages/meteor/cordova_environment.js 中被硬编码为true只在 Cordova 构建中注入browser_environment.js、server_environment.js中则均为falsecordova_environment_test.js 对此做了断言。此外包可以通过addFiles为不同构建提供不同文件集合api.addFiles(foo.js, web.cordova)仅包含于 Cordova 构建api.addFiles(bar.js, web.browser)仅包含于浏览器构建api.addFiles(baz.js, web)包含于所有客户端构建。同一语法也适用于api.use、api.imply和api.export。访问本地文件与远程资源作为 Web 应用Cordova 应用受各种安全机制约束具体取决于 Web View 的类型与版本叠加 Cordova 自身乃至操作系统的访问控制理解起来颇为复杂。本地文件访问由于 Meteor 的 Cordova 集成不从file://URL 提供服务受同源策略约束通过file://URL 访问本地文件同样不被允许。Meteor 的文件服务机制支持通过http://localhost:port/local-filesystem/path形式的 URL 访问本地文件可手动构造这类 URL或用WebAppLocalServer.localFileSystemUrl()转换file://URL——例如转换cordova-plugin-file、cordova-plugin-camera等插件返回的 URL。在cordova-plugin-meteor-webapp的客户端实现 webapp_local_server.js 中可以看到localFileSystemUrl将file://前缀替换为/local-filesystem路径从而得到可由本地服务器提供的地址。域名白名单Cordova 通过白名单机制控制对外部域的访问在 Meteor 内置的 Cordova 版本中以cordova-plugin-whitelist实现。在 Meteor 中通过mobile-config.js里的App.accessRule设置附加规则对应生成config.xml中的access、allow-navigation与allow-intent标签。iOS 上的 ATS这些设置在 iOS 上也控制 Application Transport Security (ATS)——iOS 9 引入的、强制安全最佳实践的 OS 级机制。若连接的服务端尚未满足要求可对特定域名覆盖选项App.accessRule(https://domain.com, { minimum-tls-version: TLSv1.0, requires-forward-secrecy: false, });默认情况下Meteor 中的 Cordova 应用只允许访问localhost设备本身用于提供应用服务和应用连接的服务器自动检测的 IP 或显式配置的移动服务器域名用于数据加载与热代码推送。这些限制同样适用于 iframe 加载文件及在其他应用中打开文件含移动浏览器。因此必须显式允许加载data:URL例如允许在 iframe 中加载data:URLApp.accessRule(data:*, { type: navigation });内容安全策略CSP除 Cordova 的域名白名单外Web View 本身可能通过 Content Security Policy (CSP) 强制执行访问规则。目前 Meteor 向生成的 index 页面添加了一个宽松的meta http-equivContent-Security-Policy content...头若需更细粒度控制Meteor 推荐使用 Helmet。跨域资源共享CORS一个常见的误区是设置App.accessRule就足以访问远程资源。实际上域名白名单只控制客户端能连接哪些域同源策略的额外限制依然生效——默认情况下 Web View 不允许 JavaScript 发起跨域 HTTP 请求因此使用XMLHttpRequest时很可能会遇到问题。要绕过这些限制需使用跨域资源共享CORS与客户端配置的白名单不同CORS 依赖服务器设置的响应头。换言之允许访问远程资源可能需要修改服务器配置例如设置Access-Control-Allow-Origin头。系统权限自 iOS 8.0 与 Android 6.0Marshmallow起相机、麦克风、定位、相册等系统功能通常需要额外权限iOS 10 还必须提供定制化的隐私使用说明提示。Android 端的权限值定义在应用的AndroidManifest.xml中且运行时也会请求iOS 端则定义于Info.plist。运行时请求权限可考虑使用cordova.plugins.diagnostic插件。例如为 WebRTC 会话准备 Android 与 iOS 的硬件权限meteor add cordova:cordova.plugins.diagnostic3.0.2if (Meteor.isCordova) { cordova.plugins.diagnostic.isCameraAuthorized( authorized { if (!authorized) { cordova.plugins.diagnostic.requestCameraAuthorization( granted { console.log( Authorization request for camera use was (granted ? granted : denied)); }, error { console.error(error); } ); } }, error { console.error(error); } ); }iOS 端也可在mobile-config.js中通过App.appendToConfig配合正确的 Cocoa Keys 指定隐私使用说明提示。例如访问 iOS 定位数据App.appendToConfig( edit-config targetNSLocationWhenInUseUsageDescription file*-Info.plist modemerge stringMy app needs access to your location for navigation purposes/string /edit-config );配置你的应用Meteor 在构建时读取应用根目录的mobile-config.js用其中配置生成 Cordova 的config.xml文件。元数据App.info({ id: com.meteor.examples.todos, name: Todos, version: 0.0.1 });偏好设置App.setPreference(BackgroundColor, 0xff0000ff); App.setPreference(Orientation, default); App.setPreference(Orientation, all, ios);第三个参数可指定平台更多支持的选项可参考 Meteor 的 Mobile Configuration 文档与 Cordova 文档的 preferences 一节。应用图标与启动屏Meteor 虽自带一套标准图标和启动屏但通常应通过App.icons与App.launchScreens在mobile-config.js中配置贴合品牌的自定义图片。此外Cordova iOS 支持启动 storyboard 图片——苹果推荐的新式启动屏方案无需为每种设备屏幕尺寸提供图片。做法是移除mobile-config.js中所有 iOS 的App.launchScreens指令改用App.appendToConfig添加通用图片路径App.appendToConfig( splash src../../../app/path/to/Default2x~universal~anyany.png / splash src../../../app/path/to/Default3x~universal~anyany.png / );在 iPhone X 上要让启动图铺满全屏很可能必须使用启动 storyboard 图片同时还需处理 safe areas安全区与 rounded corners圆角等布局问题。高级构建定制存在一个名为cordova-build-override/的特殊顶层目录允许以临时方式覆盖 Meteor 在.meteor/local/cordova-build中生成的 Cordova 项目部分内容——该目录的整个文件树会在构建编译前被cp -R覆盖式复制到 Cordova 项目中。这一机制在 tools/cordova/builder.js 中得到确认。但该机制覆盖的是完整文件不适合定制config.xml用自制版本替换生成版本会丢失构建过程与已装插件写入的全部配置信息很可能导致应用损坏。如需定制配置文件变通做法是创建一个伪 Cordova 插件在其plugin.xml中用config-file元素有选择地修改配置文件含config.xml的局部内容。官方建议仅在确实必要、且标准配置选项无法满足时采用这些方案。部署到生产环境生产构建使用meteor build build-output-directory --serverhost:port构建生产版本其中host与port是应用要连接的服务器地址。构建会在输出目录生成一个服务器 bundle 压缩包以及每个已添加移动平台的项目源码分别位于/ios和/android目录。其他选项--debug以 Cordova 调试模式而非发布模式编译Android 下会生成无需签名即可安装的build-output-directory/android/debug.apk--server-only只构建服务器 bundle从而可在未安装移动 SDK 的构建机上构建适合自动化部署场景。注意若改为先移除移动平台再构建服务端 bundle 不会生成 Cordova 资源热代码推送将被禁用。提交到 iOS App Store构建 iOS 应用前需在mobile-config.js中至少配置版本号以及所需的图标与启动屏集合。执行meteor build后打开生成的 Xcode 工程cd build-output-directory/ios/project open MyApp.xcodeproj此后构建 archive 并提交 App Store 的流程与普通 iOS 应用完全相同可参考 Apple 官方文档。提交到 Android Play Store同样需先配置版本号与图标/启动屏。meteor build后生成的 APK 会从build-output-directory/android/project/build/outputs/apk/release复制到build-output-directory/android/release-unsigned.apk若安装了 Crosswalk需手动执行cp复制对应的 armv7 包。提交前必须对 APK签名并运行zipalign优化归档。签名需要私钥密钥用于发布与更新应用若尚未生成keytool -genkey -alias your-app-name -keyalg RSA -keysize 2048 -validity 10000可选地通过--keystore指定不同 keystore签名 APK 时须使用同一个。务必安全备份 keystore默认位于~/.keystore一旦用某密钥发布了 Play Store 应用后丢失该密钥将永远无法发布该应用的任何更新所有版本必须用同一密钥签名。签名cd ~/build-output-directory/android/ jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 release-unsigned.apk your-app-namezipalign 优化$ANDROID_HOME/build-tools/build-tools-version/zipalign 4 release-unsigned.apk your-app-name.apk之后your-app-name.apk即上传 Play Store 的 APK提交流程与普通 Android 应用一致。使用 Crosswalk 提交由于 Crosswalk 为 Chromium 捆绑原生代码会同时产出 ARM 与 x86 两个 APK位于build-output-directory/android/project/build/outputs/apk目录。需要对两个 APK 都签名并运行zipalign并作为多 APK 一起提交到 Play Store。其他实用技巧iOS 上返回手势back gesture默认禁用可在运行时启用window.WkWebView.allowsBackForwardNavigationGestures(true);参考与延伸阅读本指南原始出处guide/source/cordova.md热代码推送故障排查guide/source/hot-code-push.md兼容版本哈希实现packages/webapp-hashing/webapp-hashing.js 及其测试 webapp-hashing-tests.js构建期兼容版本计算tools/isobuild/bundler.jsmanifest 暴露兼容版本packages/webapp/webapp_server.js设备端本地服务器与启动超时WebAppLocalServer.java、webapp_local_server.jsMeteor.isCordova环境标志cordova_environment.jscordova-build-override覆盖机制tools/cordova/builder.js【免费下载链接】meteorMeteor, the JavaScript App Platform项目地址: https://gitcode.com/gh_mirrors/me/meteor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考