Apache Cordova完全入门指南

Question

Apache Cordova 完全入门指南

什么是 Cordova？

Apache Cordova 是一个开源的移动开发框架，允许开发者使用标准的 Web 技术（HTML5、CSS3 和 JavaScript）来开发跨平台移动应用。通过 Cordova，你可以用一套代码构建 iOS、Android、Windows 等多平台应用，通过插件访问设备原生功能（如相机、GPS、文件系统等），快速开发并降低维护成本，同时利用现有的 Web 开发技能。

Cordova 的工作原理是将你的 Web 应用包装在原生应用的 WebView 中，并提供 JavaScript API 来访问设备的原生功能。

环境准备与安装

前置要求

在安装 Cordova 之前，确保你的系统已经安装了：

Node.js 和 npm：Node.js 版本需不低于 14.x，npm 会随 Node.js 一起安装。
```
node --version
npm --version
```
Git（可选，但推荐）。
```
git --version
```

安装 Cordova CLI

Cordova 命令行工具（CLI）是开发 Cordova 应用的核心工具。

npm install -g cordova
cordova --version
cordova help

平台特定要求

iOS 开发（仅 macOS）：需要安装 Xcode 和 iOS 部署工具。
```
npm install -g ios-deploy
cordova requirements ios
```

Android 开发：需要安装 Java Development Kit (JDK) 11 或更高版本、Android Studio、Android SDK，并配置环境变量 ANDROID_HOME 和 JAVA_HOME。

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools
cordova requirements android

浏览器开发：不需要额外配置，是最容易上手的开发方式。

创建第一个 Cordova 项目

方法一：从头创建新项目

cordova create MyApp io.cordova.hellocordova HelloCordova
cd MyApp
cordova info

参数说明：MyApp 是项目目录名，io.cordova.hellocordova 是应用的包标识符（反向域名格式），HelloCordova 是应用显示名称。

方法二：使用现有项目

如果你已经有一个 Cordova 项目，只需进入项目目录并安装依赖。

cd MyApp
npm install
cordova info

项目结构详解

创建项目后，目录结构如下：

MyApp/
├── config.xml              # Cordova 项目配置文件
├── package.json            # Node.js 项目配置文件
├── www/                    # Web 应用源代码
│   ├── index.html         # 应用主页面
│   ├── css/               # 样式文件
│   ├── js/                # JavaScript 文件
│   └── img/               # 图片资源
├── platforms/              # 各平台的原生代码
├── plugins/                # Cordova 插件
└── hooks/                  # 构建钩子脚本

核心文件详解

config.xml：应用配置文件，定义应用 ID、名称、描述等。



    HelloCordova
    Sample Apache Cordova App
    Apache Cordova Team

www/index.html：应用入口 HTML 文件。




    
    
    Hello World
    


    
        Apache Cordova
        
            Connecting to Device
            Device is Ready

www/js/index.js：应用逻辑 JavaScript 文件。

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

function onDeviceReady() {
    console.log('Running cordova-' + cordova.platformId + '@' + cordova.version);
    document.getElementById('deviceready').classList.add('ready');
}

Cordova 常用命令大全

项目管理命令

cordova create <目录> <包名> <应用名>
cordova info
cordova --version
cordova help
npm update -g cordova

平台管理命令

cordova platform add browser
cordova platform add ios
cordova platform add android
cordova platform ls
cordova platform remove browser
cordova platform update browser
cordova requirements

插件管理命令

cordova plugin search camera
cordova plugin add cordova-plugin-camera
cordova plugin ls
cordova plugin remove cordova-plugin-camera
cordova plugin update cordova-plugin-camera
cordova plugin save
cordova plugin restore

构建命令

cordova prepare
cordova compile
cordova build
cordova build --debug
cordova build --release

运行和测试命令

cordova run browser
cordova run ios
cordova run android --device
cordova emulate ios
cordova serve

调试命令

cordova clean
cordova requirements
cordova run android --verbose

配置命令

cordova config ls
cordova config get <键>
cordova config set <键> <值>
cordova config delete <键>

运行和调试项目

浏览器运行（最简单）

cordova platform add browser
cordova run browser
# 或使用 serve 命令
cordova serve

iOS 模拟器运行

cordova platform add ios
cordova emulate ios
cordova run ios --device

Android 模拟器/设备运行

