目录结构 - Cordova 教程

通过 Cordova CLI 创建的项目，默认拥有如下目录结构：

myapp/
├── config.xml
├── node_modules/
├── package.json
├── platforms/
├── plugins/
└── www

package.json

清单文件，声明项目用到的 JavaScript 包依赖，包含 Cordova、已添加的平台以及所有安装的插件。插件配置变量同样保存在此文件中。

你的项目可能已经存在自带依赖的 package.json（例如前端框架生成）。Cordova 只会向文件追加自身所需配置，不会干扰其他工具与现有依赖。

{
  "name": "com.foxdevelop.hello",
  "displayName": "HelloWorld",
  "version": "1.0.0",
  "description": "A sample Apache Cordova application that responds to the deviceready event.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "ecosystem:cordova"
  ],
  "author": "Apache Cordova Team",
  "license": "Apache-2.0",
  "devDependencies": {
    "cordova-android": "^15.1.0",
    "cordova-plugin-camera": "^8.0.0"
  },
  "cordova": {
    "platforms": [
      "android"
    ],
    "plugins": {
      "cordova-plugin-camera": {
        "ANDROIDX_CORE_VERSION": "1.6.+"
      }
    }
  }
}
Code language: JSON / JSON with Comments (json)

"name": "com.foxdevelop.hello" npm 包名称。在 Cordova 项目中，一般和 config.xml 的 widget id 保持一致。

注意：这不是 Android/iOS 原生包名，原生包名依然由 config.xml 的 id 控制。

"displayName": "HelloWorld" 友好显示名称，对应 App 应用名，和 config.xml 内 <name> 保持对应。
"version": "1.0.0" 项目版本号，遵循语义化版本 主版本.次版本.修订号，建议和 config.xml 的 version 统一。
"description": "A sample Apache Cordova application that responds to the deviceready event." 项目描述，元信息，用于 npm 展示，不影响 APP 打包运行。
"main": "index.js" npm 规范入口文件。Cordova 几乎不会使用这个字段，属于模板自动生成，可以忽略。Cordova APP 真正网页入口是 www/index.html（config.xml 控制）。
"scripts": { "test": "echo \"Error: no test specified\" && exit 1" } npm 自定义脚本。模板默认只有 test，没有配置构建、打包快捷命令。你后续可以自行扩展，例如：

"scripts": {
  "build-android": "cordova build android"
}
Code language: JavaScript (javascript)

"keywords": ["ecosystem:cordova"] npm 搜索标签。ecosystem:cordova 标记该项目为 Cordova 生态工程，仅用于 npm 检索，无运行作用。
"author": "Apache Cordova Team" 作者信息，纯元数据。
"license": "Apache-2.0" 开源协议：Apache 2.0。Cordova 官方默认协议。

config.xml

存放 Cordova 应用的各项偏好设置与配置项，用来自定义项目运行行为。

参考文档：config.xml 官方参考手册

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.foxdevelop.hello" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>HelloWorld</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="https://cordova.apache.org">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
</widget>
Code language: HTML, XML (xml)

id="com.foxdevelop.hello"应用唯一包名（Bundle ID）

Android：应用包名 applicationId
iOS：Bundle Identifier

上架商店不能随便修改！修改后视为全新应用。规范：反向域名 公司域名.项目名

version="1.0.0" 应用版本号（语义化版本 major.minor.patch），打包后对应 App 版本。

<name>HelloWorld</name>

应用显示名称，手机桌面图标下方展示的 App 名字。

<description>

应用描述信息，部分平台打包、商店信息会读取。

<author>

开发者信息：邮箱、官网、作者名称，仅元数据，不影响运行。

<content src="index.html" />

最重要配置

Cordova APP 启动加载的首页。

程序打开后，容器直接加载 www/index.html。

你可以修改为 src="pages/home.html" 变更入口页面。

<allow-intent>

<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
Code language: HTML, XML (xml)

作用：允许 App 唤起外部浏览器打开网页

allow-intent ≠ 页面内允许跨域访问！

两者极易混淆：

allow-intent：点击链接 target="_blank"，跳转系统浏览器，允许跳转哪些网址。当前配置：所有 http/https 网址都允许唤起外部浏览器。
access origin：控制 App 内部 webview 是否可以请求外部接口（跨域），这份配置里缺失！

⚠️ 常见坑：

如果你网页内 AJAX 请求接口报错跨域，只写 allow-intent 没用，必须新增：

xml

<!-- 允许webview内访问所有https接口 -->
<access origin="*" />Code language: HTML, XML (xml)

www/

存放项目网页资源：HTML、CSS、JavaScript 以及各类静态资源文件。

作为 Cordova 应用开发者，绝大多数业务代码和资源都放在此目录。执行 cordova prepare 命令后，该目录文件会被复制到各个平台对应的 www 目录中。

源码目录 www 会被同步复制至各平台子目录，示例路径：

platforms/ios/www 或 platforms/android/assets/www。

CLI 会持续从源码 www 目录覆盖平台目录内文件，只能编辑根目录 www 下的文件，不要直接修改 platforms 内的文件。

如果你使用前端构建工具，应当配置构建产物输出到 www 文件夹；若直接在 www 内开发源码，建议将此目录纳入版本控制。

node_modules/

存放从 npm 仓库下载的所有 JavaScript 依赖包，包括 Cordova、配套工具，以及 package.json 声明的项目依赖。

执行 cordova platform add、cordova plugin add 添加平台 / 插件时，对应的资源会从 npmjs 仓库拉取并下载至 node_modules/。

随后 Cordova 会从该目录复制平台、插件源码到对应位置，保证程序正常运行。

该目录同时包含 cordova prepare、cordova build 构建各平台所需脚本。

⚠️ 重要：node_modules 是原始依赖源码目录，禁止手动修改里面任何文件；同时该目录不要提交到版本控制系统。

更多信息查阅 npmjs 目录规范文档。

platforms/

存放你添加到项目中的各个平台源码与构建脚本。

⚠️ 警告：使用 CLI 构建应用时，除非你充分了解原理、或者官方文档明确说明，否则不要修改 /platforms/ 内任意文件。

项目构建准备、重装插件时，该目录下的文件会被频繁覆盖重写。

plugins/

插件临时中转目录：已安装插件会先复制到此目录，之后再部署到各个平台目录。

该目录不建议提交到版本控制。

如果你开发了自研、内部定制或者修改过的插件，不要存放在 plugins 目录中。

版本控制规范

推荐不要将 platforms/、plugins/ 纳入版本管理，二者属于构建产物。

已安装的平台与插件信息会自动记录在 package.json。执行 cordova prepare 时，程序会自动下载对应的平台与插件。

可选目录

merges/

通过 CLI 创建 Cordova 项目时，默认不会生成 merges 目录。官方不推荐使用该目录，但仍保留兼容支持。

该目录下子文件夹用于存放平台专属网页资源（HTML、CSS、JS）。执行 prepare 阶段时，资源会部署到对应原生项目目录。

放在 merges/ 中的文件，会覆盖 www 目录下同名文件（对应平台生效）。

举个示例目录结构：

plaintext

myapp/
├── merges
│   ├── android/
│   │   └── android.js
│   └── ios/
│       └── app.js
└── www/
    └── app.js

编译 Android、iOS 项目后：

Android 应用：包含 app.js（来自 www） + android.js
iOS 应用：仅存在 app.js，文件来源是 merges/ios/app.js，覆盖了 www 下通用版 app.js

Previous: 第一个Cordova项目

Next: Cordova 命令行工具（CLI）（参考手册）