微信小程序图片串行加载：Promise控制加载顺序的完整实践

做微信小程序开发，尤其碰到图集、漫画、长图、系列轮播这类需求时，很多人会直接被一个问题卡住：图片不是你想象中那样一张接一张地加载，而是所有请求一起发出去，谁先回来谁先显示。如果你只是展示一套普通商品图，这可能没什么；但如果业务上要求必须第一张加载完成后再加载第二张，那么并发加载的不可控性就会变成很大的麻烦。

之前我做一个漫画阅读器小程序时，就踩过这个坑。漫画页天然的依赖顺序：第一张没加载完，第二张即便先回来，也不能让用户先看到，否则剧情顺序就乱了。看起来是个很小的功能点，真正做起来才发现里面有 API 选型、Promise 串行控制、失败重试、缓存、进度反馈一堆问题。这篇文章就把我实现“按顺序一张图片加载完，再加载另一张”的完整思路和代码整理出来，适合正在做图集、阅读器、轮播、长图展示，或者想在微信小程序里控制图片加载顺序的开发者。

1. 业务场景梳理：哪些需求真正需要串行加载图片

先说结论，不是所有图片场景都适合做串行加载。普通列表页、商品详情页你如果也傻傻地串行加载，用户会等得想摔手机。真正需要“一张加载完，再加载另一张”的，我归纳下来主要有三类。

第一类是强顺序内容，比如漫画、绘本、分页小说配图、教程步骤图。这类图片之间存在严格的逻辑关系，用户必须按顺序阅读。并发加载时第二张可能先返回，如果你把先返回的图片直接渲染出来，用户会先看到后面的内容，再回头补看前面的，阅读体验非常割裂。我们当时采用的策略是：控制在用户视野内的图片必须按顺序加载，前面的图片加载失败也不会跳过渲染后面的，而是要重试或提示用户。

第二类是轮播图或自动播放场景。虽然很多轮播组件本身支持循环，但如果你的轮播里有大图、高清图，并发生成多个 Image 请求会占据大量网络带宽，导致当前展示的图片还没加载完，后面的图已经在抢资源了。串行加载在这里的意义是“保证当前播放的那张图永远优先加载”，不至于播到第二张时第二张还在转圈。

第三类是内存敏感的场景。微信小程序在部分低端 Android 机上的内存限制很严格，一次性创建多个 Image 对象并发加载大批高清图，经常会出现图片发白、页面卡顿，甚至直接被系统回收。串行加载配合及时释放图片对象，能让内存峰值降下来不少。我自己在测试机上对比过，同一组 20 张长图同时加载和串行加载，串行时内存占用峰值能降 30% 以上。

还有一类是测试和 Debug 场景。你写了一个加载时序相关功能，需要稳定复现“第一张先加载完再加载第二张”的状态，而并发加载的返回顺序不可控，很难复现时序 bug。串行加载把请求变成了严格的队列，任何问题都能稳定复现，定位起来非常方便。

那为什么不能直接靠 <image> 组件的 bindload 来解决？因为 <image> 组件只是图片的最终展示层，它自己会去发请求，你没办法控制它的请求节奏。bindload 只是告诉你“这张图在组件内部加载完成了”，如果页面里有 10 个 <image>，它们依然会同时请求。所以必须绕到组件之外，用 JS 层的图片加载 API 先把图片数据准备好，再交给 <image> 展示，这才是控制加载顺序的关键。

2. 加载方案选型：wx.getImageInfo 与 Image 对象的取舍

想控制图片加载顺序，第一步得选一个“能在 JS 层拿到加载结果”的 API。微信小程序里常用的有三个方向，我逐个讲下他们的特点和坑。

第一个是 <image> 组件自身的 bindload / binderror。它只能感知组件内部的加载结果，但你没法主动控制请求的时机，也没法在加载完成前把图片数据缓存起来。串行控制基本用不上它，但它非常适合“图片加载完成后做动画”这类的轻量交互。

第二个是 wx.getImageInfo。这是一个基础能力很稳的 API，传入图片地址，成功回调里能拿到图片的宽高、类型等信息。它的核心价值在于：无论图片来自网络还是本地，只要你调用了它，就相当于完成了一次“图片探测加载”。加载成功后，这张图片基本上已经进入了小程序自带的图片缓存体系，后续 <image> 组件去渲染同一个地址时，速度会快很多。所以用 wx.getImageInfo 做预加载和串行控制，是最自然的选择。

第三是 wx.createImage() 返回的图片对象，它模拟了浏览器里的 new Image()，可以给这个对象绑定 onload / onerror，然后手动设置 src 触发加载。这个方式在较早的基础库版本里就存在，灵活度很高，但它不返回图片宽高，需要自己再配合 wx.getImageInfo 去拿尺寸。而且个别小版本上 wx.createImage 的缓存策略表现不一致，我遇到过重复设置相同 src 时不会重新触发加载的问题。

