升级 Android

本指南介绍如何修改 Android 项目以从旧版本的 Cordova 升级。大多数这些说明适用于使用旧版命令行工具（早于 cordova CLI 实用程序）创建的项目。有关如何更新 CLI 版本的信息，请参阅 命令行界面。

升级到 10.x.x

升级到 10.X.X 的最佳方法是简单地从项目中删除 Android 平台，并使用新版本重新添加它。例如，

cordova platform remove android
cordova platform add [email protected]

如果您使用上述方法，请注意您对 android 平台文件夹所做的任何更改都将丢失（不建议编辑此文件夹的内容）。

重大更改

版本 10.0.0 引入了一个重大更改，即应用程序中 URL 的加载方式。以前版本通过文件协议加载应用程序的 Web 文件（如 index.html）。这意味着应用程序从 URL file:///android_asset/www/index.html 开始。加载 file:/// URL 被认为是不安全的，并且 Android 已弃用支持。Cordova Android 10.0.0 现在使用名为 WebViewAssetLoader 的 Android API 通过 HTTP(S) 方案 (https://localhost) 加载 Web 内容（默认情况下）。因此，应用程序现在从 URL https://localhost/ 开始，而不是 file:///android_asset/www/index.html。由于这是一个新的来源，您可能会遇到数据丢失，并且需要迁移您的 Web 数据（LocalStorage、IndexedDB 等）。

您可以使用 config.xml 首选项 <preference name="AndroidInsecureFileModeEnabled" value="true" /> 选择退出新的 WebViewAssetLoader 并切换回文件 URL。

升级到 7.X.X

升级到 7.X.X 的最佳方法是简单地从项目中删除 Android 平台，并使用新版本重新添加它。例如，

cordova platform remove android
cordova platform add [email protected]

如果您使用上述方法，请注意您对 android 平台文件夹所做的任何更改都将丢失（不建议编辑此文件夹的内容）。

不幸的是，由于文件结构的更新，非 CLI 项目将不得不手动更新，或者必须创建一个新的 Cordova 项目，并将文件传输到新项目。这是由于迁移到 Android Studio 造成的。

升级到 6.X.X

升级到 6.X.X 的最佳方法是简单地从项目中删除 Android 平台，并使用新版本重新添加它。例如，

cordova platform remove android
cordova platform add [email protected]

如果您使用上述方法，请注意您对 android 平台文件夹所做的任何更改都将丢失（不建议编辑此文件夹的内容）。

或者，您可以尝试使用平台更新脚本。对于非 CLI 项目，请运行

bin/update path/to/project

升级到 5.X.X

升级到 5.X.X 的最佳方法是简单地从项目中删除 Android 平台，并使用新版本重新添加它。例如，

cordova platform remove android
cordova platform add [email protected]

如果您使用上述方法，请注意您对 android 平台文件夹所做的任何更改都将丢失（不建议编辑此文件夹的内容）。

或者，您可以尝试使用平台更新脚本。对于非 CLI 项目，请运行

bin/update path/to/project

对于 CLI 项目

  1. 更新 cordova CLI 版本。请参阅 命令行界面。

  2. 在现有项目中运行 cordova platform update [email protected]。

升级 Android Marshmallow 的插件

版本 5.0.0 添加了对 Android API 级别 23（Marshmallow）的支持。Android Marshmallow 引入了一种新的权限模型，您可能需要更新一些已安装的插件以确保它们与更新的手机兼容。旧版本的插件如果不能正确处理权限，会导致您的应用程序意外崩溃。请注意，这不会影响所有插件，而只会影响那些访问被认为是危险的 Android 权限的插件（请参阅 危险权限表）。

以下核心插件受此更改的影响，必须升级才能与 cordova-android 5.0.0+ 一起使用

插件 最低兼容版本
cordova-plugin-camera 2.0.0
cordova-plugin-contacts 2.0.0
cordova-plugin-file 4.0.0
cordova-plugin-geolocation 2.0.0
cordova-plugin-media 2.0.0

对于非核心插件，您可以通过检查插件的 plugin.xml 文件来验证插件是否请求 危险权限。如果插件使用 Android 权限，您将在 plugin.xml 中看到声明它们的条目。例如

<uses-permission android:name="android.permission.PERMISSION_NAME" />

