uniapp开发避坑指南：常见问题与解决

做独立开发这几年，uniapp 几乎是我做小程序和 App 的首选框架。它一套代码多端运行确实省事，但真上手后会发现，坑也不少。这篇文章把我踩过的坑和常见问题的解决方法整理出来，希望能帮你少走弯路。

一、条件编译写不对，多端适配白费

很多人写条件编译时经常漏掉平台标识，导致代码在某一端直接报错。记住 uniapp 的条件编译是写在注释里的，格式必须严格：

// #ifdef MP-WEIXIN
console.log('只在微信小程序执行')
// #endif

// #ifndef H5
console.log('除了H5都执行')
// #endif

常见错误是把 #ifdef 写成 #ifdef 之外的形式，或者在 template、style 里用错语法。样式里的条件编译要用 /* #ifdef APP-PLUS */，别写成 //。

二、页面传参丢失或类型错误

页面跳转传参是最容易出问题的地方。通过 URL 传参时，参数会被转成字符串，对象和数组必须序列化：

// 传递
uni.navigateTo({
  url: '/pages/detail/detail?data=' + encodeURIComponent(JSON.stringify(item))
})

// 接收
onLoad(options) {
  const data = JSON.parse(decodeURIComponent(options.data))
}

如果参数里有特殊字符（比如 &、=），不编码就会截断。另外，navigateTo 不能跳转到 tabBar 页面，要用 switchTab。

三、生命周期混乱，数据不更新

uniapp 同时有应用生命周期、页面生命周期和组件生命周期，很多人分不清。几个高频问题：

• 在 onLoad 里请求数据，页面返回时不会重新触发，需要配合 onShow。
• 组件里用 onLoad 无效，组件要用 mounted 或 created。
• onReady 只触发一次，适合操作 DOM 或获取节点信息。

如果页面数据在返回后不刷新，把请求逻辑放到 onShow，或者用 uni.$emit 做事件通知。

四、样式不生效或跨端差异

样式问题主要集中在单位、选择器和平台差异上：

• 优先用 rpx，但要注意 rpx 在 App 端和 H5 端计算方式不同，复杂布局建议用 px 或百分比。
• 小程序不支持通配符 * 选择器，也不支持部分伪类。
• App 端默认没有 box-sizing: border-box，建议全局设置。
• 使用 scoped 时，子组件根节点样式可能穿透失败，可用 ::v-deep 或 /deep/。

五、请求封装与跨域问题

开发阶段 H5 跨域很常见，解决办法是在 manifest.json 里配置代理，或者用 uni.request 配合后端 CORS。生产环境建议统一封装请求：

const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      url: baseURL + options.url,
      method: options.method || 'GET',
      data: options.data || {},
      header: { 'Authorization': token },
      success: (res) => {
        if (res.statusCode === 200) resolve(res.data)
        else reject(res)
      },
      fail: reject
    })
  })
}

注意小程序端 uni.request 不支持 cookie 自动携带，需要手动处理 session。

六、打包与真机调试问题

打包 App 时常见白屏、闪退，多半是以下原因：

1. 没有配置 appid 或证书错误。
2. 使用了不支持的 API，比如 document、window。
3. 静态资源路径用了绝对路径，打包后找不到。

真机调试时，如果 HBuilderX 连不上手机，检查 USB 调试是否开启，或者改用自定义基座。小程序真机预览报错，先看开发者工具的 vConsole，再排查域名是否在白名单。

七、性能优化建议

• 长列表用 scroll-view 或 recycle-view，避免一次性渲染过多节点。
• 图片懒加载，使用 lazy-load 属性。
• 减少 setData 频率，合并数据更新。
• 分包加载，把非首屏页面放到子包。

总结：uniapp 开发的核心是理解多端差异，条件编译、生命周期、样式单位、请求封装这四块吃透，大部分问题都能迎刃而解。遇到报错先看控制台，再查官方文档，最后去社区搜，基本都能找到答案。