第一个Cordova项目

上节课，我们安装cordova成功了，本节课我们来使用CLI命令来创建项目

一、创建 Cordova 项目

打开终端，进入你想要存放项目的文件夹，执行创建命令：

cordova create hello com.foxdevelop.hello HelloWorldCode language: CSS (css)

参数说明：

1. hello：项目文件夹名称
2. com.example.hello：应用包名（安卓唯一标识，上线必须修改）
3. HelloWorld：应用显示名称

下面是正式例子，在d盘创建了一个目录，然后在目录里面创建项目

C:\Users>d:

D:\>mkdir cordovademo

D:\>cd cordovademo

D:\cordovademo>cordova create hello com.foxdevelop.hello HelloWorld
Creating a new cordova project.Code language: CSS (css)

然后在D盘中，就可以看到cordovademo目录，里面有一个hello的子目录。

核心源码目录：hello/www/

入口页面：www/index.html

不要修改 platforms 目录下任何文件，打包时会被覆盖！

二、进入项目，添加平台

cd hello

添加平台

# 安卓平台（Windows可用）
cordova platform add android

# ios平台【Windows无法编译！仅Mac电脑支持】
# cordova platform add iosCode language: PHP (php)

执行记录

D:\cordovademo>cd hello

D:\cordovademo\hello>cordova platform add android
Using cordova-fetch for cordova-android
Adding android project...
Creating Cordova project for the Android platform:
        Path: platforms\android
        Package: com.foxdevelop.hello
        Name: HelloWorld
        Activity: MainActivity
        Android Target SDK: android-36
        Android Compile SDK: 36
Subproject Path: CordovaLib
Subproject Path: app
Android project created with cordova-android@15.1.0

D:\cordovademo\hello>cordova platform ls
Installed platforms:
  android 15.1.0
Available platforms:
  browser
  electronCode language: CSS (css)

三、环境前置检查（重要）

cordova requirements

检查你的系统是否已经配置好了环境，例如安装JDK等等。

D:\cordovademo\hello>cordova requirements
Android SDK is missing cmdline-tools directory.

Requirements check results for android:
Java JDK: installed 11.0.31
Android SDK: installed true
Android target: not installed
Command failed with exit code 1: avdmanager list target
'avdmanager' �����ڲ����ⲿ���Ҳ���ǿ����еij���
���������ļ���
Gradle: not installed
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path, or install Android Studio
Some of requirements check failedCode language: PHP (php)

正常是

Java JDK: installed
Android SDK: installed
Gradle: installed

但是我这里Gradle: not installed

如果读者，没安装JDK，则需要安装JDK，关于JDK的安装，可以参考其他课程，

我这里安装的jdk是11的版本

作者本机出现如下

D:\cordovademo\hello>cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=undefined (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)
Android SDK is missing cmdline-tools directory.
Using Android SDK: D:\Sortware\ADB
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path, or install Android StudioCode language: JavaScript (javascript)

读者需要安装android studio 里面包含sdk

关于android studio，可以参考其他课程

打开你的Android studio 顶部菜单：Tools → SDK Manager 然后 找到下面的 sdk 查看你的sdk路径

然后设置环境变量

变量名：ANDROID_HOME
变量值：C:\Users\xxxxx\AppData\Local\Android\Sdk

除了创建变量值，还要加到path中

%ANDROID_HOME%\platform-tools
%ANDROID_HOME%\cmdline-tools\latest\bin

Android Studio 安装命令行工具

打开 Android Studio → Tools → SDK Manager

切换到 SDK Tools 标签

下载 Gradle 二进制包

官网下载：https://gradle.org/releases/

解压到路径：C:\gradle\gradle-8.5

Gradle by Develocity | Releases

配置系统环境变量

变量名：GRADLE_HOME
变量值：C:\gradle-8.7

新建【系统变量】

配置到Path中

验证是否安装成功

打开cmd

gradle -v

再次测试，出现下面 则表示成功配置

D:\cordovademo\hello>cordova requirements

Requirements check results for android:
Java JDK: installed 11.0.31
Android SDK: installed true
Android target: not installed
No android targets (SDKs) installed!
Gradle: installed C:\gradle-8.7\bin\gradle.BAT
Some of requirements check failedCode language: CSS (css)

问题2 JDK版本

小编使用cordova run android 命令后报如下错误

D:\cordovademo\hello>cordova run android
Checking Java JDK and Android SDK versions
ANDROID_HOME=C:\Users\maiwu\AppData\Local\Android\Sdk (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)

BUILD SUCCESSFUL in 1sCUTING [91ms]
1 actionable task: 1 up-to-date
Subproject Path: CordovaLib
Subproject Path: app

[Incubating] Problems report is available at: file:///D:/cordovademo/hello/platforms/android/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* Where:
Build file 'D:\cordovademo\hello\platforms\android\app\build.gradle' line: 20

* What went wrong:
A problem occurred evaluating project ':app'.
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in C:\Program Files\Zulu\zulu-11
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.14.2/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.

BUILD FAILED in 2s
Command failed with exit code 1: D:\cordovademo\hello\platforms\android\tools\gradlew.bat cdvBuildDebugCode language: JavaScript (javascript)

小编当前环境 JDK11，但当前 Cordova Android 平台搭配的 AGP (Android Gradle Plugin) 强制要求 JDK17，构建直接失败。

小编用的是Zulu JDK 11 所以本次更新到Zulu JDK 17

请到这里下载 Java 8, 11, 17, 21, 25 Download for Linux, Windows and macOS