我把这三种方式进行了一个对比，方便你选型：

我最终选择的是 wx.getImageInfo 配合 Promise 封装。因为这套 API 在真机上表现最稳定，而且它在加载成功后还能顺便拿到图片宽高，对后续做图片适配、占位、比例控制都有用。需要注意一点：wx.getImageInfo 请求网络图片时，同样受小程序 downloadFile 合法域名限制。开发调试时可以勾选“不校验合法域名”，上线前必须把图片域名配置到后台 downloadFile 白名单里，否则正式环境会直接进入 fail。这个问题排查过很多次，每次都是页面白图，一看控制台就是 url not in domain list。

还有，本地临时路径和代码包内的图片路径不需要域名配置，可以直接传给 wx.getImageInfo。如果你的图片是用户上传后返回的临时文件，那就更不用担心域名问题了。

3. 手写 Promise 串行加载器：完整实现与逐步拆解

选定 API 之后，剩下的核心工作就是写一个串行加载器。先看最简单的单张图片加载函数封装。

javascript复制function loadImage(url) {
  return new Promise((resolve, reject) => {
    wx.getImageInfo({
      src: url,
      success(res) {
        resolve(res)
      },
      fail(err) {
        reject(err)
      }
    })
  })
}

这个函数只是把 wx.getImageInfo 包成 Promise，让后续可以用 await 去等它。不要小看这步封装，有了它，你才能用 async/await 写出可读性极高的串行代码。接着是串行加载多张图片的核心函数。

javascript复制async function loadImagesInOrder(urls) {
  const results = []
  for (const url of urls) {
    // 每一张都 await，等上一张加载完成再进入下一次循环
    const imgInfo = await loadImage(url)
    results.push(imgInfo)
    console.log('已加载完成：', url)
  }
  return results
}

用 for...of 循环配合 await，是串行流程里最简单直观的写法。每一轮循环都会暂停在 await 这一行，直到当前图片加载成功或失败后，才继续执行下一次循环。这满足“一张图片加载完后，再加载另一张”的核心语义。

接下来把它用在 Page 里。假设我们有一个图片列表，要在一张加载完后把下一张的地址交给页面上的 <image> 组件。

javascript复制Page({
  data: {
    urls: [
      'https://example.com/1.jpg',
      'https://example.com/2.jpg',
      'https://example.com/3.jpg'
    ],
    currentIndex: 0,
    currentImage: '',
    loadedCount: 0,
    totalCount: 3
  },

  async onLoad() {
    const { urls } = this.data
    try {
      for (let i = 0; i < urls.length; i++) {
        await loadImage(urls[i])
        // 当前这张加载完成，更新页面展示
        this.setData({
          currentIndex: i,
          currentImage: urls[i],
          loadedCount: i + 1
        })
        console.log(`第 ${i + 1} 张加载完成`)
      }
    } catch (err) {
      console.error('加载中断：', err)
      wx.showToast({
        title: '图片加载失败',
        icon: 'none'
      })
    }
  }
})

页面里只需要一个 <image> 组件，src 绑定 currentImage。每加载完一张，setData 更新一次图片地址，视觉上就是严格按顺序切换。这种方式的优点是代码逻辑和 UI 展示一一对应，调试时每一步都清楚。

很多新手在这里会写错成 urls.forEach(async (url) => { await loadImage(url) })，这是没有用的。forEach 不会等待异步函数结束，它只是把每个回调都启动后就返回了，本质上还是并发请求。我在 code review 里见过很多次这种写法，结果就是页面依然是所有图片一起加载，顺序完全控制不住。想串行，就必须用 for...of 或者 reduce 链式 Promise。reduce 写法更函数式，但可读性不如 for...of，我更推荐后者。

还有一点要注意：setData 本身是异步的，但你在 await loadImage 之后立刻 setData，setData 会把数据更新到视图层。如果下一张图片加载很快，可能出现上一张的 setData 还没渲染完，下一张又触发 setData 的情况。这时候我建议在 setData 回调里再做下一张的加载，或者用一个简单的 loading 标记来避免并发更新。实际上微信小程序的 setData 是有队列机制的，连续多次调用会按顺序执行，所以大部分场景下不需要额外加锁，但如果你在真机上发现图片切换有闪动，就可以考虑用 setData 回调来卡一下节奏。

4. 踩坑复盘：加载失败、超时和顺序错乱的真实教训

光有串行加载的骨架还不够，真实项目里遇到的坑比基础逻辑多得多。我把自己踩过的几个重点问题列出来，每一个都是真金白银换来的经验。

