升级 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://127.0.0.1) 加载 Web 内容。因此，应用程序现在以 URL https://127.0.0.1/ 而不是 file:///android_asset/www/index.html 启动。因为这是一个新的来源，您可能会遇到数据丢失，并且需要迁移您的 Web 数据（本地存储、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 上，创建 type="file" 的文件输入元素不会打开文件选择器对话框。这是 Android 上 Chromium 的一个回归，该问题可以在 Android 上的独立 Chrome 浏览器中重现（请参阅 https://code.google.com/p/android/issues/detail?id=62220）。建议的解决方法是为 Android 4.4 使用 FileTransfer 和 File 插件。您可以监听来自输入 type="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.0

  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/phonegap.xml 替换为 res/xml/cordova.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/phonegap.xml 替换为 res/xml/cordova.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。