Uniapp 鸿蒙实战之 AtomGit APP - 环境搭建与项目初始化

千逐68

37人浏览 · 2026-07-05 13:40:12

千逐68 · 2026-07-05 13:40:12 发布

在这里插入图片描述

一、前言

随着鸿蒙生态的快速发展，越来越多的开发者开始关注鸿蒙原生应用的开发。而 Uniapp 作为一款优秀的跨平台框架，已经全面支持鸿蒙平台。本文将带你从零开始，搭建一个基于 Uniapp 的鸿蒙应用开发环境，并初始化 AtomGit APP 项目。

为什么选择 Uniapp + 鸿蒙？

一套代码，多端运行：Uniapp 支持 iOS、Android、鸿蒙、Web 等多平台
鸿蒙原生性能：编译为鸿蒙原生应用，性能接近原生
开发效率高：Vue 语法，上手快，生态丰富
未来趋势：鸿蒙生态崛起，提前布局

二、开发环境搭建

2.1 系统要求

操作系统	最低版本	推荐版本
Windows	Windows 10	Windows 11
macOS	10.14+	12.0+
Linux	Ubuntu 18.04	Ubuntu 22.04

硬件要求：

内存：建议 8GB 以上
磁盘空间：至少 10GB 可用空间
CPU：支持虚拟化技术（用于模拟器）

2.2 工具链安装

步骤 1：安装 Node.js

Uniapp 依赖 Node.js 环境，建议安装 LTS 版本（16.x 或 18.x）。

Windows 系统：

# 使用 chocolatey 安装
choco install nodejs-lts

# 或使用 nvm 安装
nvm install 18.16.0
nvm use 18.16.0

macOS 系统：

# 使用 homebrew 安装
brew install node@18

# 或使用 nvm 安装
nvm install 18.16.0
nvm use 18.16.0

安装完成后，检查版本：

node -v
# 预期输出：v18.16.0

npm -v
# 预期输出：9.x.x

步骤 2：安装 HBuilderX

HBuilderX 是 Uniapp 官方 IDE，内置鸿蒙开发支持。

访问 HBuilderX 官网下载安装包
安装完成后，打开 HBuilderX，安装插件：
- 点击菜单栏 工具 > 插件安装
- 安装"uniapp编译器"
- 安装"鸿蒙开发插件"
- 安装"内置终端"

插件安装示例：

// HBuilderX 插件配置示例（插件市场搜索）
{
  "plugins": [
    "uniapp-compiler",
    "harmonyos-development",
    "built-in-terminal"
  ]
}

步骤 3：安装 DevEco Studio

DevEco Studio 是鸿蒙官方 IDE，用于编译和调试鸿蒙应用。

访问鸿蒙开发者官网下载 DevEco Studio
安装完成后，配置 SDK：
- 打开 DevEco Studio，进入 File > Settings > SDK Manager（Windows/Linux）或 DevEco Studio > Preferences > SDK Manager（macOS）
- 安装 HarmonyOS SDK（建议 API 9+）
- 配置 SDK 存储路径（建议：C:\HarmonyOS\SDK 或 ~/HarmonyOS/SDK）

SDK 配置示例：

# SDK 路径配置
harmonyos.sdk.path=C:\HarmonyOS\SDK
harmonyos.sdk.version=3.1.0.331
harmonyos.ndk.version=1.0.0

步骤 4：配置环境变量

Windows 系统：