第一个坑是失败处理。最开始我的 loadImagesInOrder 遇到任何一张图片加载失败，就直接 reject，整个流程中断。这在漫画阅读器里是不可接受的：某一张图因为网络波动加载失败，用户后面的所有内容都看不了了。后来改成“每张图最多重试 2 次，重试仍失败就跳过并把失败项记录到数组里”，至少保证后面的图还能继续加载。

javascript复制async function loadImageWithRetry(url, retries = 2) {
  for (let i = 0; i <= retries; i++) {
    try {
      return await loadImage(url)
    } catch (err) {
      if (i === retries) throw err
      console.warn(`第 ${i + 1} 次加载失败，重试中：`, url)
      await sleep(300 * (i + 1))
    }
  }
}

这里的 sleep 是简单的延迟函数，防止失败后立刻重试仍然命中同一个网络问题。重试间隔按次数递增，给网络恢复留一点时间。

第二个坑是超时。理论上 wx.getImageInfo 失败时会走 fail 回调，但我在某些真机上遇到过长时间没有回调的情况，请求既不成功也不失败，页面一直卡在加载中。后来加了一个手动超时控制，用 Promise.race 让加载 Promise 和超时 Promise 赛跑，超时了就按失败处理。

javascript复制function loadImageWithTimeout(url, timeout = 15000) {
  return Promise.race([
    loadImage(url),
    new Promise((_, reject) => {
      setTimeout(() => reject(new Error('图片加载超时')), timeout)
    })
  ])
}

超时时间我一般设置 15 秒。如果 15 秒都没加载出来，基本可以断定网络有问题，没必要继续等下去。注意超时后原来的 wx.getImageInfo 请求可能还在进行，最终其结果也不会再影响流程，因为 Promise 状态已经被 race 固定在 reject 上了。

第三个坑是顺序错乱。这个不是串行逻辑的问题，而是我在展示层出的错。当时页面里同时渲染了多个 <image> 组件，每个组件的 src 按数组索引绑定，然后我用 v-show 控制只显示当前图片。但实际运行时发现，当前显示的那张图总是先白屏一下才出现。排查后发现，虽然 JS 层是串行加载，但 <image> 组件拿到一个已经通过 wx.getImageInfo 加载过的图片地址时，有时并不会直接从缓存里取，而是会重新发一次请求，导致白屏。解决办法是结合 bindload 事件再控制显示：只有当 <image> 组件自己触发 bindload 后，才把这张图标记为“已显示”，在图片组件真正渲染完成前，给用户看一个占位背景。

第四个坑是缓存和内存。wx.getImageInfo 加载成功后会做缓存，但缓存空间并不是无限大的。一次加载几十张大图后，如果再频繁替换 src，低端机上依然可能出现内存告警。我的做法是把 wx.getImageInfo 返回的本地临时路径缓存到一个全局 Map 里，下次遇到相同 url 时直接返回缓存，不再重复请求。同时在一张图片不再需要展示时，把对应的 <image> 组件 src 设置为空字符串，让渲染层尽早释放图片资源。

javascript复制const imageCache = new Map()

function loadImageWithCache(url) {
  if (imageCache.has(url)) {
    return Promise.resolve(imageCache.get(url))
  }
  return loadImage(url).then(res => {
    imageCache.set(url, res)
    return res
  })
}

全局缓存的好处不仅在串行场景，对轮播、图集、重复进入页面的场景都非常有用。用户第一次进入页面时逐张加载，第二次再进入时大部分图片可以瞬间显示，体验提升非常明显。

第五个坑是真机兼容性。wx.getImageInfo 在 iOS 和 Android 上表现略有差异，主要表现在回调速度和缓存策略上。iOS 上偶发并发加载时回调乱序，但串行加载基本不会；Android 低端机上如果连续调用 wx.getImageInfo 频繁，可能出现加载队列阻塞，所以我在串行加载时会在每张之间留一个很小的空隙，比如 50ms，用 sleep 延迟一下，让底层网络请求有喘息机会。真机自测时，这个空隙对整体速度影响很小，但稳定性提升明显。

5. 体验优化进阶：预加载、进度反馈与并发上限控制

当核心串行逻辑跑通后，还有一个绕不开的问题：串行加载确实稳，但如果图片数量很多，用户等待时间会很长。直接串行加载 30 张图，每张按 200ms 算也要 6 秒，体验上还是有点折磨。所以我在真实项目里做了一些优化，让串行逻辑不变成“慢吞吞的串行”，而是“稳中带快的串行”。

