uni-app 入门实战：跨端小应用从零搭建

uni-app 入门实战：跨端小应用从零搭建

一份个人学习笔记。最近在折腾跨端方案，选了 uni-app（基于 Vue 语法），记录从环境到跑通的过程，供自己留档，也给想"一套代码打多端"的同学参考。

1. 环境准备

uni-app 官方推荐用 HBuilderX，但更顺手的方式是用 CLI：

# 全局安装 vue-cli（已装可跳过）
npm install -g @vue/cli

# 创建 uni-app 项目（默认模板）
vue create -p dcloudio/uni-preset-vue my-uni-app

# 进入目录，运行到微信小程序
cd my-uni-app
npm run dev:mp-weixin

小坑：CLI 创建时会让你选模板，新手直接回车用默认 default 即可。模板代码里带了一堆示例页，第一次跑建议先别删，对照着看结构最快。

2. 路由与页面：pages.json 是核心

uni-app 不用 vue-router，页面和 tabBar 全在 pages.json 里声明：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": { "navigationBarTitleText": "首页" }
    },
    {
      "path": "pages/about/about",
      "style": { "navigationBarTitleText": "关于" }
    }
  ],
  "tabBar": {
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/about/about", "text": "关于" }
    ]
  }
}

关键约定：新增页面必须先在 pages 数组里登记，光建 .vue 文件是不会自动生效的。这是和 Vue SPA 最大的认知差。

3. 生命周期：应用级 + 页面级

// App.vue —— 应用级
export default {
  onLaunch() {
    console.log('App Launch')
  },
  onShow() {
    console.log('App Show')
  }
}

// pages/index/index.vue —— 页面级
export default {
  onLoad(options) {
    console.log('页面加载，参数：', options)
  },
  onShow() {
    console.log('页面显示')
  },
  onPullDownRefresh() {
    // 下拉刷新
  }
}

页面级用 onLoad / onShow / onReady 这套；如果你想用 Vue 的 mounted，在 H5 端能用，但在小程序端不会触发——跨端项目一律用 uni-app 的生命周期钩子，别混用。

4. 条件编译：一套代码，多端差异

不同端 API 有差异时，用条件编译注释隔离：

// #ifdef MP-WEIXIN
wx.login({ success: (res) => console.log(res.code) })
// #endif

// #ifdef H5
console.log('这段只在 H5 编译进包')
// #endif

样式也能条件编译：

/* #ifdef MP-WEIXIN */
.btn { padding-top: 20rpx; }
/* #endif */

5. 网络请求：自带 uni.request

uni.request({
  url: 'https://weiserv.com/api/v1/posts/',
  method: 'GET',
  success: (res) => {
    console.log('拿到数据：', res.data)
  },
  fail: (err) => {
    console.error('请求失败：', err)
  }
})

提醒：小程序端要求域名在后台白名单（HTTPS），本地调试可在开发者工具勾"不校验合法域名"。H5 端则受浏览器跨域限制，需要服务端配 CORS。

6. 小结

uni-app 的上手曲线对 Vue 开发者很友好：

维度	体会
路由	集中声明在 pages.json，新增页必登记
生命周期	用 uni-app 钩子，别混 Vue 的
多端差异	条件编译注释搞定
请求	uni.request 统一封装

个人感受：它不是"零成本跨端"，各端细节仍要逐个抠，但省下的重复脚手架工作量很可观。先把默认模板跑起来，再照着 pages.json 改结构，是最高效的起步路径。