uni-app 开发微信小程序的常见问题

在使用 uni-app 开发微信小程序的过程中，虽然框架提供了"一次开发，多端部署"的便利，但实际开发中仍会遇到各种平台特定的问题。本文整理了实际项目中遇到的常见问题及解决方案。

1. 样式兼容性问题

问题描述：在 uni-app 中编写的样式在微信小程序端无法正常显示，尤其是一些特殊的 CSS 属性。

常见症状：

flex 布局在某些情况下失效
滚动条样式不一致
rpx 单位在不同设备上显示异常

解决方案：

使用条件编译处理平台差异：

<style>
/* 所有平台通用样式 */
.container {
  width: 100%;
}

/* 仅微信小程序生效的样式 */
/* #ifdef MP-WEIXIN */
.wx-specific {
  display: flex;
  flex-direction: column;
}
/* #endif */

/* 仅H5生效的样式 */
/* #ifdef H5 */
.h5-specific {
  display: grid;
}
/* #endif */
</style>

避免使用微信小程序不支持的 CSS 特性，如：
- 避免使用 CSS 变量（或使用条件编译区分）
- 不要使用复杂的 CSS 选择器
- 小心使用position: fixed，可能导致层级问题

2. 微信登录授权流程踩坑

问题描述：微信小程序登录授权流程与其他平台不同，uni-app 封装后仍有一些特殊情况需要处理。

解决方案：使用 uni.login 结合条件编译适配微信授权：

// 登录函数
async function login() {
  // #ifdef MP-WEIXIN
  try {
    // 获取code
    const { code } = await uni.login();
    if (!code) {
      throw new Error("登录失败");
    }

    // 获取用户信息（新版微信小程序需要使用button授权）
    const userProfile = await getUserProfile();

    // 发送到服务器换取token
    const res = await uni.request({
      url: "登录接口",
      method: "POST",
      data: {
        code,
        userInfo: userProfile,
      },
    });

    // 存储登录状态
    uni.setStorageSync("token", res.data.token);
    return res.data;
  } catch (e) {
    console.error("微信登录失败", e);
    uni.showToast({
      title: "登录失败，请重试",
      icon: "none",
    });
  }
  // #endif

  // #ifdef H5 || APP-PLUS
  // 其他平台的登录逻辑
  // #endif
}


### 3. 页面生命周期与分包加载问题

**问题描述**：小程序有严格的包大小限制，分包加载配置不当会导致启动缓慢或超出大小限制。

**解决方案**：

1. 合理配置分包：

```js
// pages.json
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": { ... }
    }
  ],
  "subPackages": [
    {
      "root": "pagesA", // 分包根目录
      "pages": [ // 分包下的页面
        {
          "path": "detail/detail",
          "style": { ... }
        }
      ]
    },
    {
      "root": "pagesB",
      "pages": [ ... ]
    }
  ],
  "preloadRule": {
    "pages/index/index": { // 在首页预加载的分包
      "network": "all", // 在指定网络下预下载
      "packages": ["pagesA"] // 需要预下载的分包
    }
  }
}

针对微信小程序优化生命周期处理：

export default {
  data() {
    return { ... }
  },
  // 页面加载时
  onLoad() {
    console.log('页面加载');
    // #ifdef MP-WEIXIN
    // 微信小程序特有的处理
    wx.showShareMenu({
      withShareTicket: true,
      menus: ['shareAppMessage', 'shareTimeline']
    });
    // #endif
  },
  // 小程序特有的分享功能
  // #ifdef MP-WEIXIN
  onShareAppMessage() {
    return {
      title: '分享标题',
      path: '/pages/index/index',
      imageUrl: '/static/share.jpg'
    }
  },
  // #endif
}

4. 组件通信与跨端组件问题

问题描述：跨端组件在微信小程序端的表现与 H5/App 有差异，通信方式也需特别处理。

解决方案：

使用 uni.$emit和uni.$on 进行组件间通信：

// 组件A - 发送事件
methods: {
  sendMessage() {
    uni.$emit('custom-event', { data: 'hello' });
  }
}

// 组件B - 接收事件
created() {
  this.listener = (data) => {
    console.log('收到消息', data);
  };
  uni.$on('custom-event', this.listener);
},
beforeDestroy() {
  // 移除监听，防止内存泄漏
  uni.$off('custom-event', this.listener);
}

自定义组件使用 easycom 配置简化导入：

// pages.json
{
  "easycom": {
    "^u-(.*)": "@/components/u-$1/u-$1.vue"
  }
}

对于微信小程序特有组件，使用条件编译：

<template>
  <view>
    <!-- #ifdef MP-WEIXIN -->
    <official-account @error="handleError"></official-account>
    <!-- #endif -->

    <!-- 所有平台通用内容 -->
    <view>通用内容</view>
  </view>
</template>

总结

uni-app 在开发跨端领域的确是一个学习成本很低的框架，但是在很多时候你要盯着文档去查看平台之间的差异，这也挺耗费心神的