第一个优化是“预加载下一张”。严格来说，这并没有违背“按顺序加载”的需求，因为串行控制是针对“展示顺序”的，不是针对“网络请求顺序”的。我的策略是：当前图片已经加载完成并展示后，提前开始下一张的加载；但不等它加载完成，页面仍然只显示当前图。当用户操作进入下一张时，下一张大概率已经准备好了，切换几乎无感知。

javascript复制let nextUrl = urls[currentIndex + 1]
if (nextUrl) {
  // 提前预加载下一张，但不阻塞流程
  loadImageWithCache(nextUrl).then(() => {
    console.log('下一张预加载完成')
  })
}

这种“当前展示严格串行，后台预加载下一张”的组合，在漫画阅读器里表现非常好。用户翻页时基本不需要等待，同时内存压力也比全量并发小很多。

第二个优化是进度反馈。串行加载天然能拿到“当前第几张 / 总共有多少张”的信息，所以加一个进度提示非常方便。我在页面上用了一个进度条组件，loadedCount 和 totalCount 都是现成的，加载完成一张就更新一次。特别是当用户等待时间较长时，明确的进度反馈能显著降低焦虑感。

javascript复制wx.showLoading({
  title: `正在加载第 ${currentIndex + 1} / ${total} 张`,
  mask: true
})
// 加载完成时 wx.hideLoading()

如果不想用系统 loading，也可以自己在页面上渲染一个百分比进度条。实测下来，当用户能看到“已经加载到第 8 张 / 总共 20 张”时，连续等待 10 秒也不会觉得特别难熬。

第三个优化是“并发数控制”。有些场景并不是必须严格 1 张 1 张来，而是需要“同时最多发 3 个请求，但返回结果必须按数组顺序处理”。举个例子：你有一个图集列表，用户快速滑动到第 5 张，但你不想让前 4 张全部串行加载完才显示第 5 张，而是希望先处理当前用户关注的一张，再回头补齐前边的。这种场景可以用一个简单的并发控制函数，限制最大并发数，同时把结果按照原始 URL 顺序返回。

javascript复制async function loadImagesWithLimit(urls, limit = 3) {
  const results = new Array(urls.length)
  let index = 0

  async function worker() {
    while (index < urls.length) {
      const current = index++
      const url = urls[current]
      try {
        results[current] = await loadImage(url)
      } catch (err) {
        results[current] = { error: err }
      }
    }
  }

  const workers = Array.from({ length: limit }, () => worker())
  await Promise.all(workers)
  return results
}

这个实现是经典的生产者-消费者模型。3 个 worker 同时从 URLs 数组里取任务，每个任务完成后把结果填到对应的索引位置，最终结果数组的顺序和传入的 URL 顺序完全一致。这样既保证了请求并发度，又保证了结果顺序稳定。如果你需求界于“纯串行”和“全并发”之间，这个函数可以作为升级版方案。

第四个优化是跟页面滚动结合。用户通常不会一到页面就看完所有图片，所以不需要把所有图片一次性加载完。我最常用的方案是：默认只加载第一张，当用户滚动接近当前图片底部时，再触发下一张的加载。这样天然形成了一个“按需串行”的加载链，既符合业务需求，又减少不必要的流量消耗。

javascript复制onPageScroll(e) {
  const { scrollTop } = e
  // 假设当前图片高度已知为 imageHeight
  if (scrollTop >= imageHeight * (this.data.currentIndex + 1) - 200) {
    this.loadNextImage()
  }
}

这种方式的体验最好，但逻辑复杂度也会增加。你需要维护当前已加载到哪一张、图片高度是否已知、是否正在加载中这些状态。如果你的图片是等高的，实现就简单很多；如果高度不固定，可以在 <image> 组件的 bindload 回调里获取高度并累加起来。

最后再说一个真实项目里让我印象很深的小细节：串行加载图片时，wx.getImageInfo 成功回调里的 res.path 通常是一个本地临时路径，如果你把它直接赋值给 <image> 的 src，在 iOS 上偶尔会出现图片闪烁的问题。后来我把 res.path 再做了一次 wx.saveFile 持久化缓存，第二次进入页面时直接从本地文件读取，加载速度接近零延迟。虽然代码量增加了，但对阅读类小程序来说，这个提升非常值得。

回到最开始说的漫画阅读器，我最终用的方案是“串行加载 + 下一张预加载 + 失败重试 + 本地缓存”。代码跑了一个多月，再也没有出现过图片顺序错乱、白屏和闪图的问题。如果你也在做类似功能，建议先跑通纯串行，再按我的进阶方案逐步优化，每一步都能看到明确的效果。这套思路不仅适用于微信小程序，换个壳也能平移到其他小程序平台，核心还是 Promise 控制异步流程那一套，吃透了就不会被“图片加载顺序”这个问题卡住。