引入：為什麼選擇uniapp開發鴻蒙？

隨着鴻蒙生態的快速發展，uniapp作為跨平台開發框架，為開發者提供了快速接入鴻蒙系統的能力。通過uniapp，你可以用一套Vue代碼同時運行到鴻蒙、安卓、iOS、小程序等多個平台，大大降低了多端開發的成本。今天，我們就從最基礎的環境搭建開始，帶你快速上手uniapp鴻蒙開發。

一、開發工具準備

1.1 必備工具清單

要使用uniapp開發鴻蒙應用，需要準備以下開發環境：

核心工具：

  • HBuilderX：v4.61+版本（推薦最新版），uniapp官方開發工具
  • DevEco Studio：5.0.3.402+版本（推薦5.0.7.210+），華為官方IDE
  • Node.js：v16+版本，建議使用LTS版本
  • 鴻蒙系統API版本：14+（通過osHarmonySDKAPIVersion獲取）

版本兼容性説明：

  • HBuilderX 4.24+要求DevEco Studio 5.0.3.400+
  • HBuilderX 4.31+要求DevEco Studio 5.0.3.800+
  • 鴻蒙系統版本需要API 12以上

1.2 工具下載地址

  • HBuilderX：https://www.dcloud.io/hbuilderx.html
  • DevEco Studio：https://developer.huawei.com/consumer/cn/deveco-studio/
  • Node.js：https://nodejs.org/

二、環境配置步驟

2.1 安裝DevEco Studio

下載並安裝DevEco Studio後，需要配置鴻蒙SDK：

  1. 打開DevEco Studio
  2. 依次點擊 Tools > SDK Manager
  3. 下載 HarmonyOS SDK 和 Build Tools
  4. 配置鴻蒙模擬器或連接真機

2.2 配置HBuilderX

在HBuilderX中配置DevEco Studio路徑：

  1. 打開HBuilderX
  2. 點擊菜單欄 工具 > 設置 > 運行配置
  3. 找到 鴻蒙(HarmonyOS) 配置項
  4. 填寫DevEco Studio的安裝路徑（例如：C:\Program Files\Huawei\DevEco Studio）
  5. 保存配置

配置文件位置：

  • Windows：%USERPROFILE%\.hbuilderx\settings.json
  • macOS：~/.hbuilderx/settings.json

三、創建第一個uniapp鴻蒙項目

3.1 新建項目

在HBuilderX中創建項目：

  1. 點擊菜單欄 文件 > 新建 > 項目
  2. 選擇 uni-app 類型
  3. 關鍵選擇：必須選擇 Vue3 版本（Vue2不支持鴻蒙）
  4. 輸入項目名稱，選擇默認模板
  5. 點擊創建

3.2 配置鴻蒙平台

打開項目根目錄的manifest.json文件：

{
  "name": "你的應用名稱",
  "appid": "你的應用ID",
  "description": "應用描述",
  "versionName": "1.0.0",
  "versionCode": "100",
  "platforms": ["harmony"],
  "app-plus": {
    "harmony": {
      "bundleName": "com.example.yourapp",
      "debuggable": true
    }
  }
}

關鍵配置項：

  • bundleName：應用包名，需符合鴻蒙規範（如com.example.myapp）
  • debuggable：是否開啓調試模式

四、項目結構解析

創建完成後，項目目錄結構如下：

your-project/
├── pages/                 # 頁面目錄
│   └── index/
│       ├── index.vue      # 首頁頁面組件
│       └── index.json    # 頁面配置
├── static/               # 靜態資源目錄
├── App.vue              # 應用入口文件
├── main.js              # 入口JS文件
├── manifest.json        # 應用配置文件
├── pages.json           # 頁面路由配置
└── uni.scss            # 全局樣式變量

核心文件説明：

  • manifest.json：應用名稱、版本、權限等配置
  • pages.json：頁面路由、導航欄樣式等配置
  • App.vue：應用生命週期函數
  • main.js：Vue實例初始化

五、運行到鴻蒙設備

5.1 配置調試證書

首次運行需要配置調試證書：

  1. 點擊HBuilderX菜單欄 運行 > 運行到手機或模擬器 > 運行到鴻蒙
  2. 在設備選擇對話框中，點擊 配置調試證書
  3. 填寫包名（與manifest.json中一致）
  4. 點擊 自動申請調試證書
  5. 保存配置

5.2 選擇運行設備

配置完成後，可以選擇運行到：

  • 鴻蒙模擬器：在DevEco Studio中啓動模擬器
  • 鴻蒙真機：連接手機並開啓USB調試模式

5.3 運行項目

點擊運行後，HBuilderX會自動：

  1. 編譯uniapp項目為鴻蒙工程
  2. 生成鴻蒙工程目錄（如unpackage/dist/dev/app-harmony）
  3. 安裝應用到設備
  4. 啓動應用

六、常見問題與解決方案

6.1 證書配置失敗

問題：調試證書申請失敗或簽名錯誤

解決方案：

  1. 確認包名格式正確（如com.example.myapp）
  2. 檢查網絡連接是否正常
  3. 重新運行配置調試證書

6.2 模擬器無法啓動

問題：鴻蒙模擬器黑屏或無法啓動

解決方案：

  1. 確認已安裝Hyper-V（Windows專業版/企業版）
  2. 重啓模擬器
  3. 檢查DevEco Studio版本兼容性

6.3 真機調試失敗

問題：無法安裝應用到真機

解決方案：

  1. 開啓手機的USB調試模式
  2. 確認已安裝鴻蒙系統14+版本
  3. 檢查USB連接是否正常

總結

通過本篇文章，你已經完成了uniapp鴻蒙開發環境的完整配置。我們學習了：

  1. 工具準備：HBuilderX + DevEco Studio + Node.js
  2. 環境配置：路徑設置、SDK下載
  3. 項目創建：Vue3項目創建與鴻蒙平台配置
  4. 證書配置：調試證書申請與配置
  5. 運行調試：模擬器與真機運行

現在你已經擁有了完整的開發環境，可以開始編寫你的第一個鴻蒙應用了。下一篇文章，我們將深入講解頁面佈局與基礎組件的使用，帶你構建第一個完整的鴻蒙應用界面。

温馨提示：開發過程中遇到問題，可以查看HBuilderX控制枱日誌，或訪問uniapp官方文檔（https://uniapp.dcloud.net.cn）獲取更多幫助。