uni-app 平台差异:数组 query、canvas 与 manifest

2026-11-19 前端开发 有希 38 次瀏覽

uni-app 有些故障不是代码写错,而是平台实现不同:H5 正常的数组参数,到小程序端被原生请求层拆坏;开发者工具导出的 jpg,实际是 png;改了 manifest 配置,第一次构建却没进产物。三个坑的共同点是:不能只看开发工具,要看真实请求、临时文件后缀和构建产物。

这些差异来自同一套 API 背后的不同实现。H5 走浏览器的请求和 Canvas,小程序走宿主提供的原生模块,App 又走另一套原生能力。业务代码看起来一样,序列化、文件格式和构建流程却各写各的,所以问题往往只在某一个端出现。

三个坑分别坏在哪

现象常见环境直接原因判断依据
数组筛选条件不生效小程序 / App原生请求层不按重复键序列化抓请求 URL,看是否出现 tag=a&tag=b
导出 jpg 得到 png微信开发者工具canvasToTempFilePath 忽略 fileType临时文件路径后缀是 .png
配置改了但产物没变首次构建 / dev 缓存生成物落后于配置源app.json 里的值仍是旧的

它们都不属于“语法错误”,所以类型检查和本地 H5 预览都不会报。下面逐个给最小复现。

数组 query:原生请求层不会替你保留重复键

先看一个看似正常的请求:

uni.request({
  url: '/api/activity/list',
  data: {
    tag: ['new', 'hot'],
    page: 1,
  },
})

H5 端可能得到 tag=new&tag=hot,也可能得到 tag%5B%5D=new,取决于底层实现;小程序和 App 的原生请求层又是另一套序列化。后端如果按重复键绑定,例如 Go 的 []string,它期望的是:

/api/activity/list?tag=new&tag=hot&page=1

一旦前端发成 tag=new,hot 或 tag[]=new,后端拿到的就是空数组或绑定失败。最稳妥的做法是把查询串的拼装收回自己手里:

export function serializeQuery(params: Record<string, unknown>): string {
  return Object.entries(params)
    .flatMap(([key, value]) => {
      const encodedKey = encodeURIComponent(key)

      if (Array.isArray(value)) {
        return value
          .filter(item => item !== undefined && item !== null)
          .map(item => `${encodedKey}=${encodeURIComponent(String(item))}`)
      }

      if (value === undefined || value === null)
        return []

      return [`${encodedKey}=${encodeURIComponent(String(value))}`]
    })
    .join('&')
}

const query = serializeQuery({ tag: ['new', 'hot'], page: 1 })
uni.request({ url: `/api/activity/list?${query}` })

这里有两个容易忽略的边界:

  • 空数组会被拼成空字符串,最终请求里没有 tag 这个键。后端要区分“不过滤”和“筛选为空”,需要提前约定:要么不传,要么显式传一个空值。
  • 不要把整个对象 JSON.stringify 后塞进一个参数。后端按表单/查询参数绑定时不会自动反序列化,等于把问题从序列化挪到了解析。

如果项目已有统一的请求拦截器,优先在拦截器里处理 query,不要让每个页面各拼一次。否则数组参数会在不同页面出现不同的写法,排查时很难确认到底发出去的是什么。

canvas:开发者工具会忽略 fileType

微信小程序的 2d canvas 导出通常这样调用:

uni.canvasToTempFilePath({
  canvas,
  fileType: 'jpg',
  quality: 0.8,
  success: (res) => {
    console.log(res.tempFilePath)
  },
})

真机上 fileType: 'jpg' 会得到 jpg 临时文件;微信开发者工具有一个已知差异:它忽略 fileType,恒导出 png。代码没有报错,上传也能成功,但文件类型、体积和后端校验都会和预期不一致。

判断方式不是看参数,而是看返回路径:

function isPng(path: string): boolean {
  return /\.png(?:$|\?)/i.test(path)
}

uni.canvasToTempFilePath({
  canvas,
  fileType: 'jpg',
  quality: 0.8,
  success: async (res) => {
    if (!isPng(res.tempFilePath)) {
      return res.tempFilePath
    }

    const jpg = await new Promise<string | null>((resolve) => {
      uni.compressImage({
        src: res.tempFilePath,
        quality: 80,
        success: (result) => {
          resolve(isPng(result.tempFilePath) ? null : result.tempFilePath)
        },
        fail: () => resolve(null),
      })
    })

    return jpg || res.tempFilePath
  },
})