# 添加 DevEco Studio 到 PATH
[System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\Huawei\DevEco Studio\bin", [System.EnvironmentVariableTarget]::User)

# 添加 SDK 到 PATH
[System.Environment]::SetEnvironmentVariable("HARMONYOS_SDK_HOME", "C:\HarmonyOS\SDK", [System.EnvironmentVariableTarget]::User)

macOS/Linux 系统：

# 编辑 ~/.bashrc 或 ~/.zshrc
export DEVECO_STUDIO_HOME=/Applications/DevEco-Studio.app/Contents
export HARMONYOS_SDK_HOME=~/HarmonyOS/SDK
export PATH=$PATH:$DEVECO_STUDIO_HOME/bin:$HARMONYOS_SDK_HOME/toolchains

2.3 验证环境

创建验证脚本 verify_env.js：

const { exec } = require('child_process');
const os = require('os');

console.log('=== AtomGit APP 开发环境验证 ===\n');

// 验证 Node.js
exec('node -v', (error, stdout, stderr) => {
  if (error) {
    console.error('❌ Node.js 未安装或版本过低');
  } else {
    console.log(`✅ Node.js 版本: ${stdout.trim()}`);
  }
});

// 验证 npm
exec('npm -v', (error, stdout, stderr) => {
  if (error) {
    console.error('❌ npm 未安装');
  } else {
    console.log(`✅ npm 版本: ${stdout.trim()}`);
  }
});

// 验证 HBuilderX
const hbuilderxPath = os.platform() === 'win32' 
  ? 'C:\\Program Files\\HBuilderX\\HBuilderX.exe'
  : '/Applications/HBuilderX.app/Contents/MacOS/HBuilderX';

const fs = require('fs');
if (fs.existsSync(hbuilderxPath)) {
  console.log('✅ HBuilderX 已安装');
} else {
  console.error('❌ HBuilderX 未安装');
}

// 验证 DevEco Studio
const devEcoPath = os.platform() === 'win32'
  ? 'C:\\Program Files\\Huawei\\DevEco Studio\\bin\\devecostudio.bat'
  : '/Applications/DevEco-Studio.app/Contents/bin/devecostudio';

if (fs.existsSync(devEcoPath)) {
  console.log('✅ DevEco Studio 已安装');
} else {
  console.error('❌ DevEco Studio 未安装');
}

console.log('\n=== 验证完成 ===');

运行验证脚本：

node verify_env.js

预期输出：

=== AtomGit APP 开发环境验证 ===

✅ Node.js 版本: v18.16.0
✅ npm 版本: 9.5.1
✅ HBuilderX 已安装
✅ DevEco Studio 已安装

=== 验证完成 ===

三、创建 AtomGit 项目

3.1 使用 HBuilderX 创建项目

打开 HBuilderX，点击 文件 > 新建 > 项目
选择 uni-app 模板
填写项目信息：
- 项目名称：AtomGit
- 项目路径：选择本地目录（建议：D:\Projects\AtomGit 或 ~/Projects/AtomGit）
- 模板选择：默认模板（或选择 uni-ui 模板 如果需要进行 UI 快速开发）

点击"创建"，等待项目初始化完成。

3.2 项目目录结构

初始化后的项目结构如下：

AtomGit/
├── pages/                   # 页面目录
│   ├── index/              # 首页
│   │   ├── index.vue      # 首页组件
│   │   └── index.scss    # 首页样式
│   ├── repos/             # 仓库列表页
│   ├── repo-detail/       # 仓库详情页
│   └── ...
├── components/             # 组件目录
│   ├── repo-card.vue      # 仓库卡片组件
│   ├── file-tree.vue      # 文件树组件
│   └── ...
├── static/                 # 静态资源
│   ├── images/           # 图片资源
│   ├── icons/            # 图标资源
│   └── css/              # 全局样式
├── store/                  # Vuex 状态管理
│   ├── index.js          # Store 入口
│   ├── modules/          # 模块
│   │   ├── user.js      # 用户模块
│   │   └── repo.js      # 仓库模块
│   └── ...
├── utils/                  # 工具函数
│   ├── request.js        # 网络请求封装
│   ├── auth.js           # 认证工具
│   └── ...
├── unpackage/              # 编译产物目录
│   ├── dist/             # 编译产物
│   └── cache/            # 编译缓存
├── pages.json              # 页面路由配置
├── manifest.json           # 应用配置文件
├── uni.scss                # 全局样式变量
├── main.js                 # 入口文件
├── App.vue                 # 根组件
└── package.json            # 项目依赖配置

3.3 配置 manifest.json

编辑 manifest.json，添加鸿蒙平台配置：

{
  "appid": "__UNI__XXXXXX",
  "name": "AtomGit",
  "description": "AtomGit - 鸿蒙版 Git 客户端",
  "versionName": "1.0.0",
  "versionCode": "100",
  "uniStatistics": {
    "enable": false
  },
  "app-plus": {
    "modules": {
      "Contacts": {
        "description": "通讯录"
      },
      "Camera": {
        "description": "相机"
      }
    },
    "distribute": {
      "android": {
        "packagename": "com.atomgit.app",
        "permissions": [
          "android.permission.CAMERA",
          "android.permission.READ_CONTACTS"
        ]
      },
      "ios": {
        "appid": "",
        "mobileprovision": ""
      }
    }
  },
  "mp-harmonyos": {
    "appid": "com.atomgit.app",
    "name": "AtomGit",
    "version": {
      "code": 100,
      "name": "1.0.0"
    },
    "compileMode": "fastDev",
    "config": {
      "runtime": {
        "harmonyos": {
          "apiVersion": "9.0.0.0"
        }
      },
      "build": {
        "signingConfigs": [
          {
            "name": "default",
            "material": {
              "certpath": "harmonyos/certificates/debug.cer",
              "storePassword": "123456",
              "keyAlias": "debug",
              "keyPassword": "123456",
              "profile": "harmonyos/profiles/debug.p7b",
              "signAlg": "SHA256withECDSA"
            }
          }
        ]
      }
    }
  }
}

关键配置说明：

配置项	说明
`mp-harmonyos.appid`	鸿蒙应用的包名，必须唯一
`mp-harmonyos.compileMode`	编译模式，`fastDev` 为快速开发模式
`mp-harmonyos.config.runtime.harmonyos.apiVersion`	鸿蒙 API 版本，建议 9.0.0.0+
`mp-harmonyos.config.build.signingConfigs`	签名配置，用于应用打包

四、配置鸿蒙平台

4.1 创建鸿蒙配置文件

在项目根目录创建 harmonyos 文件夹，用于存放鸿蒙平台相关配置：

AtomGit/
├── harmonyos/                  # 鸿蒙平台配置
│   ├── certificates/          # 证书文件
│   │   └── debug.cer        # 调试证书
│   ├── profiles/             # 配置文件
│   │   └── debug.p7b        # 调试配置文件
│   ├── build-profile.json5   # 构建配置
│   └── app.json5             # 应用配置

4.2 配置 build-profile.json5

创建 harmonyos/build-profile.json5：

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "material": {
          "certpath": "certificates/debug.cer",
          "storePassword": "123456",
          "keyAlias": "debug",
          "keyPassword": "123456",
          "profile": "profiles/debug.p7b",
          "signAlg": "SHA256withECDSA"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "9.0.0.0"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "signingConfig": "default"
    }
  ]
}

