---
title: '【教學】使用 Capacitor 將 Vue3 輕鬆打包成 APP！'
disqus: hackmd
---
# 【教學】使用 Capacitor 將 Vue3 輕鬆打包成 APP！


🚀 Vue 3 秒變行動裝置 APP，你相信嗎？
是不是覺得製作 APP 很複雜、還要學 Flutter/Java/Kotlin...😵‍💫 門檻好高？
別擔心！Vue 3 網頁應用程式一樣可以用 **Capacitor** 簡單地將它打包成原生 Android 或 iOS 的行動 APP！🎉🎉🎉

本篇以我自己工作上需求，將 Vue3 打包成 Android APK 為主做教學。

## 關於 Capacitor

### Capacitor 是什麼呢？🤔
你可能會覺得把這些內容變成 APP 是一個超級複雜的工程。 Capacitor 可以幫助你把熟悉的開發技術（例如 Vue3/Nuxt、React/Next）打包成Native APP，無論是 Android 還是 iOS 都辦得到！

### Capacitor 是如何運作的 🛠️

Capacitor 也和 Cordova 等工具一樣，會把你的專案包在一個 WebView 裡面，並且允許你使用手機的原生功能。這樣你的專案看起來、使用起來就像是一個真正的 Native APP！

### Capacitor 的好處 🌟
1. 能繼續使用你所熟悉的技術：不用學新的程式語言或工具框架！只要你熟悉前端三本柱，也就是 HTML/CSS/JavaScript，甚至是前端框架，那你已經具備了大部分必要的技能了哦！

2. 跨平台支援：可以同時幫你打包成 Android 和 iOS APP，不需要寫兩份程式碼。

3. 存取原生功能：想用手機相機📷？或者是 GPS 定位🌍？沒問題，Capacitor 內建了一些原生Plugin，讓你可以輕鬆存取手機內部的既有功能。

4. 持續更新：Capacitor 是 Ionic 團隊維護的專案，持續為它增加新的酷炫功能和修正問題，不需擔心使用到過時的技術！

準備好了嗎？一起來看看如何用 **Capacitor** 輕鬆將你的 Vue3 專案打包成 APP 吧！💪

## 確認是否安裝 Android SDK
在我們進行 Capacitor 環境安裝以前，請先確定已經安裝了 Android Studio，如果你還需要打包 iOS ipa 的話則也需要安裝 XCODE (過程可能會需要更新 OSX 系統)

:::info
如果你用的是Nuxt，設定上幾乎是一樣的，詳細可以參照Nuxt官網：
https://capgo.app/blog/building-a-native-mobile-app-with-nuxt-3-and-capacitor/#adding-capacitor-to-your-nuxt-3-app
:::


為了測試不同版本的Android，可以考慮將 7~14 版本的SDK都裝起來試試看！

## Capacitor 安裝教學

### **一、安裝核心套件**

如果你也跟我一樣需要用到檔案上傳、啟動相機等功能，一定要連同 filesystem 和 camera 一起安裝哦！

npm install @capacitor/core @capacitor/cli
npm install @capacitor/filesystem
npm install @capacitor/camera

### **二、初始化 Capacitor**

npx cap init


初始化的過程會詢問你要如何命名這個專案名稱、以及符合 Java 命名規則的 APP ID。
例如：`com.example.frontapp`

### **三、打包你的 Vue 專案並同步到 Capacitor**

npm run build

生成靜態資源目錄 dist 後，需要透過這個指令將 dist 複製過去 Capacito 下。

npx cap copy

### **四、在 Vue 專案中生成 Android 目錄**

npx cap add android

這個步驟會在你的專案中生成一個 android 目錄，包含原生的 Android 檔案結構。
:::info
這裡需要特別小心，如果你還沒安裝Android Studio，或者還沒安裝任何 SDK 的時候。
CMD會出現這樣的錯誤：
:::

npx cap sync

將打包好的 dist 同步到 android/app/src/main/assets 目錄中。