uni.compressImage 在小程序端输出固定为 jpg,可以作为一次转码兜底;转换后仍要再判一次后缀,避免某些环境继续返回 png。还要注意 PNG 转 jpg 可能变大:如果既没有缩放,产物又比原图大,直接保留原图更合理。图片格式和体积的快速核对可以用 图片转 Base64 看编码结果,但最终仍以临时文件后缀和真机上传为准。

另一个与格式相关的细节是透明通道。jpg 不支持透明,绘制前要先铺白底,否则透明区域导出后会发黑;png 则不需要这一步。导出 jpg 和导出 png 不能共用同一套绘制准备,判断格式之后再把画布交给导出函数,逻辑会清楚很多。

manifest:生成物与构建时序

uni-app 项目里常见的结构是:manifest.config.ts 是配置源,src/manifest.json 是构建期生成的产物,并且被 .gitignore 忽略。构建插件在启动时读取配置源并写入生成物,uni-app 再消费生成物。生成物不提交,是为了避免手改和配置源分叉,但也意味着每次构建都多了一步“先写文件、再读文件”。

这条链多了一次文件写入,就出现了时序问题:改了 manifest.config.ts 后立刻构建,第一次可能仍读到上一次的 src/manifest.json;再跑一次构建就恢复。实测里 lazyCodeLoading 就遇到过这种情况,第二次构建后 app.json 顶层才出现正确值。开发进程的监听和缓存还会放大这个问题:文件时间变了,但消费方已经在内存里读过旧内容。

{
  "mp-weixin": {
    "lazyCodeLoading": "requiredComponents"
  }
}

验证时直接看构建产物,不要看开发服务的缓存:

pnpm build:mp
grep -n "lazyCodeLoading" dist/build/mp-weixin/app.json

还有两个容易误判的点:

  • dev 进程可能会清掉 dist/build,拿旧的 dist/dev 产物对照会得出完全相反的结论。要验证发布配置,就现跑一次 build:mp。
  • optimization 这类字段属于 project.config.json,不会出现在 app.json。在错误的文件里找字段,会误以为配置没生效。

如果第一次构建确实没更新,先删掉生成的 src/manifest.json 再构建,或者连续构建两次;同时确认构建日志里没有跳过生成步骤。不要把生成物手工改好并提交,下一次构建会被覆盖。CI 从干净目录开始构建,通常不会碰到这个问题;本地连续构建、增量缓存开着时才容易出现。顺序反过来,看到的永远是上一轮结果。

一张排查表

现象先看什么常见误判处理
数组筛选为空请求 URL 是否有重复键以为后端没收到参数统一序列化,数组展开成重复键
上传格式不对临时文件后缀以为 fileType 一定生效按后缀识别,必要时用 compressImage 转码
配置不生效构建产物 app.json拿 dist/dev 当发布产物重新构建,检查生成物时间与字段
第一次构建异常、第二次正常生成物是否落后以为代码有随机问题删除生成物或重跑构建

常见问题

为什么 H5 正常,小程序数组参数变成空? H5 的请求实现和原生小程序不同,数组的序列化规则不一致。不要依赖默认行为,显式拼重复键。

开发者工具导出 jpg,为什么拿到 png? 工具忽略 fileType,按返回路径后缀判断,再用 uni.compressImage 转一次。真机通常不会触发这段兜底。

改了 manifest 为什么第一次构建没生效? 生成物在构建期写入,第一次可能读到旧文件。重跑一次构建,或先删除生成的 src/manifest.json。

dist/dev 和 dist/build 应该看哪个? 验证发布配置看 dist/build;dist/dev 可能被开发进程清理或停留在旧状态。

升级 uni-app 能自动解决吗? 不一定。平台差异和插件版本都在变,升级后要重新验证请求、导出和产物,不能假设旧兜底仍然需要或仍然有效。

这三个坑看起来分散,本质都是“本地工具链的正常路径不等于真机路径”。同类的多端样式问题可以继续看 wot-ui 暗色主题排查,更多前端排错记录在 前端开发。

評論

登入後即可參與評論

還沒有評論,來說兩句吧

相關文章