其中 PERMISSION_NAME 被替换为 Android 权限的名称。plugin.xml 文件可以在 Cordova 项目的插件文件夹中找到（例如 plugins/example-plugin/plugin.xml）。请咨询使用危险权限的任何插件的文档，以确定需要采取哪些步骤来确保 cordova-android 5.0.0+ 兼容性。

升级到 4.0.0

要利用 4.0.0 中的重大更改，需要执行特定的升级步骤。首先，需要执行以下常见的升级步骤。

对于非 CLI 项目，请运行

bin/update path/to/project

对于 CLI 项目

  1. 更新 cordova CLI 版本。请参阅 命令行界面。

  2. 在现有项目中运行 cordova platform update [email protected]。

升级白名单

所有白名单功能现在通过插件实现。如果没有插件，升级到 4.0.0 后，您的应用程序将不再受白名单保护。Cordova 有两个白名单插件，它们提供不同级别的保护。

  1. cordova-plugin-whitelist 插件（推荐）
    • 强烈推荐使用此插件，因为它比以前版本的白名单更安全，并且可配置性更高
    • 有关所需配置更改的详细信息，请参阅 cordova-plugin-whitelist
    • 运行：cordova plugin add cordova-plugin-crosswalk-webview
  2. cordova-plugin-legacy-whitelist 插件
    • 此插件提供与以前版本相同的白名单行为。请参阅 cordova-plugin-legacy-whitelist
    • 不需要进行任何配置更改，但它提供的保护不如推荐的插件
    • 运行：cordova plugin add cordova-plugin-legacy-whitelist

使用 Crosswalk WebView

默认情况下，您的应用程序将继续使用设备提供的系统 WebView。如果您希望使用 Crosswalk WebView，只需添加 Crosswalk 插件

cordova plugin add cordova-plugin-crosswalk-webview

添加插件后，您的应用程序将获得正确安装和配置的 Crosswalk WebView。

升级到启动画面插件

如果您的应用程序使用启动画面，该功能已移至插件。启动画面的配置选项保持不变。唯一需要的升级步骤是添加插件

cordova plugin add cordova-plugin-splashscreen

从 3.6.0 升级到 3.7.1

对于非 CLI 项目，请运行

bin/update path/to/project

对于 CLI 项目

  1. 更新 cordova CLI 版本。请参阅 命令行界面。

  2. 在现有项目中运行 cordova platform update android。

从 3.2.0 升级到 3.3.0

按照 3.2.0 的相同说明操作。

从 3.3.0 开始，Cordova 运行时现在被编译为 Android 库，而不是 Jar。这对于命令行使用应该没有影响，但 IDE 用户需要将新添加的 MyProject-CordovaLib 项目导入其工作区。

从 3.1.0 升级到 3.2.0

对于使用 cordova CLI 创建的项目

  1. 更新 cordova CLI 版本。请参阅 命令行界面。

  2. 运行 cordova platform update android

对于未使用 cordova CLI 创建的项目，请运行

    bin/update <project_path>

警告：在 Android 4.4 - Android 4.4.3 上，创建类型为“file”的文件输入元素将不会打开文件选择器对话框。这是 Android 上 Chromium 的一个回归，并且可以在 Android 上的独立 Chrome 浏览器中重现此问题（请参阅 https://code.google.com/p/android/issues/detail?id=62220）建议的解决方法是使用 Android 4.4 的 FileTransfer 和 File 插件。您可以监听来自输入类型“file”的 onClick 事件，然后弹出文件选择器 UI。为了将表单数据与上传绑定，您可以使用 JavaScript 将表单值附加到 FileTransfer 执行的多部分 POST 请求。

从 3.0.0 升级到 3.1.0

对于使用 cordova CLI 创建的项目

  1. 更新 cordova CLI 版本。请参阅 命令行界面。

  2. 运行 cordova platform update android

对于未使用 cordova CLI 创建的项目，请运行

    bin/update <project_path>