### **五、開啟 Android Studio 並進行打包**

npx cap open android

順利打開 Android Studio 的話，應該會看到這樣的檔案結構：

如果你想要先建立一個 debug 測試版本。
選取工具列的`Build -> Build Bundle(s) / APK(s) -> Build APK(s)`
如下圖：

等待IDE編譯結束就行了！
編譯完以後，可以在Vue專案的這個路徑下找到APK:

android/app/build/outputs/apk/AndroidTest/debug

此時就可以把APK檔案分享到雲端給你的裝置下載，或者微軟的VS APP Center之類服務來發布給團隊內的成員做測試！

## 開始測試你的APP

### Debug 版本

接著我們來測試這個debug版本的APP！

如果想要在 Android Studio 上模擬測試。
可以先新增一個虛擬行動裝置，在工具列選取 `Tools -> Device Manager`
右邊會出現這個視窗面板：

選擇你想測試的虛擬裝置硬體型號，以及API版本:

工具列選取 `Run -> Run 'app'`

這樣就可以看到你酷酷的APP了！

### Release 版本

如果你想生成 Release APK 並發佈到 Google Play 商店，必須對 APK 進行簽名。以下是簽名 Release APK 的步驟：

選取工具列的`Build -> Generate Signed Bundle / APK` 後，選擇「APK」。

接著我們需要新增一組新的keystore檔案。
這裡檔案的路徑和命名為`Android_keystore/test-release-key.keystore`
也需要加上密碼以供日後存取。


Key Alias 相關的欄位，這裡的 Alias 就填入這個APP的別名 Key 和密碼。
有效期設定至少 25 年，認證資訊可選填個人姓名或國家組織等訊息。
創建完成後，你就可以在 Key Alias 欄位選擇這個新創建的 Alias，並進行簽名。


最後選擇Vue專案內我們用來存放 Capacitor 轉包 Android APK 的位置後，選擇`release` 版本。
並確認app目錄的位置通常應該是 `<專案名稱>/android/app`。


Build結束後會在`<專案名稱>/android/app/release` 下看到release簽名版本的 APK 檔了！再來就根據 Google APP 商店規則上架即可！

## 添加APP icon 和 Splash Screen

### Step 1: 首先安裝`cordova-res`套件：

npm install cordova-res

:::info
由於 Android 在 8.0 以上版本的SDK(API Level 26)，開始引入了Adaptive Icons，開始使用了前景與後景圖片分層顯示的設計，用來確保不同裝置上保持一致性和自適應的關係，Cordova-Res 這個套件可能無法完全自動產生，需要手動來替換各種解析度下的`ic_launcher_foreground`
:::


### Step 2: 準備原始圖片

準備一個取名為`resources`的目錄在Vue專案裡。將icon和splash的原始大小圖片放進去，兩者的原始尺寸如下：

icon.png: `1024 x 1024 px`
slpash.png: `2732 x 2732 px`

需注意 Splash 圖片應該是中心對齊的，因為不同設備會裁剪不同的區域。

### Step 3: 生成圖片

接著命令列輸入：

npx cordova-res android --skip-config --copy
npx cordova-res ios --skip-config --copy

就可以自動產生各種解析度使用的圖片。
然後打開專案下的Android目錄查看轉好的圖片：


記得將這些路徑下的`ic_launcher_foreground`圖片也替換掉

<專案名稱>/android/app/src/main/res/mipmap-mhdpi
<專案名稱>/android/app/src/main/res/mipmap-hdpi
<專案名稱>/android/app/src/main/res/mipmap-xhdpi
<專案名稱>/android/app/src/main/res/mipmap-xxhdpi
<專案名稱>/android/app/src/main/res/mipmap-xxxhdpi

### Step 4: 測試換好圖片的 APP

完成！你的 APP 現在看起來更酷了對吧？


---

###### tags: `VueJS` `Vue3` `Capacitor` `打包APP` `Hybrid App` `Mobile Development` `APP開發` `跨平台APP開發` `前端開發` `Web Development`