一套代码搞定小程序、App、H5，手把手带你走通全流程

前言：为什么要用 uni-app？

在跨端开发领域，uni-app 凭借其“一套代码，多端发布”的核心能力，已成为国内中小团队和独立开发者的首选方案。它基于 Vue.js 语法，支持编译到 iOS、Android、H5，以及微信、支付宝、抖音等十余个小程序平台。

HBuilderX 是 DCloud 官方为 uni-app 量身打造的专业 IDE，内置了从项目创建、代码编写到云端打包的全链路工具链，无需配置 nodejs 环境即可开箱即用。本文将从环境搭建开始，带你完整走完一个 uni-app 项目的开发与发布全流程。

---

一、开发工具安装与配置

1.1 下载 HBuilderX

访问 DCloud 官网下载 HBuilderX。建议下载 App 开发版，该版本内置了 uni-app 编译插件，可直接运行和发行 uni-app 项目。如使用标准版，首次运行 uni-app 项目时会提示自动安装插件。

https://img-blog.csdnimg.cn/direct/xxx.png
（示意图：HBuilderX 下载界面）

1.2 安装微信开发者工具（小程序调试必备）

若需要将项目运行到微信小程序，还需安装微信开发者工具。关键步骤：打开微信开发者工具 → 设置 → 安全设置 → 开启“服务端口”。未开启此选项会导致 HBuilderX 无法正常唤起小程序工具。

1.3 HBuilderX 首次启动设置

建议以 管理员身份 打开 HBuilderX，避免部分插件安装或文件读写时出现权限问题。

---

二、创建你的第一个 uni-app 项目

2.1 新建项目

打开 HBuilderX，点击顶部菜单 文件 → 新建 → 项目（快捷键 Ctrl+N）。

在弹出的窗口中：

• 选择项目类型：uni-app

• 输入工程名称：如 my-first-uniapp

• 选择模板：推荐选择 uni-ui项目 模板，该模板内置了大量常用组件，适合日常开发

点击“创建”按钮，项目即生成完毕。

2.2 认识项目核心目录

my-first-uniapp/
├── pages/              # 页面目录（每个页面一个文件夹）
│   └── index/          # 首页
│       └── index.vue   # 页面文件（模板+逻辑+样式）
├── static/             # 静态资源目录（图片、字体等）
├── manifest.json       # 全局配置文件（AppID、图标、权限配置）
├── pages.json          # 页面路由与窗口样式配置
└── App.vue             # 应用入口文件（全局样式、生命周期）

💡 提示：pages.json 是 uni-app 特有的路由配置文件，替代了 Vue Router 的路由方式，所有页面路径需在此注册。

---

三、运行项目到多端

3.1 运行到浏览器（H5端）

点击工具栏 运行 → 运行到浏览器 → Chrome（快捷键 Ctrl+R）。项目将自动编译并在浏览器中打开 H5 版本，适合快速预览 UI 效果。

3.2 运行到微信小程序

1. 点击 运行 → 运行到小程序模拟器 → 微信开发者工具

2. 首次使用需配置微信开发者工具安装路径：运行 → 运行到小程序模拟器 → 运行设置，填入工具路径

3. HBuilderX 会自动编译项目，生成的小程序代码存放于 unpackage/dist/dev/mp-weixin/ 目录，并自动唤起微信开发者工具进行预览

⚠️ 常见问题：如无法自动启动微信开发者工具，可手动打开工具，选择“导入项目”，路径指向上述 mp-weixin 目录即可。

3.3 运行到手机真机（App端）

1. 使用 USB 数据线连接手机，确保手机开启 USB 调试模式

2. 点击工具栏 运行 → 运行到手机或模拟器 → 选择设备

3. 如设备无法识别，可参考 HBuilderX 内置的“真机运行常见故障排查指南”

---

四、引入插件与组件扩展

HBuilderX 深度集成了 uni-app 插件市场，可一键导入第三方组件和模板。

操作步骤：

1. 打开 uni-app 插件市场，搜索所需插件（如抽奖转盘、图表等）

2. 在插件详情页点击 “使用 HBuilderX 导入插件”，HBuilderX 会自动下载并安装到项目的 uni_modules/ 目录下

3. 在页面中直接 import 插件组件即可使用

<template>
    <view>
        <almost-lottery :prizeList="prizeList" @finish="handleFinish" />
    </view>
</template>

<script>
import AlmostLottery from '@/uni_modules/almost-lottery/components/almost-lottery/almost-lottery.vue'

export default {
    components: { AlmostLottery },
    data() {
        return {
            prizeList: [
                { prizeId: 1, prizeName: "西瓜", prizeWeight: 10 },
                { prizeId: 2, prizeName: "苹果", prizeWeight: 20 }
            ]
        }
    },
    methods: {
        handleFinish(res) {
            console.log('抽奖结束', res)
        }
    }
}
</script>

插件导入后，部分插件需要按文档配置 manifest.json 或 pages.json，请仔细阅读插件说明。

五、项目发布与打包

5.1 发布为 H5 网站

点击菜单 发行 → 网站-H5手机版，HBuilderX 将在 unpackage/dist/build/h5/ 目录生成完整的静态网页资源，可直接部署到 Nginx 或云托管服务。

5.2 发布为微信小程序

1. 在 manifest.json 中配置微信小程序的 AppID

2. 点击 发行 → 小程序-微信，填写小程序名称和 AppID

3. 编译完成后，在微信开发者工具中打开生成的 unpackage/dist/build/mp-weixin/ 目录，点击“上传”按钮提交审核

5.3 打包为原生 App（云端打包）

1. 在 manifest.json 中填写 App 图标、启动图及应用名称

2. 点击 发行 → 原生App-云端打包

3. 选择 Android（APK）或 iOS（IPA）平台，填写证书信息（Android 可使用公共测试证书快速体验）

4. 点击“打包”，DCloud 云端服务器将自动编译并返回安装包下载链接

📌 提示：DCloud 的“安心打包”机制不会上传开发者代码和证书，通过差量包制作方式保护隐私安全。

---

六、常见问题与避坑指南

问题	解决方案
微信开发者工具无法启动	检查“服务端口”是否开启，或手动导入 mp-weixin 目录
手机真机无法识别	更换 USB 线缆，检查驱动，参考 HBuilderX 内置故障排查
打包失败提示“未配置 AppID”	在 manifest.json 中正确填写 DCloud 应用 AppID（需登录 DCloud 开发者中心创建）
运行时报“缺少编译插件”	检查 HBuilderX 是否为 App 开发版，或手动安装 uni-app 编译插件

---

总结

通过 HBuilderX 学习 uni-app，核心优势在于可视化操作 + 一键多端，大幅降低了跨平台开发的学习成本和环境配置门槛。从项目创建、运行调试到插件引入和最终打包，整个流程在 HBuilderX 内即可闭环完成。

接下来的学习建议：

1. 深入掌握 uni-app 的条件编译机制，实现不同平台的差异化适配

2. 学习 uniCloud 云开发，实现前后端一体化快速交付

3. 阅读官方 uni-app 组件库 文档，熟悉内置组件和 API