4.3 配置 app.json5

创建 harmonyos/app.json5：

{
  "app": {
    "bundleName": "com.atomgit.app",
    "vendor": "AtomGit Team",
    "version": {
      "code": 100,
      "name": "1.0.0"
    },
    "apiVersion": {
      "compatible": 9,
      "target": 9,
      "releaseType": "Release"
    }
  }
}

五、运行到鸿蒙设备

5.1 连接鸿蒙设备

方式 1：真机调试

开启开发者模式：
- 打开鸿蒙设备，进入 设置 > 关于手机
- 连续点击"版本号" 7 次，开启开发者模式
启用 USB 调试：
- 进入 设置 > 系统和更新 > 开发者选项
- 启用"USB 调试"
连接电脑：
- 使用 USB 数据线连接鸿蒙设备和电脑
- 在设备上点击"允许 USB 调试"

方式 2：模拟器调试

打开 DevEco Studio
点击 Tools > Device Manager
创建鸿蒙模拟器：
- 选择设备类型（建议：Phone > Huawei Mate 50 Pro）
- 选择系统镜像（建议：HarmonyOS 3.1.0）
- 配置模拟器参数（RAM: 4GB, Storage: 16GB）
启动模拟器

5.2 编译运行

在 HBuilderX 中：

点击菜单栏 运行 > 运行到手机或模拟器 > 运行到鸿蒙设备
选择目标设备（真机或模拟器）
等待编译完成：
- HBuilderX 会将 Uniapp 代码编译为鸿蒙原生代码
- 自动安装应用到目标设备
- 启动应用