下载的是一个msi 然后点击安装 安装的勾选下面这些，让安装包自动配置javahome path这些

打开CMD检查一下java

java -version

openjdk version "17.0.20" 2026-07-21 LTS
OpenJDK Runtime Environment Zulu17.68+17-CA (build 17.0.20+8-LTS)
OpenJDK 64-Bit Server VM Zulu17.68+17-CA (build 17.0.20+8-LTS, mixed mode, sharing)Code language: CSS (css)

提示以上则表示成功

四、构建应用

# 构建所有平台（当前只有android）
cordova build

# 只构建安卓
cordova build android
Code language: PHP (php)

编译成功后，apk 输出路径：

hello\platforms\android\app\build\outputs\apk\debug\app-debug.apk

实录

D:\cordovademo\hello>cordova build android
Checking Java JDK and Android SDK versions
ANDROID_HOME=C:\Users\maiwu\AppData\Local\Android\Sdk (recommended setting)
ANDROID_SDK_ROOT=undefined (DEPRECATED)
Using Android SDK: C:\Users\maiwu\AppData\Local\Android\Sdk

BUILD SUCCESSFUL in 9s
1 actionable task: 1 up-to-date
Subproject Path: CordovaLib
Subproject Path: app

> Task :CordovaLib:compileDebugJavaWithJavac
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.

[Incubating] Problems report is available at: file:///D:/cordovademo/hello/platforms/android/build/reports/problems/problems-report.html

BUILD SUCCESSFUL in 11s
50 actionable tasks: 50 executed
Built the following apk(s):
        D:\cordovademo\hello\platforms\android\app\build\outputs\apk\debug\app-debug.apkCode language: JavaScript (javascript)

在目录下面看到apk文件D:\cordovademo\hello\platforms\android\app\build\outputs\apk\debug\

五、测试运行

方式 1：安卓模拟器运行

cordova emulate android

方式 2：USB 连接真机测试（开启 USB 调试）

cordova run android

我们使用真机来测试，也建议大家使用真机测试，用数据线链接android手机，然后手机开启调试模式。

在hello目录下面 打开cmd，执行命令cordova run android

之后手机就可以安装一个app

打开cordova的页面了

六、插件安装

访问手机原生能力

Cordova 网页本身不能调用摄像头、蓝牙、文件、通知等硬件，必须安装插件。

示例：摄像头插件

cordova plugin add cordova-plugin-camera

查看已安装插件

cordova plugin ls

JS 调用原生 API 必须等待 deviceready 事件触发，页面加载完成不能直接调用插件！

基础模板示例（www/js/index.js）

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    // 设备就绪，可以调用所有cordova插件
    console.log("Cordova初始化完成");
}
Code language: JavaScript (javascript)

实录

D:\cordovademo\hello>cordova plugin add cordova-plugin-camera
Installing "cordova-plugin-camera" for android
Subproject Path: CordovaLib
Subproject Path: app
Adding cordova-plugin-camera to package.json

D:\cordovademo\hello>cordova plugin ls
cordova-plugin-camera 8.0.0 "Camera"Code language: CSS (css)

下面修改index.html 为如下代码，测试摄像头功能

首先说明一下，创建好项目后，我们的目录文件

D:\cordovademo\hello

日后编写代码就在www中

修改index.html 为如下

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Camera Test</title>
    <script src="cordova.js"></script>
</head>
<body>
    <button id="btnTake">拍照</button>
    <br>
    <img id="imgPreview" style="width:220px;">

    <script>
        let cameraReady = false;

        document.addEventListener("deviceready", onDeviceReady, false);

        function onDeviceReady() {
            console.log("deviceready 触发，Cordova就绪");
            cameraReady = true;
        }

        // 改用addEventListener绑定（onclick容易出现时序冲突，推荐）
        document.getElementById("btnTake").addEventListener("click", function(){
            if(!cameraReady){
                alert("等待Cordova初始化完成！");
                return;
            }

            navigator.camera.getPicture(
                function(imageUri) {
                    console.log("拍照成功：", imageUri);
                    document.getElementById("imgPreview").src = imageUri;
                },
                function(error) {
                    alert("拍照失败：" + error);
                },
                {
                    destinationType: 0, // Camera.DestinationType.FILE_URI = 0，直接用数字规避Camera未定义
                    sourceType: 1,      // Camera.PictureSourceType.CAMERA = 1
                    quality: 80
                }
            );
        });
    </script>
</body>
</html>Code language: C# (cs)

再次运行cordova run android 命令

会打开app，上面看到一个按钮，点击按钮，就会打开摄像头，然后就可以拍照了。

* 七、merges 目录：多平台差异化文件

默认所有平台共用 www 资源。

如果你想要安卓、iOS 界面资源不一样，使用 merges 文件夹：

merges/
├─android/
│  └─css/overrides.css  # 仅安卓生效
└─ios/
Code language: PHP (php)

构建时，merges 内文件会覆盖 www 同名文件。

* 八、升级 Cordova

# 全局升级cordova命令行
npm update -g cordova

# 安装指定版本
npm install -g cordova@12.0.0

# 更新项目内安卓平台版本
cordova platform update android --save
Code language: PHP (php)

命令汇总

#1 创建项目
cordova create testapp com.mytest.app TestApp
cd testapp

#2 添加安卓平台
cordova platform add android

#3 检查环境
cordova requirements

#4 编译调试包
cordova build android

#5 真机运行
cordova run android
Code language: CSS (css)