知识库

Appearance

uni-app 常见兼容性问题 ​

样式兼容性 ​

字体大小兼容性 ​

问题描述：不同平台的字体大小表现不一致，如微信小程序和 H5 平台的字体大小差异。

解决方案：

  • 使用 uni.scss 中定义的字体变量
  • 使用相对单位（如 rem、rpx）
  • 为不同平台设置不同的字体大小
  • 测试不同平台的字体表现

示例：

css
/* 使用 rpx 单位 */
.text {
  font-size: 32rpx;
}

/* 条件编译 */
/* #ifdef H5 */
.text {
  font-size: 16px;
}
/* #endif */

/* #ifdef MP-WEIXIN */
.text {
  font-size: 14px;
}
/* #endif */

样式选择器兼容性 ​

问题描述：不同平台对 CSS 选择器的支持不同，如某些选择器在部分平台不可用。

解决方案：

  • 使用基本的 CSS 选择器
  • 避免使用复杂的选择器
  • 为不同平台提供不同的样式
  • 测试不同平台的样式表现

示例：

css
/* 避免使用复杂选择器 */
/* 推荐 */
.text {
  color: red;
}

/* 避免 */
.container > .item:first-child {
  color: red;
}

布局兼容性 ​

问题描述：不同平台的布局表现不一致，如 Flex 布局在部分平台的差异。

解决方案：

  • 使用 uni-app 推荐的布局方式
  • 测试不同平台的布局表现
  • 为不同平台提供不同的布局
  • 避免使用平台特定的布局属性

示例：

css
/* 使用 Flex 布局 */
.container {
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  align-items: center;
}

API 兼容性 ​

API 支持差异 ​

问题描述：不同平台的 API 支持情况不同，如某些 API 在部分平台不可用。

解决方案：

  • 使用 uni-app 提供的跨平台 API
  • 使用条件编译处理 API 差异
  • 为不同平台提供不同的实现
  • 参考官方文档了解各平台 API 支持情况

示例：

javascript
// 使用条件编译
// #ifdef H5
// H5 平台特定 API
uni.showToast({
  title: 'H5 提示',
  duration: 2000
});
// #endif

// #ifdef MP-WEIXIN
// 微信小程序特定 API
wx.showToast({
  title: '微信小程序提示',
  duration: 2000
});
// #endif

API 参数差异 ​

问题描述：不同平台的 API 参数格式不同，如某些参数在部分平台不支持。

解决方案：

  • 了解各平台 API 参数的差异
  • 为不同平台提供不同的参数
  • 使用条件编译处理参数差异
  • 测试不同平台的 API 调用

示例：

javascript
// 条件编译处理参数差异
// #ifdef H5
uni.request({
  url: 'https://api.example.com',
  method: 'GET',
  success: (res) => {
    console.log(res.data);
  }
});
// #endif

// #ifdef MP-WEIXIN
wx.request({
  url: 'https://api.example.com',
  method: 'GET',
  success: (res) => {
    console.log(res.data);
  }
});
// #endif

组件兼容性 ​

组件表现差异 ​

问题描述：不同平台的组件表现不一致，如按钮、输入框等组件的样式和行为差异。

解决方案：

  • 使用 uni-app 提供的跨平台组件
  • 为不同平台提供不同的组件实现
  • 测试不同平台的组件表现
  • 避免使用平台特定的组件属性

示例：

vue
<template>
  <view>
    <!-- 使用跨平台组件 -->
    <button type="primary" @click="handleClick">按钮</button>
    
    <!-- 条件编译处理组件差异 -->
    <!-- #ifdef H5 -->
    <input type="text" placeholder="H5 输入框" />
    <!-- #endif -->
    
    <!-- #ifdef MP-WEIXIN -->
    <input type="text" placeholder="微信小程序输入框" />
    <!-- #endif -->
  </view>
</template>

组件事件差异 ​

问题描述：不同平台的组件事件表现不一致，如点击事件、输入事件等。