编译日志示例：

[INFO] 开始编译鸿蒙平台...
[INFO] 编译 Uniapp 代码...
[INFO] 生成鸿蒙原生代码...
[INFO] 打包 HAP 文件...
[INFO] 安装应用到设备...
[INFO] 启动应用...
[SUCCESS] 编译成功！应用已运行在鸿蒙设备上。

六、项目初始化代码

6.1 入口文件 main.js

import Vue from 'vue'
import App from './App'
import store from './store'

// 引入全局样式
import './static/css/global.css'

// 引入网络请求封装
import { request } from './utils/request'
import { auth } from './utils/auth'

// 挂载全局方法
Vue.prototype.$request = request
Vue.prototype.$auth = auth

Vue.config.productionTip = false

App.mpType = 'app'

const app = new Vue({
  store,
  ...App
})
app.$mount()

6.2 根组件 App.vue

<template>
  <view id="app">
    <router-view />
  </view>
</template>

<script>
export default {
  onLaunch() {
    console.log('App Launch')
    // 初始化应用
    this.initApp()
  },
  onShow() {
    console.log('App Show')
  },
  onHide() {
    console.log('App Hide')
  },
  methods: {
    async initApp() {
      try {
        // 检查登录状态
        const isLoggedIn = await this.$auth.checkLoginStatus()
        if (!isLoggedIn) {
          // 未登录，跳转到登录页
          uni.navigateTo({
            url: '/pages/login/login'
          })
        } else {
          // 已登录，跳转到首页
          uni.switchTab({
            url: '/pages/index/index'
          })
        }
      } catch (error) {
        console.error('初始化应用失败:', error)
      }
    }
  }
}
</script>

<style lang="scss">
/* 全局样式 */
page {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB',
    'Microsoft YaHei', 'Helvetica Neue', Helvetica, Arial, sans-serif;
  font-size: 28rpx;
  color: #333;
  background-color: #f5f5f5;
}

/* 清除默认样式 */
view, text, image {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}
</style>

6.3 首页实现 pages/index/index.vue

<template>
  <view class="container">
    <view class="header">
      <text class="title">AtomGit</text>
      <text class="subtitle">鸿蒙版 Git 客户端</text>
    </view>
    
    <view class="content">
      <button type="primary" @click="goToRepos">浏览仓库</button>
      <button type="default" @click="goToLogin">登录</button>
    </view>
    
    <view class="footer">
      <text class="version">版本: 1.0.0</text>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      title: 'AtomGit',
      isLoggedIn: false
    }
  },
  onLoad() {
    // 页面加载时检查登录状态
    this.checkLoginStatus()
  },
  methods: {
    async checkLoginStatus() {
      try {
        const result = await this.$auth.checkLoginStatus()
        this.isLoggedIn = result
      } catch (error) {
        console.error('检查登录状态失败:', error)
      }
    },
    goToRepos() {
      if (!this.isLoggedIn) {
        uni.showToast({
          title: '请先登录',
          icon: 'none'
        })
        return
      }
      uni.navigateTo({
        url: '/pages/repos/repos'
      })
    },
    goToLogin() {
      uni.navigateTo({
        url: '/pages/login/login'
      })
    }
  }
}
</script>

<style scoped lang="scss">
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 100vh;
  padding: 20px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.header {
  text-align: center;
  margin-bottom: 50px;
}

.title {
  font-size: 48px;
  font-weight: bold;
  color: #fff;
  text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.3);
}

.subtitle {
  font-size: 18px;
  color: rgba(255, 255, 255, 0.8);
  margin-top: 10px;
}

