uni-app 跨端开发实战：一套代码跑微信小程序和 H5

什么是 uni-app

uni-app 是 DCloud 推出的跨端框架，使用 Vue 语法编写，一套代码可编译到微信小程序、H5、App（iOS/Android）、支付宝小程序等十余个平台。底层原理是：编写时用统一 API，编译时针对各平台生成对应代码。

一、创建项目

两种方式：

方式一：HBuilderX（官方 IDE，可视化）
新建项目 → 选择 uni-app 模板（推荐 Vue3 + Vite 版）。

方式二：命令行 CLI

npx degit dcloudio/uni-preset-vue#vite my-uni-app
cd my-uni-app
npm install
npm run dev:mp-weixin   # 编译到微信小程序
npm run dev:h5          # 编译到 H5

推荐 CLI 方式，方便用自己熟悉的编辑器。

二、目录结构

my-uni-app/
├── src/
│   ├── pages/          # 页面，每个页面一个目录
│   │   └── index/
│   │       └── index.vue
│   ├── static/         # 静态资源
│   ├── App.vue         # 应用入口（全局生命周期、全局样式）
│   ├── main.js         # Vue 入口
│   ├── pages.json      # 页面路由与导航栏配置（类似小程序的 app.json）
│   ├── manifest.json   # 应用配置（appid、各平台配置）
│   └── uni.scss        # 全局样式变量
└── package.json

三、pages.json：路由与导航栏

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "enablePullDownRefresh": true
      }
    },
    {
      "path": "pages/detail/detail",
      "style": {
        "navigationBarTitleText": "详情"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#ffffff"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      },
      {
        "pagePath": "pages/detail/detail",
        "text": "详情"
      }
    ]
  }
}

第一项 pages 是首页（启动页），tabBar 配置底部导航。

四、写一个页面

页面就是一个 Vue 单文件组件，用 template + script + style：

<template>
  <view class="container">
    <text class="title">今日待办</text>

    <view class="item" v-for="todo in todos" :key="todo.id">
      <checkbox :checked="todo.done" @click="toggle(todo)" />
      <text :class="{ done: todo.done }">{{ todo.title }}</text>
    </view>

    <input v-model="newTodo" placeholder="输入新待办" confirm-type="done" @confirm="addTodo" />
    <button type="primary" @click="addTodo">添加</button>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const todos = ref([
  { id: 1, title: '学习 uni-app', done: false },
  { id: 2, title: '发布到微信小程序', done: false }
])
const newTodo = ref('')

function toggle(todo) {
  todo.done = !todo.done
}

function addTodo() {
  const title = newTodo.value.trim()
  if (!title) return
  todos.value.push({ id: Date.now(), title, done: false })
  newTodo.value = ''
}
</script>

<style scoped>
.container {
  padding: 24rpx;
}
.title {
  font-size: 40rpx;
  font-weight: bold;
}
.done {
  text-decoration: line-through;
  color: #999;
}
</style>

注意事项：

• 标签用 view、text、input、button 等 uni-app 内置组件，不是 HTML 的 div/span；
• 单位用 rpx（响应式像素），750rpx = 屏幕宽度，跨端自适应；
• 部分 Web 特性（如 v-html）在各端支持不一致，跨端场景尽量不用。

五、API 调用：uni.xxx 统一接口

// 请求
uni.request({
  url: 'https://api.example.com/todos',
  method: 'GET',
  success: (res) => {
    console.log(res.data)
  },
  fail: (err) => {
    uni.showToast({ title: '请求失败', icon: 'none' })
  }
})

// 本地存储
uni.setStorageSync('token', token)
const token = uni.getStorageSync('token')

// 页面跳转
uni.navigateTo({ url: '/pages/detail/detail?id=1' })

// 提示
uni.showToast({ title: '保存成功', icon: 'success' })
uni.showLoading({ title: '加载中' })

六、条件编译：处理平台差异

少数场景各平台实现不同，用条件编译注释区分：

<!-- #ifdef MP-WEIXIN -->
<view>只在微信小程序编译</view>
<!-- #endif -->

<!-- #ifdef H5 -->
<view>只在 H5 编译</view>
<!-- #endif -->

// #ifdef APP-PLUS
console.log('App 端（iOS/Android）专用逻辑')
// #endif

常用条件值：MP-WEIXIN（微信小程序）、H5、APP-PLUS（App）、MP-ALIPAY（支付宝小程序）。

七、运行与发布

微信小程序：

1. npm run dev:mp-weixin 生成 dist/dev/mp-weixin；
2. 用微信开发者工具”导入项目”选择该目录，填入自己的小程序 AppID；
3. 真机预览调试；
4. 发布时 npm run build:mp-weixin，在微信开发者工具里上传审核。

H5：

1. npm run dev:h5 本地调试；
2. npm run build:h5 构建 dist/build/h5，部署到任意静态服务器即可。

常见坑

1. 样式不一致：各端对 CSS 支持有差异，涉及兼容性的样式用条件编译单独处理；
2. uni.request 在小程序里需要配置合法域名（微信公众平台 → 开发设置 → 服务器域名），本地调试要勾选”不校验合法域名”；
3. 组件不能随便用 HTML 标签：跨端场景务必使用 uni-app 内置组件；
4. App 端发布：需要 DCloud 开发者账号打包，或者用云打包生成安装包。

总结

uni-app 的核心价值是”一份代码，多端覆盖”。上手重点：pages.json 路由配置、内置组件、uni.xxx API、条件编译。业务简单、追求多端覆盖的项目，用 uni-app 比分别维护小程序和 H5 高效得多。