目錄結構 - 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能否呼叫外部 API（跨域），這份範例設定裡沒有這一行！

⚠️ 常見陷阱：

如果網頁 AJAX 呼叫 API 出現跨域錯誤，只寫 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）（參考手冊）