上一堂課，我們成功安裝好 Cordova，這堂課將透過 CLI 指令建立專案
一、建立 Cordova 專案
開啟終端機，切換到你想要存放專案的資料夾，執行建立指令：
cordova create hello com.foxdevelop.hello HelloWorldCode language: CSS (css)參數說明：
hello：專案資料夾名稱com.example.hello：應用程式套件名稱（Android 專屬識別碼，上架前務必修改）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新增平台
# Android平台（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' 不是內部或外部命令，也不是可執行的程式或批次檔。
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 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路徑
接下來設定環境變數
變數名稱：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安裝程式，執行安裝時勾選下列選項，讓安裝工具自動設定 JAVA_HOME 與 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
# 只建置Android版本
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：Android模擬器執行
cordova emulate android
方式 2：USB連接實機測試（開啟USB偵錯）
cordova run android
建議使用實機測試；透過傳輸線連接Android手機，並開啟手機的偵錯模式。
切換至hello目錄，開啟CMD執行 cordova run android
接著手機將安裝此App
隨即載入Cordova頁面
六、安裝外掛（Plugin）
存取行動裝置原生功能
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 資源。
若你想要Android、iOS使用不同介面資源，可以使用 merges 資料夾：
merges/
├─android/
│ └─css/overrides.css # 僅Android平台生效
└─ios/
Code language: PHP (php)建置專案時，merges內的檔案會覆蓋www同名檔案。
* 八、升級 Cordova
# 全域升級cordova命令列工具
npm update -g cordova
# 安裝指定版本
npm install -g cordova@12.0.0
# 更新專案內Android平台版本
cordova platform update android --save
Code language: PHP (php)常用指令整理
#1 建立專案
cordova create testapp com.mytest.app TestApp
cd testapp
#2 新增Android平台
cordova platform add android
#3 檢查開發環境
cordova requirements
#4 編譯測試套件
cordova build android
#5 實機執行
cordova run android
Code language: CSS (css)第一個Cordova專案
Previous: 介紹與安裝