PhoneGap:建置編譯環境

在《PhoneGap:用HTML5製作APP》中,有介紹如何使用Adobe的雲端服務來編譯PhoneGap的程式,但缺點是如果沒有支付費用,一個帳號只能同時擁有一個專案。除此之外,如果你需要安裝一些特殊的Plugin,甚至是自行撰寫Plugin時,免費帳戶是不支援此功能的。為了解決這些問題,我們可以自行在本機電腦上建置編譯環境,讓我們的電腦擁有將HTML5打包成APK的能力(iOS的話仍然需要使用Xcode編譯上傳至iTunes Connect)。

為了編譯PhoneGap,我們的電腦必須安裝不少東西。首先是Android所需要的環境,包括Java和Android SDK。不過只有這兩樣東西,電腦是不會自動幫我們編譯的。所以為了讓我們的電腦能自動編譯Java,我們需要安裝Apache Ant,才能達到自動編譯的功能。至於PhoneGap所需要的環境原則上就只有Node.js。若是想要自動安裝套件有幾種方式,安裝Git、GitHub,或是使用最新Cordova所提供的Plugman都可以。當然你也可以自行上網下載ZIP檔後,丟到本機的電腦上。由於大部份的第三方Plugin都會放在GitHub上,所以我自己是使用GitHub。

設定環境變數
上面的所有軟體都必須要設定環境變數。環境變數的用意是讓電腦知道你的執行檔在那裡。這邊我就偷懶一點轉貼Java的環境變數設定說明,請參考《我要如何設定或變更 PATH 系統變數?》。設定的路徑可以參考下面的列表。比較麻煩的大概就是GitHub,我每次安裝路徑都不一樣,要花點時間找一下。參考的路徑是「C:\Users\username\AppData\Local\GitHub\xxxxxxxx\bin」。

C:\Program Files\Java\jdk1.8.0_25\bin;
C:\Program Files\Java\apache-ant-1.9.4\bin;
C:\android-sdk\platform-tools;
C:\android-sdk\tools;
C:\Program Files\nodejs\;

安裝Cordova CLI
安裝並且設定好環境變數之後,我們就可以開始來安裝 PhoneGap,並且建立專案了。這裡要注意的是,Adobe PhoneGap 和 Apache Cordova 其實是不同的公司維護的專案。原則上 PhoneGap 是由 Cordova 為基礎發展出來的。在我們使用 command-line(CLI) 安裝 PhoneGap 時,建議大家安裝 Cordova 的版本,因為有些插件只認識 Cordova,使用上比較不會有問題。所以說,你會發現我們打的指令都是 Cordova,如果你想裝 PhoneGap 的版本,只要把 Cordova 改成 PhoneGap 即可。

接下來,請開啟電腦上的 command-line,找不到的話可以執行「cmd」指令。如果是使用 OS X 或 Linux 系統,在執行指令時可能會出現權限不足的錯誤訊息,此時只要在指令前加上「sudo」即可。與安裝相關的指令我都列在下面,建議大家記住自己編譯專案的 PhoneGap 版本。有時候新版本可能會因為 Bug 或是與插件相容性的問題,導致我們必須裝舊版的 PhoneGap,如果忘記自己之前安裝那一個版本,就只能一個版本一個版本地測式了。

安裝PhoneGap:npm install -g cordova
安裝指定版本的PhoneGap:npm install -g cordova@版本
取得各版本資訊:npm info cordova
檢查PhoneGap安裝版本:cordova -v
檢查PhoneGap最新版本:npm info cordova version
更新PhoneGap:npm update -g cordova
解除安裝PhoneGap:npm uninstall -g cordova

建立專案
環境建置完成後,就可以開始創建APP了。每個APP都是一個專案,建立專案後它會產生一個專案資料夾。以下的範例我們建立一個名為 myProject 的專案,APP 的 ID 是 tw.moke.sample,標題為 myProjectTitle。建立好專案之後,我們必須在這個專案底下加入我們想要編譯的平台。範例是以 Android 為例,如果是 iOS,只要把 android 換成 ios 即可。記得,除了建立專案的指令以外,其它的指令都要在專案目錄下執行,否則系統會告訴你所在位置不是一個 PhoneGap/Cordova 專案。

建立專案:cordova create myProject tw.moke.sample myProjectTitle
進入專案資料夾:cd myProject
編譯成Android平台:cordova platform add android
指定編譯Android版本:cordova platform add android@版本
升級平台版本:cordova platform update android@版本
移除平台:cordova platform remove android
檢查需要的安裝:cordova requirements
確認平台SDK版本:cordova platform version