解决方案：

  • 使用 uni-app 推荐的事件处理方式
  • 测试不同平台的事件表现
  • 为不同平台提供不同的事件处理
  • 避免使用平台特定的事件

示例：

vue
<template>
  <view>
    <!-- 使用跨平台事件 -->
    <button @click="handleClick">点击按钮</button>
    <input @input="handleInput" placeholder="输入内容" />
  </view>
</template>

<script>
export default {
  methods: {
    handleClick() {
      console.log('点击事件');
    },
    handleInput(e) {
      console.log('输入事件:', e.detail.value);
    }
  }
};
</script>

网络兼容性 ​

网络请求差异 ​

问题描述：不同平台的网络请求表现不一致，如 H5 平台的跨域问题、小程序平台的域名配置问题。

解决方案：

  • 在 H5 平台使用代理或 CORS
  • 在小程序平台配置合法域名
  • 使用 uni-app 提供的网络请求 API
  • 测试不同平台的网络请求

示例：

javascript
// 使用 uni-app 网络请求 API
uni.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  success: (res) => {
    console.log(res.data);
  },
  fail: (err) => {
    console.error(err);
  }
});

网络状态差异 ​

问题描述：不同平台的网络状态检测表现不一致。

解决方案：

  • 使用 uni-app 提供的网络状态 API
  • 测试不同平台的网络状态检测
  • 为不同平台提供不同的网络状态处理

示例：

javascript
// 检测网络状态
uni.getNetworkType({
  success: (res) => {
    console.log('网络类型:', res.networkType);
  }
});

// 监听网络状态变化
uni.onNetworkStatusChange((res) => {
  console.log('网络状态变化:', res);
});

存储兼容性 ​

存储容量差异 ​

问题描述：不同平台的存储容量限制不同，如小程序平台的存储限制。

解决方案：

  • 合理使用存储，避免存储过多数据
  • 定期清理存储数据
  • 测试不同平台的存储容量
  • 为不同平台提供不同的存储策略

示例：

javascript
// 存储数据
uni.setStorage({
  key: 'userInfo',
  data: { name: '张三', age: 18 },
  success: () => {
    console.log('存储成功');
  }
});

// 获取数据
uni.getStorage({
  key: 'userInfo',
  success: (res) => {
    console.log('获取数据:', res.data);
  }
});

存储 API 差异 ​

问题描述：不同平台的存储 API 表现不一致。

解决方案：

  • 使用 uni-app 提供的存储 API
  • 测试不同平台的存储 API
  • 为不同平台提供不同的存储实现

示例：

javascript
// 使用 uni-app 存储 API
uni.setStorageSync('userInfo', { name: '张三', age: 18 });
const userInfo = uni.getStorageSync('userInfo');
console.log(userInfo);

媒体兼容性 ​

图片格式兼容性 ​

问题描述：不同平台对图片格式的支持不同，如某些图片格式在部分平台不支持。

解决方案：

  • 使用常见的图片格式（如 JPG、PNG）
  • 测试不同平台的图片格式支持
  • 为不同平台提供不同的图片格式

示例：

vue
<template>
  <view>
    <!-- 使用常见图片格式 -->
    <image src="/static/images/logo.png" mode="aspectFit" />
  </view>
</template>

视频格式兼容性 ​

问题描述：不同平台对视频格式的支持不同，如某些视频格式在部分平台不支持。

解决方案：

  • 使用常见的视频格式（如 MP4）
  • 测试不同平台的视频格式支持
  • 为不同平台提供不同的视频格式

示例：

vue
<template>
  <view>
    <!-- 使用常见视频格式 -->
    <video src="/static/videos/demo.mp4" controls></video>
  </view>
</template>

权限兼容性 ​

权限申请差异 ​

问题描述：不同平台的权限申请方式不同，如 H5 平台和小程序平台的权限申请差异。

解决方案：

  • 在 manifest.json 中配置权限
  • 使用 uni-app 提供的权限申请 API
  • 测试不同平台的权限申请
  • 为不同平台提供不同的权限申请方式