.content {
  display: flex;
  flex-direction: column;
  gap: 20px;
  width: 80%;
}

.footer {
  position: absolute;
  bottom: 20px;
}

.version {
  font-size: 14px;
  color: rgba(255, 255, 255, 0.6);
}
</style>

七、配图说明

在这里插入图片描述

说明：展示 Uniapp 开发鸿蒙应用的工具链架构，从代码编写到应用运行的完整流程。

图 2：项目初始化流程图

在这里插入图片描述

说明：展示项目初始化和运行的时序流程。

八、踩坑记录

问题 1：HBuilderX 无法识别鸿蒙设备

现象：

HBuilderX 中点击"运行到鸿蒙设备"时，无法找到已连接的鸿蒙设备。

原因：

鸿蒙设备未开启 USB 调试
DevEco Studio 未正确配置 SDK 路径
HBuilderX 的鸿蒙插件未正确安装

解决方案：

步骤 1：检查设备开发者选项

# 在鸿蒙设备上
设置 > 系统和更新 > 开发者选项 > USB 调试（启用）

步骤 2：配置 DevEco Studio SDK 路径

1. 打开 DevEco Studio
2. File > Settings > SDK Manager
3. 确认 HarmonyOS SDK 路径正确
4. 如果路径不正确，手动修改为正确路径

步骤 3：重新安装 HBuilderX 鸿蒙插件

1. 打开 HBuilderX
2. 工具 > 插件安装
3. 搜索"鸿蒙开发插件"
4. 卸载后重新安装
5. 重启 HBuilderX

问题 2：编译时报错"鸿蒙 SDK 未找到"

现象：

编译时出现错误：Error: HarmonyOS SDK not found.

原因：

manifest.json 中鸿蒙 SDK 路径配置错误
环境变量 HARMONYOS_SDK_HOME 未正确设置

解决方案：

步骤 1：检查 manifest.json 配置

{
  "mp-harmonyos": {
    "config": {
      "runtime": {
        "harmonyos": {
          "sdkPath": "C:/HarmonyOS/SDK"  // Windows 示例
          // "sdkPath": "/Users/username/HarmonyOS/SDK"  // macOS 示例
        }
      }
    }
  }
}

步骤 2：设置环境变量

# Windows PowerShell
[System.Environment]::SetEnvironmentVariable("HARMONYOS_SDK_HOME", "C:\HarmonyOS\SDK", [System.EnvironmentVariableTarget]::User)

# macOS/Linux
export HARMONYOS_SDK_HOME=~/HarmonyOS/SDK

步骤 3：重启 HBuilderX

环境变量更新后，需要重启 HBuilderX 才能生效。

九、总结

本文详细介绍了 AtomGit APP 的开发环境搭建和项目初始化过程。通过 Uniapp + 鸿蒙的组合，我们可以高效地开发出性能优异的跨平台应用。

关键要点回顾

环境搭建：安装 Node.js、HBuilderX、DevEco Studio，并配置环境变量
项目创建：使用 HBuilderX 创建 Uniapp 项目，并配置 manifest.json
鸿蒙配置：创建 harmonyos 目录，配置 build-profile.json5 和 app.json5
设备连接：真机调试或模拟器调试
编译运行：在 HBuilderX 中编译并运行到鸿蒙设备

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

HarmonyOS 小游戏《对战五子棋》开发第3篇-项目配置文件全解析

人工智能6S服务平台

OFDKIT-HARMONY 0.2.0 发布：鸿蒙原生 OFD 阅读库，已上架 OHPM

电子发票的「红章框」常常是 Foreground 模板，必须最后绘制，否则会被发票数据盖住。渲染顺序：模板 Background → 主页对象 → 模板 Foreground → 注释 → 签章。早期把「DeltaX 太小就用字符自然宽度兜底」的逻辑加进去，结果把负值也覆盖了，密码区直接错乱——后来改成负值跳过兜底。调用方自己注册字体到系统表（避免授权风险），然后告诉 Renderer 用这个 f