uni-app 是一个使用 Vue.js 开发所有前端应用的跨平台框架。开发者编写一套代码，即可发布到 iOS、Android、H5、各类小程序（微信/支付宝/抖音等）以及鸿蒙（HarmonyOS）等多个平台。

结合最新的技术生态，以下是 uni-app 开发的完整指南：

一、 核心优势与适用场景

跨平台降本：一套代码多端运行，极大节省开发成本，非常适合需要同时覆盖 H5、小程序和移动 App 的中小型项目或快速原型开发。

学习成本低：基于 Vue.js 语法，前端开发者极易上手。

生态丰富：支持丰富的内置组件、API 以及 npm 第三方插件，扩展性强。

二、 开发环境搭建

基础依赖：确保安装最新版本的 Node.js（Vue3/Vite 版建议 v18+ 或 v20+）。

开发工具：

HBuilderX（官方推荐）：专为 uni-app 设计，集成了真机调试、跨端编译、云打包等核心功能。

VS Code + CLI：习惯 VS Code 的开发者可以通过命令行（如 npx degit dcloudio/uni-preset-vue）创建项目，配合 Vue 官方插件进行开发。

鸿蒙开发环境（2026新增）：若需发布到鸿蒙平台，还需安装 DevEco Studio（建议 5.1.1 及以上），并在 HBuilderX 中配置其安装路径。

三、 项目结构与核心开发

目录规范：

pages：存放页面文件（.vue）。

static：存放图片、字体等静态资源。

components：存放自定义组件。

manifest.json：应用配置文件（名称、图标、权限、各端 AppID 等）。

pages.json：配置页面路由和全局导航栏样式。

跨端适配（条件编译）：针对不同平台的差异，使用 #ifdef 和 #endif 语法进行条件编译。例如，在微信小程序端执行特定逻辑，或在 H5 端使用特定样式。

统一 API：使用 uni. 前缀调用 API（如 uni.request、uni.setStorage），编译器会自动将其映射为各平台的等效接口（如 wx.request、my.request）。

四、 调试与预览

多端预览：在 HBuilderX 中点击“运行”，可一键运行到浏览器、微信开发者工具、各平台模拟器或连接真机进行调试。

鸿蒙调试：支持模拟器与真机调试，可通过 Chrome DevTools 配合端口转发（如 hdc fport）调试业务逻辑层 JS 代码。

五、 打包与发布部署

H5 发布：执行 npm run build:h5，将生成的 dist/build/h5 目录下的静态文件部署至 Web 服务器。

小程序发布：执行 npm run build:mp-weixin，将生成的代码包导入微信开发者工具，提交审核并发布。

App 发布：使用 HBuilderX 的“发行 -> 原生App-云打包”功能，生成 iOS 和 Android 安装包（APK/IPA），随后提交至各大应用市场。

鸿蒙发布：编译后会生成完整的鸿蒙工程，可使用 DevEco Studio 打开进行签名配置与打包发布。

六、 避坑与进阶建议

性能限制：在复杂图形或重度动画场景下，帧率可能低于纯原生方案，需注意性能优化。

平台差异：尽管是一套代码，但不同平台（尤其是小程序和鸿蒙）的底层表现可能存在差异，需做好额外的适配工作。

接口安全：后端接口建议强制 HTTPS，采用 JWT 鉴权，并对敏感数据进行加密处理。

状态管理：推荐使用 Vuex 或 Pinia 进行全局状态管理，使用本地存储（uni.setStorage）处理轻量级数据缓存