从 2.9.0 升级到 CLI（3.0.0）

  1. 使用 cordova CLI 创建一个新的 Apache Cordova 3.0.0 项目，如 命令行界面 中所述。

  2. 将您的平台添加到 cordova 项目，例如：cordova platform add android。

  3. 将项目 www 目录的内容复制到您刚刚创建的 cordova 项目根目录下的 www 目录。

  4. 将任何原生资产从旧项目复制到 platforms/android 下的相应目录：此目录是您的原生 cordova-android 项目所在的位置。

  5. 使用 cordova CLI 工具安装您需要的任何插件。请注意，CLI 将所有核心 API 作为插件处理，因此可能需要添加它们。只有 3.0.0 插件与 CLI 兼容。

从 2.9.0 升级到 3.0.0

  1. 创建一个新的 Apache Cordova Android 项目。

  2. 将 www 目录的内容复制到新项目。

  3. 将任何原生 Android 资产从 res 目录复制到新项目。

  4. 将您从 src 子目录中安装的任何插件复制到新项目。

  5. 确保将旧 config.xml 文件中的任何已弃用的 <plugin> 引用升级到新的 <feature> 规范。

  6. 更新对 org.apache.cordova.api 包的任何引用，使其成为 org.apache.cordova。

    注意：所有核心 API 都已删除，必须作为插件安装。有关详细信息，请参阅 使用 Plugman 管理插件 指南。

从 2.8.0 升级到 2.9.0

  1. 运行 bin/update <project_path>。

从 2.7.0 升级到 2.8.0

  1. 从项目的 libs 目录中删除 cordova-2.7.0.jar。

  2. 将 cordova-2.8.0.jar 添加到项目的 libs 目录。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  1. 将新的 cordova.js 复制到您的项目。

  2. 更新您的 HTML 以使用新的 cordova.js 文件。

  3. 复制 res/xml/config.xml 文件以匹配 framework/res/xml/config.xml。

  4. 更新 framework/res/xml/config.xml 以使其具有与以前类似的设置。

  5. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

从 2.6.0 升级到 2.7.0

  1. 从项目的 libs 目录中删除 cordova-2.6.0.jar。

  2. 将 cordova-2.7.0.jar 添加到项目的 libs 目录。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.7.0.js 复制到您的项目。

  5. 更新您的 HTML 以使用新的 cordova-2.7.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

  7. 更新 framework/res/xml/config.xml 以使其具有与以前类似的设置。

  8. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

从 2.5.0 升级到 2.6.0

  1. 从项目的 libs 目录中删除 cordova-2.5.0.jar。

  2. 将 cordova-2.6.0.jar 添加到项目的 libs 目录。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.6.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-2.6.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

  7. 更新 framework/res/xml/config.xml 以使其具有与以前类似的设置。

  8. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

在 Cordova 源代码目录中列出项目路径，运行 bin/update <project> 命令。

从 2.4.0 升级到 2.5.0

  1. 从项目 libs 目录中删除 cordova-2.4.0.jar 文件。

  2. 将 cordova-2.5.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.5.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-2.5.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

  7. 更新 framework/res/xml/config.xml 以使其具有与以前类似的设置。

  8. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

从 2.3.0 升级到 2.4.0

  1. 从项目 libs 目录中删除 cordova-2.3.0.jar 文件。

  2. 将 cordova-2.4.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.4.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-2.4.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

  7. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

从 2.2.0 升级到 2.3.0

  1. 从项目 libs 目录中删除 cordova-2.2.0.jar 文件。

  2. 将 cordova-2.3.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.3.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-2.3.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

  7. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

从 2.1.0 升级到 2.2.0

  1. 从项目 libs 目录中删除 cordova-2.1.0.jar 文件。

  2. 将 cordova-2.2.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.2.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-2.2.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

  7. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

从 2.0.0 升级到 2.1.0

  1. 从项目 libs 目录中删除 cordova-2.0.0.jar 文件。

  2. 将 cordova-2.1.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.1.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-2.1.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

  7. 将文件从 bin/templates/cordova 复制到项目的 cordova 目录。

从 1.9.0 升级到 2.0.0

  1. 从项目 libs 目录中删除 cordova-1.9.0.jar 文件。

  2. 将 cordova-2.0.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-2.0.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-2.0.0.js 文件。

  6. 复制 res/xml/config.xml 以匹配 framework/res/xml/config.xml。

在 2.0.0 版本中，config.xml 文件合并并替换了 cordova.xml 和 plugins.xml 文件。旧文件已弃用，虽然它们在 2.0.0 中仍然有效，但将在未来版本中停止工作。