示例：

json
// manifest.json
{
  "mp-weixin": {
    "permission": {
      "scope.userLocation": {
        "desc": "用于获取您的位置信息"
      }
    }
  }
}

权限使用差异 ​

问题描述：不同平台的权限使用方式不同，如某些权限在部分平台的使用限制。

解决方案：

  • 了解各平台的权限使用限制
  • 测试不同平台的权限使用
  • 为不同平台提供不同的权限使用方式
  • 提供权限被拒绝的降级方案

示例：

javascript
// 申请位置权限
uni.getLocation({
  type: 'wgs84',
  success: (res) => {
    console.log('位置信息:', res);
  },
  fail: (err) => {
    console.error('获取位置失败:', err);
    // 提供降级方案
  }
});

性能兼容性 ​

渲染性能差异 ​

问题描述：不同平台的渲染性能不同，如 H5 平台和小程序平台的渲染性能差异。

解决方案：

  • 优化页面结构，减少 DOM 节点
  • 合理使用数据绑定，避免不必要的更新
  • 测试不同平台的渲染性能
  • 为不同平台提供不同的渲染优化

示例：

vue
<template>
  <view>
    <!-- 优化渲染性能 -->
    <view v-for="item in items" :key="item.id">
      {{ item.name }}
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      items: []
    };
  },
  mounted() {
    // 模拟数据
    this.items = Array.from({ length: 100 }, (_, i) => ({ id: i, name: `Item ${i}` }));
  }
};
</script>

启动性能差异 ​

问题描述：不同平台的启动性能不同，如小程序平台的启动速度和 H5 平台的启动速度差异。

解决方案：

  • 优化应用体积，减少主包大小
  • 使用分包加载
  • 延迟加载非关键资源
  • 测试不同平台的启动性能

示例：

json
// pages.json
{
  "subPackages": [
    {
      "root": "pages/sub1",
      "pages": [
        {
          "path": "index/index",
          "style": {}
        }
      ]
    }
  ]
}

最佳实践 ​

代码组织 ​

  • 按功能模块组织代码
  • 使用组件化开发
  • 合理使用目录结构
  • 统一命名规范

样式兼容 ​

  • 使用 uni.scss 变量
  • 使用相对单位
  • 测试不同平台的样式表现
  • 为不同平台提供不同的样式

API 兼容 ​

  • 使用 uni-app 提供的跨平台 API
  • 使用条件编译处理 API 差异
  • 测试不同平台的 API 调用
  • 为不同平台提供不同的实现

组件兼容 ​

  • 使用 uni-app 提供的跨平台组件
  • 测试不同平台的组件表现
  • 为不同平台提供不同的组件实现
  • 避免使用平台特定的组件属性

网络兼容 ​

  • 使用 uni-app 提供的网络请求 API
  • 处理 H5 平台的跨域问题
  • 配置小程序平台的合法域名
  • 测试不同平台的网络请求

存储兼容 ​

  • 合理使用存储，避免存储过多数据
  • 定期清理存储数据
  • 测试不同平台的存储容量
  • 为不同平台提供不同的存储策略

权限兼容 ​

  • 在 manifest.json 中配置权限
  • 使用 uni-app 提供的权限申请 API
  • 测试不同平台的权限申请
  • 提供权限被拒绝的降级方案

性能优化 ​

  • 优化页面结构，减少 DOM 节点
  • 合理使用数据绑定，避免不必要的更新
  • 使用分包加载
  • 延迟加载非关键资源
  • 测试不同平台的性能表现

总结 ​

uni-app 跨端开发中，兼容性问题是不可避免的。通过了解和掌握这些常见的兼容性问题及解决方案，可以提高开发效率，减少调试时间，打造出高质量的跨平台应用。在开发过程中，建议多测试不同平台的表现，及时发现和解决兼容性问题，确保应用在所有目标平台上都能正常运行。

基于 VitePress 的本地知识库

Copyright © 2026