下面是 PhoneGap/Cordova 專案的基本目錄結構。原則上我們只需要維護 plugins 與 www 資料夾,和 config.xml 即可。platforms 資料夾裡有著可以用 Android Studio 或 Xcode 開啟的專案,但是這個資料夾在你安裝插件或是更新版本時,都會被 PhoneGap 改寫。所以建議大家只有在程式寫完要打包成發佈檔時,再使用 Xcode 開啟(Android 可以完全不必經由 Eclipse 或 Android Studio 打包專案)。

myProject ─── hooks
├─ platforms (各平台編譯所需相關檔案與編譯後結果)
├─ plugins (PhoneGap插件安裝位置)
├─ www (HTML5)
└─ config.xml

安裝插件(外掛程式)
使用 HTML5 製作 APP 可以讓我們簡單撰寫介面操作的程式,但是有一些手機上的特殊功能,例如操作相機、陀螺儀等,還是必須仰賴原生的程式。不過大部份常用的功能都已經有人幫我們寫成插件(Plugin)的形式了,我們只要在PhoneGap中載入需要的插件,就可以使用插件語法來呼叫對應的功能(注意,相同功能的不同插件可能會採用不同語法)。使用 CLI 安裝插件,你不需要編輯 config.xml,只要在專案目錄下執行下面的指令即可。即使你沒有安裝 GitHub,仍然可以自行下載插件並且指定插件的位置,系統會自動將插件內容複製一份到 plugins 資料夾中。

安裝插件:cordova plugin add cordova-plugin-whitelist
安裝插件:cordova plugin add GitHub網址或本機的絕對/相對路徑
已安裝的插件列表:cordova plugin ls
插件移除:cordova plugin remove cordova-plugin-whitelist

如果你已經指定編譯的平台,在安裝插件時,系統會自動將檔案複製一份到 platforms 資料夾中對應的位置,例如 android/src/packagename。如果還沒有指定平台,則是在 platform add 時才會將檔案複製過去。使用插件的時候,別忘了在你的 HTML5 檔案<head></head>中加入 PhoneGap/Cordova 的 JavaScript 檔,有加入這份檔案,PhoneGap 就會自動幫你載入已安裝的插件檔案。

編譯專案
PhoneGap 在編譯時會進行兩個動作,第一是將 www 以及 config.xml 複製到對應的位置,第二是編譯原生程式。如果是 Android 平台,編譯完就可以在 platforms/android/build/outputs/apk 下找到 apk 檔,但是 iOS 平台的話只能使用 Xcode 編譯,所以在下達 build 指令之後,還是要用 Xcode 開啟 platforms/ios/ 下的 myProject.xcodeproj 檔案。事實上,iTunes Connect 上架也是要用 Xcode 上傳,所以只能老實地用 Xcode 編譯。不過由於 PhoneGap 在安裝/更新插件時都會修改 platforms 資料夾裡的內容,所以建議大家在開啟 Xcode 之後,任何的操作(例如參數設定)都要用文件記錄下來才好,否則將來更新時就會很麻煩……

編譯成所有平台:cordova build
編譯成指定平台:cordova build android

常用config.xml設定
建立專案時,系統會產生一份基本的 config.xml 檔,這份檔案在編譯時,會複製到 platforms/android/res/xml/ 或 platforms/ios/myProject/ 中。下面提供常用的參數設定,可自行選用,詳細的參數說明請參考官方文件

建立私人金鑰 (發佈到Android平台)
如果要把APP上架到 Android 的 Play 商店,我們必須把 apk 進行簽署才能上架,而簽署必須使用私人金鑰。一般來說,同一個作者/公司可以使用同一把金鑰,所以無論你擁有多少個APP,這個動作原則上只需要做一次。產生金鑰是透過 Java 的工具來完成。在 CLI 中輸入下面的指令,電腦會詢問你要設定的密碼,接著就會幫你產生一個私人金鑰的檔案(.keystore)。filename 是金鑰的檔案名稱,key_name 則是金鑰的名字(請用英文)。

簽署apk (發佈到Android平台)
如果你是使用 Eclipse 或 Android Studio,發佈簽署的 apk 時,系統會彈出視窗提示你該如何進行操作。如果你打算用 CLI 完成全部的工作,你需要編寫一份 release-signing.properties 的檔案,檔案的內容如下,對應上面私人金鑰的設定。寫好之後將這個檔案連同 .keystore 放至 projectRoot/platforms/android/,並且下達編譯簽署apk的指令,系統就會產生簽署過的apk檔。

編譯成簽署的apk檔:cordova build android — release

Originally published at 摩刻部落.