从 1.8.1 升级到 1.9.0

  1. 从项目 libs 目录中删除 cordova-1.8.0.jar 文件。

  2. 将 cordova-1.9.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.9.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-1.9.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

由于 1.9.0 版本中引入了 CordovaWebView，第三方插件可能无法正常工作。这些插件需要使用 getContext() 或 getActivity() 从 CordovaInterface 获取上下文。如果您不是经验丰富的 Android 开发人员，请联系插件维护者并将此任务添加到他们的错误跟踪器中。

从 1.8.0 升级到 1.8.1

  1. 从项目 libs 目录中删除 cordova-1.8.0.jar 文件。

  2. 将 cordova-1.8.1.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.8.1.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-1.8.1.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

从 1.7.0 升级到 1.8.0

  1. 从项目 libs 目录中删除 cordova-1.7.0.jar 文件。

  2. 将 cordova-1.8.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.8.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-1.8.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

从 1.7.0 升级到 1.8.0

  1. 从项目 libs 目录中删除 cordova-1.7.0.jar 文件。

  2. 将 cordova-1.8.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.8.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-1.8.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

从 1.6.1 升级到 1.7.0

  1. 从项目 libs 目录中删除 cordova-1.6.1.jar 文件。

  2. 将 cordova-1.7.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.7.0.js 文件复制到您的项目中。

  5. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

从 1.6.0 升级到 1.6.1

  1. 从项目 libs 目录中删除 cordova-1.6.0.jar 文件。

  2. 将 cordova-1.6.1.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.6.1.js 文件复制到您的项目中。

  5. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

从 1.5.0 升级到 1.6.0

  1. 从项目 libs 目录中删除 cordova-1.5.0.jar 文件。

  2. 将 cordova-1.6.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.6.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-1.6.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

  7. 用 res/xml/cordova.xml 文件替换 res/xml/phonegap.xml 文件，以匹配 framework/res/xml/cordova.xml 文件。

从 1.4.0 升级到 1.5.0

  1. 从项目 libs 目录中删除 phonegap-1.4.0.jar 文件。

  2. 将 cordova-1.5.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 cordova-1.5.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 cordova-1.5.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

  7. 用 res/xml/cordova.xml 文件替换 res/xml/phonegap.xml 文件，以匹配 framework/res/xml/cordova.xml 文件。

从 1.3.0 升级到 1.4.0

  1. 从项目 libs 目录中删除 phonegap-1.3.0.jar 文件。

  2. 将 phonegap-1.4.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 phonegap-1.4.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 phonegap-1.4.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

  7. 更新 res/xml/phonegap.xml 文件以匹配 framework/res/xml/phonegap.xml 文件。

从 1.2.0 升级到 1.3.0

  1. 从项目 libs 目录中删除 phonegap-1.2.0.jar 文件。

  2. 将 phonegap-1.3.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 phonegap-1.3.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 phonegap-1.2.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

  7. 更新 res/xml/phonegap.xml 文件以匹配 framework/res/xml/phonegap.xml 文件。

从 1.1.0 升级到 1.2.0

  1. 从项目 libs 目录中删除 phonegap-1.1.0.jar 文件。

  2. 将 phonegap-1.2.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 phonegap-1.2.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 phonegap-1.2.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

  7. 更新 res/xml/phonegap.xml 文件以匹配 framework/res/xml/phonegap.xml 文件。

从 1.0.0 升级到 1.1.0

  1. 从项目 libs 目录中删除 phonegap-1.0.0.jar 文件。

  2. 将 phonegap-1.1.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 phonegap-1.1.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 phonegap-1.1.0.js 文件。

  6. 更新 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。

从 0.9.6 升级到 1.0.0

  1. 从项目 libs 目录中删除 phonegap-0.9.6.jar 文件。

  2. 将 phonegap-1.0.0.jar 文件添加到项目 libs 目录中。

  3. 如果您使用 Eclipse，请刷新您的 Eclipse 项目并进行清理。

  4. 将新的 phonegap-1.0.0.js 文件复制到您的项目中。

  5. 更新您的 HTML 代码以使用新的 phonegap-1.0.0.js 文件。

  6. 添加 res/xml/plugins.xml 文件以匹配 framework/res/xml/plugins.xml 文件。