为什么选择 uni-app？

作为一名前端新手，你是否也曾被这样的问题困扰：想开发小程序，但微信的语法还没搞懂；想做个App，又得去学Android/iOS？uni-app 的出现正是为了解决这个痛点。

正如其标语“一套代码，发布到iOS、Android、H5、以及各种小程序” ，uni-app 结合了 Vue.js 的语法 和 微信小程序的组件与API 。这意味着，你只需要掌握 Vue，就能快速成为“全栈”多端开发者。

本文将手把手带你走过：环境搭建 -> 项目创建 -> 微信小程序运行 的全过程，并附赠新手最容易踩的 3个坑 的解决方案。

第一步：准备工作（下载工具）

工欲善其事，必先利其器。我们需要安装两个核心软件：

1. 下载 HBuilderX（官方强烈推荐）

下载地址：HBuilderX-高效极客技巧DCloud官网（HBuilderX板块）。

版本选择：下载 App 开发版。这个版本自带 uni-app 编译插件，开箱即用，无需配置 Node.js 环境，对新手极其友好 。

2. 下载微信开发者工具

下载地址：微信公众平台官网。

用途：用于预览和调试最终编译成的小程序代码。

关键设置（避坑点1）：安装后，打开微信开发者工具，点击 设置 -> 安全 -> 开启 “服务端口” 。如果这一步没开，HBuilderX 将无法自动唤起微信工具 。

💡 额外提示：你也可以使用 VSCode 进行开发，但需要自己配置 vue-cli 脚手架。对于新手，HBuilderX 的图形化操作能省去大量配置时间 。

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

打开 HBuilderX，点击顶部菜单栏 文件 -> 新建 -> 项目 。
在弹出的对话框中：
项目名称：输入你的项目名（例如：my-first-uniapp）。

选择模板：选择 uni-app 分类下的 uni-ui 项目模板。

为什么不选默认模板？ uni-ui 是官方提供的组件库，内置了大量常用组件（如轮播图、列表等），开发效率提升 40% 以上 。

点击 创建，等待项目结构生成完毕。

第三步：核心配置（AppID 与 路径）

这是连接 uni-app 和 微信小程序的关键一步。

1. 配置微信小程序 AppID

如果你已经有了微信小程序的 AppID，可以进行配置；如果没有，可以先使用“测试号”，但部分功能受限：如果你想要功能不受限制则需要去微信小程序自己去注册登录并复制AppID。

然后打开项目根目录下的 manifest.json 文件：

点击左侧菜单栏的 微信小程序配置。

在 appid 输入框中填入你的 AppID 。

2. 配置微信开发者工具路径（重要！）

为了让代码一键运行到微信，需要告诉 HBuilderX 你的微信工具装在哪里。

点击 HBuilderX 顶部菜单 工具 -> 设置 -> 运行配置。

找到 小程序运行配置 -> 微信开发者工具路径。

选择你电脑里 微信开发者工具.exe 的安装路径 。

第四步：一键运行到微信小程序

在 HBuilderX 中，打开项目，在项目目录上右键（或点击顶部菜单 运行）。
选择 运行到小程序模拟器 -> 微信开发者工具 。
观察效果：
HBuilderX 底部的控制台会开始编译，显示 Compiling...。

编译成功后，微信开发者工具会自动弹出来，你会看到你的 uni-app 项目已经在模拟器里跑起来了！

⚠️ 常见报错急救（90%的新手会碰到）
报错：“未找到微信开发者工具” 或 “请确认开发工具的服务端口已开启”

原因：没开启微信开发者工具的端口，或者路径填写错误。

解法：回到第一步，确认微信开发者工具的 安全 设置中 “服务端口” 是开启状态，且 HBuilderX 中的路径指向了正确的 .exe 文件 。

第五步：深度解读项目结构（小白必知）

pages.json：全局配置文件。它是 uni-app 的灵魂。

                     配置路由（哪行代码对应哪个页面）。

                     配置底部 TabBar（底部导航栏的图标、文字、颜色都在这里设置）。

                     配置导航栏标题。

manifest.json：应用配置文件。AppID、应用名称、权限申请都在这里 。

App.vue：入口组件。全局样式、全局生命周期监听（如应用启动 onLaunch）写在这里。

pages 目录：存放页面。每个 .vue 文件就是一个页面。

static：图片文件。整个项目的图片都需要放在这个文件。

uni.scss：全局样式变量文件，在这里定义的主题色，全项目通用 。

第六步：尝试简单开发（写一个 TabBar）

为了验证项目正常运行，我们来尝试修改 pages.json，自定义底部的 TabBar（这是面试和实际工作中最常用的功能）。

打开 pages.json，找到 tabBar 节点，参考以下代码进行修改：

"tabBar": {
    "color": "#7A7E83",      // 文字默认颜色
    "selectedColor": "#007AFF", // 文字选中颜色
    "borderStyle": "black",   // 边框颜色
    "backgroundColor": "#F8F8F8", // 背景色
    "list": [
        {
            "pagePath": "pages/index/index", // 页面路径
            "iconPath": "static/tab/home.png",   // 默认图标（需自己放入图片）
            "selectedIconPath": "static/tab/home_sel.png", // 选中图标
            "text": "首页"
        },
        {
            "pagePath": "pages/my/my",
            "iconPath": "static/tab/my.png",
            "selectedIconPath": "static/tab/my_sel.png",
            "text": "我的"
        }
    ]
}

保存后，你会发现微信开发者工具里的界面底部多了一个美观的导航栏！

新手高频 3 大“避坑”指南

1. 路径引用大坑：不要用绝对路径

在 H5 开发中，我们习惯写 <img src="/static/logo.png">，但在 uni-app 编译成小程序时，绝对路径可能不生效。

✅ 正确做法：使用相对路径。<image src="../../static/logo.png"></image> 。

2. 条件编译：一套代码，两套逻辑

有时候微信小程序和 H5 的 API 不一样。这时候不要写 if else 乱糟糟的代码，使用官方提供的 条件编译。

<!-- 仅在微信小程序中生效 -->
<!-- #ifdef MP-WEIXIN -->
<view>这里的内容只有微信小程序能看到</view>
<!-- #endif -->

<!-- 仅在 App 端生效 -->
<!-- #ifdef APP-PLUS -->
<view>这里的内容只有 App 能看到</view>
<!-- #endif -->

这个技巧是 uni-app 的精髓，掌握它，你就真正理解了跨端原理 。

3. 样式单位：rpx 与 px 的区别

px：固定大小，在不同屏幕上显示物理大小一样。

rpx：微信小程序和 uni-app 的魔法单位。它会根据屏幕宽度自动适配。建议：字体和宽高尽量使用 rpx，以保证在不同手机上的视觉效果一致 。

 结语

至此，你已经成功完成了：

1.✅ 搭建了 "uni-app + 微信小程序" 的开发环境。

2.✅ 创建并运行了第一个跨端项目。

3.✅ 配置了 TabBar 并了解了核心目录。

4.✅ 掌握了新手最常见的排坑技巧。

uni-app 的魅力远不止于此，后面你可以继续探索 Vue3 的组合式 API、Pinia 状态管理 以及 云端一体 的开发模式。