cordova platform add android
cordova emulate android
cordova run android --device
adb logcat

平台管理

Cordova 支持多个平台，包括浏览器、iOS、Android、Windows、macOS 和 Electron。多平台开发工作流通常包括添加平台、开发测试、构建和发布。

平台特定代码

document.addEventListener('deviceready', function() {
    var platform = cordova.platformId;
    if (platform === 'browser') {
        console.log('Running in browser');
    } else if (platform === 'ios') {
        console.log('Running on iOS');
    } else if (platform === 'android') {
        console.log('Running on Android');
    }
}, false);

插件管理

Cordova 插件是访问设备原生功能的桥梁。核心插件推荐包括设备信息、网络状态、相机、地理位置、文件系统等。

插件使用示例

设备信息插件：

cordova plugin add cordova-plugin-device

document.addEventListener('deviceready', function() {
    console.log('设备型号: ' + device.model);
    console.log('平台: ' + device.platform);
    console.log('系统版本: ' + device.version);
    console.log('设备UUID: ' + device.uuid);
}, false);

相机插件：

cordova plugin add cordova-plugin-camera

document.getElementById('takePicture').addEventListener('click', function() {
    navigator.camera.getPicture(onSuccess, onFail, {
        quality: 50,
        destinationType: Camera.DestinationType.DATA_URL
    });

    function onSuccess(imageData) {
        var image = document.getElementById('myImage');
        image.src = "data:image/jpeg;base64," + imageData;
    }

    function onFail(message) {
        alert('拍照失败: ' + message);
    }
});

地理位置插件：

cordova plugin add cordova-plugin-geolocation

navigator.geolocation.getCurrentPosition(
    function(position) {
        console.log('纬度: ' + position.coords.latitude);
        console.log('经度: ' + position.coords.longitude);
    },
    function(error) {
        console.log('获取位置失败: ' + error.message);
    }
);

构建与发布

调试构建 vs 发布构建

调试构建：包含调试符号，文件未压缩，适用于开发阶段。
发布构建：代码经过优化和混淆，文件大小更小，需要签名证书，准备上架应用商店。

Android 发布构建

生成签名密钥。
配置签名文件。
构建发布版本：cordova build android --release。
对齐 APK 以优化。

iOS 发布构建

配置 Apple 开发者账号。
使用 Xcode 构建：cordova build ios --release --device。
上传到 App Store Connect。

最佳实践与技巧

版本控制：将 config.xml、package.json 和 www/ 目录提交到 Git，忽略 node_modules/、platforms/、plugins/ 等。
项目初始化脚本：在 package.json 中定义脚本，如 setup、serve、build 等，简化工作流。
性能优化：使用 FastClick 消除点击延迟，懒加载图片以提升加载速度。
调试技巧：使用远程调试工具如 weinre，或利用浏览器开发者工具进行调试。
跨平台兼容性：检测平台并处理差异，确保应用在各平台运行一致。
错误处理：设置全局错误处理和超时处理，提高应用稳定性。
安全性：在 config.xml 中配置安全策略，限制访问域名，防止恶意攻击。
持续集成：使用 GitHub Actions 等工具自动化构建和部署流程。

常见问题与解决方案

deviceready 事件不触发：确保正确加载 cordova.js，使用超时检测机制。
插件不工作：检查插件是否已安装、平台是否支持，并确保在 deviceready 事件后使用插件。
Android 构建失败：清理并重新构建，检查 Java/Gradle 版本兼容性。
iOS 构建失败：更新 CocoaPods，清理并重新构建项目。

实战演练：运行本项目

检查环境：确认项目目录，检查 Cordova 版本和依赖。
安装依赖：运行 npm install 并恢复插件。
在浏览器中运行：使用 cordova run browser 或 cordova serve 启动应用。
添加更多平台：如 iOS 或 Android，进行跨平台测试。
修改和测试：编辑 www/ 目录下的文件，实时刷新查看更改，验证功能。

总结

通过本指南，你掌握了 Cordova 的安装、项目创建、命令使用、平台管理、插件管理、构建发布以及最佳实践。下一步可以深入插件开发、集成前端框架如 React 或 Vue、学习更多设备 API、进行性能优化和实现自动化部署。有用的资源包括 Cordova 官方文档、插件库、Stack Overflow 和 GitHub 仓库，帮助你在移动开发道路上更进一步。

Apache Cordova完全入门指南