uni-app小程序开发入门与实践指南

1. 为什么选择uni-app作为小程序开发起点

三年前我刚接触小程序开发时，面对微信原生开发、Taro、uni-app等多个技术栈犹豫不决。最终选择uni-app的原因很简单——它允许我用熟悉的Vue.js语法同时发布到微信、支付宝、百度等多个平台。对于一个刚入门的开发者来说，这种"一次编写，多端运行"的特性极大地降低了学习成本。

记得第一次在HBuilderX中创建uni-app项目时，项目模板自带的hello world示例只用了不到5分钟就成功运行在了微信开发者工具中。这种近乎零配置的体验让我印象深刻，尤其对比当时需要手动配置各种loader的Webpack项目，uni-app的入门友好度确实令人惊喜。

新手提示：虽然uni-app支持多端发布，但实际开发中仍需注意各平台的能力差异。比如微信小程序的登录机制就和支付宝小程序完全不同，这些平台特性需要后期专门处理。

2. 从demo到真实项目的关键跨越

2.1 基础项目结构解析

一个标准的uni-app项目包含以下核心目录：

code复制├── pages
│   ├── index
│   │   ├── index.vue    # 页面组件
│   │   └── index.json   # 页面配置
├── static               # 静态资源
├── App.vue              # 应用入口
├── main.js              # 应用配置
└── manifest.json        # 跨端配置

初学者最容易混淆的是pages.json和manifest.json的区别：

• pages.json：控制页面路由、导航栏样式等应用级配置
• manifest.json：配置各平台特有的参数，如微信小程序的appid

2.2 首页典型组件实现

一个电商类小程序首页通常包含以下模块：

1. 轮播图：使用uni-app的<swiper>组件

vue复制<swiper :indicator-dots="true" :autoplay="true">
  <swiper-item v-for="(item,index) in banners" :key="index">
    <image :src="item.imageUrl" mode="aspectFill"></image>
  </swiper-item>
</swiper>

2. 商品网格：注意flex布局在iOS下的兼容问题

vue复制<view class="grid">
  <view 
    v-for="(item,index) in products" 
    :key="index"
    class="grid-item"
    @click="navToDetail(item.id)"
  >
    <image :src="item.thumb" mode="aspectFit"></image>
    <text class="title">{{item.name}}</text>
    <text class="price">¥{{item.price}}</text>
  </view>
</view>

3. 吸底工具栏：需要处理iPhoneX系列的安全区域

css复制.footer {
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
}

3. 开发环境配置要点

3.1 HBuilderX的实用插件

• uniapp-snippets：代码自动补全
• easy-less：LESS编译支持
• git-plugin：版本控制集成

3.2 微信开发者工具配置

1. 设置 → 安全 → 开启服务端口
2. 工具 → 项目设置 → 勾选"不校验合法域名"（开发阶段）
3. 调试 → 打开调试模式（解决真机预览白屏）

踩坑记录：如果修改了manifest.json中的微信小程序配置，必须重新运行"发行 → 小程序-微信"，单纯保存不会触发配置更新。

4. 数据请求的实战方案

4.1 封装uni.request

javascript复制const BASE_URL = 'https://api.yourservice.com'

export const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      url: BASE_URL + options.url,
      method: options.method || 'GET',
      data: options.data || {},
      success: (res) => {
        if (res.statusCode !== 200) {
          return reject(res.data)
        }
        resolve(res.data)
      },
      fail: (err) => {
        reject(err)
      }
    })
  })
}

4.2 接口调用示例

javascript复制import { request } from '@/utils/http'

export const getHomeData = () => {
  return request({
    url: '/home/data',
    method: 'GET'
  })
}

4.3 本地Mock方案

开发阶段可以使用easy-mock或本地json文件模拟接口：

javascript复制// 条件编译
// #ifdef H5
import mockData from '@/mock/home.json'
// #endif

export const getHomeData = () => {
  // #ifdef H5
  return Promise.resolve(mockData)
  // #endif
  
  // #ifndef H5
  return request({ url: '/home/data' })
  // #endif
}

5. 样式编写的注意事项

5.1 单位选择策略

• 字体：建议使用px
• 布局：建议使用rpx（响应式像素）
• 边框：使用px（部分Android设备rpx边框显示异常）

5.2 全局样式管理

在App.vue中引入公共样式：

vue复制<style lang="scss">
/* 注意要加scoped限制作用域 */
@import '@/styles/variables.scss';
@import '@/styles/mixins.scss';
</style>

5.3 常见布局问题解决

1. 滚动穿透：在弹窗出现时给底层页面添加overflow: hidden
2. fixed定位失效：在微信小程序中需要单独声明position: fixed
3. z-index层级：各平台实现差异较大，建议控制在10以内

6. 性能优化实践

6.1 图片懒加载

vue复制<image 
  :src="item.image" 
  lazy-load 
  :data-index="index"
  @load="imageLoaded"
></image>

6.2 数据分页加载

javascript复制export default {
  data() {
    return {
      page: 1,
      loading: false,
      noMore: false
    }
  },
  methods: {
    async loadMore() {
      if (this.loading || this.noMore) return
      
      this.loading = true
      const res = await getList({
        page: this.page
      })
      
      if (res.list.length < 10) {
        this.noMore = true
      }
      
      this.list = [...this.list, ...res.list]
      this.page++
      this.loading = false
    }
  }
}

6.3 组件按需注册

javascript复制// 只在需要的页面引入大组件
import heavyComponent from '@/components/heavy-component.vue'

export default {
  components: {
    heavyComponent
  }
}

7. 调试与发布技巧

7.1 真机调试要点

1. Android设备需要开启USB调试模式
2. iOS设备需要信任开发者证书
3. 使用uni.getSystemInfo()获取设备信息辅助调试

7.2 版本发布流程

1. 修改manifest.json中的版本号
2. 运行"发行 → 小程序-微信"
3. 使用微信开发者工具上传代码
4. 登录微信公众平台提交审核

7.3 常见审核被拒原因

1. 未提供测试账号
2. 页面存在空白或错误状态
3. 权限申请未说明合理用途
4. 内容不符合平台规范

8. 进阶开发建议

8.1 使用Vuex进行状态管理

javascript复制// store/modules/home.js
export default {
  namespaced: true,
  state: {
    banners: []
  },
  mutations: {
    SET_BANNERS(state, payload) {
      state.banners = payload
    }
  },
  actions: {
    async fetchBanners({ commit }) {
      const res = await getBanners()
      commit('SET_BANNERS', res.list)
    }
  }
}

8.2 混合开发方案

对于复杂功能，可以考虑：

1. 使用原生插件（Android/iOS）
2. 通过web-view嵌入H5页面
3. 使用uni-app的native.js直接调用原生API

8.3 多端适配策略

javascript复制// 条件编译示例
onLoad() {
  // #ifdef MP-WEIXIN
  console.log('微信小程序环境')
  // #endif
  
  // #ifdef H5
  console.log('H5环境') 
  // #endif
}

从demo到真实项目的转变过程中，最大的挑战不是技术实现，而是思维方式的转变。真实项目需要考虑异常状态、加载策略、用户体验等众多demo中不会出现的问题。建议新手在完成基础功能后，重点完善以下方面：

1. 页面加载状态管理（骨架屏/loading）
2. 网络异常处理
3. 数据缓存策略
4. 用户操作日志记录

这些细节往往决定着项目的最终质量。