企业官网建设流程全解析

别急着给代码加各种节流，先想清楚一件事：van-list的load事件为什么会"疯狂触发"？这个问题我在不同项目里至少踩过三次坑，每次表现都差不多——页面一进来就连续发好几个请求，滚动到底部又发一批，甚至上一轮请求没回来下一轮就已经出去了。排查到最后，绝大多数都不是组件本身的问题，而是你对它的触发机制理解有偏差。这篇文章我就把van-list的加载逻辑、常见误区和一套可以直接抄的解决方案一次性讲透。

1. 先搞懂van-list的触发逻辑，才不会瞎调

1.1 load事件到底什么时候会触发

van-list是移动端做滚动加载最常用的组件之一，核心逻辑很直白：监听滚动，当滚动条接近底部时触发load事件，然后你在这个事件里去请求下一页数据。但很多人的理解停留在这里，一旦出现问题就只能一顿乱试。

实际上，van-list的触发机制有三道闸门：

• loading状态：组件内部必须认为"当前没有在加载"，才会触发下一次load。
• finished状态：组件必须认为"数据还没有全部加载完"，才会继续触发。
• 滚动位置：必须满足"距离底部小于offset设定值"这个距离条件。

这三个条件同时满足，load才会被触发。van-list在滚动过程中会不断执行一次检查逻辑，这个检查不是等滚动停下来才做，而是滚动事件触发了就做。也就是说，只要这三个条件一直满足，它就会一直触发，看起来就像"停不下来"。

一个容易忽略的细节是：van-list触发load时，组件会尝试把loading置为true，用来挡住后续触发。但这个"置为 true"的动作要生效，前提是你必须使用v-model:loading做了双向绑定。如果只写了:loading="loading"这种单向绑定，组件内部的通知传不到你外面的变量上，外面的loading永远是false，组件就会觉得"没在加载啊，继续触发"，于是出现无限调用。

1.2 为什么会出现"连发"和"多发"

我见过最典型的场景有这么几类：

第一，loading状态没有做好闭环。要么忘了加v-model，要么在异步请求里没有在合适时机把它复位。组件判断不了你是否在加载，只能不断触发。

第二，首屏内容不足一屏。van-list默认开启immediate-check，初始化时如果发现内容填不满屏幕，会反复触发load直到内容填满或finished变为true。如果你的接口一次只返回两三条数据，页面上就会看到连续好几个请求打出去，这是"看起来像 bug"但其实是预期行为。

第三，分页参数没有正确更新。比如page值没有在请求成功后自增，每次请求拿到的都是同一页数据，列表长度没有变化，finished永远不能被赋值true，于是滚动到底就继续请求，形成死循环。

第四，滚动容器判断错位。van-list默认监听的是页面级别的滚动，如果你的列表在一个overflow-y: auto的 div 里，而这个 div 本身又是撑满屏幕的存在，滚动发生在 div 上而不是 window 上，van-list很可能监听不到正确的滚动事件，产生"怎么划都不触发"或"一进来就连续触发"的诡异现象。

用一个电梯门的类比来帮助理解：电梯门在关闭前会检测门缝里有没有东西，只要有东西就继续开门，门就一直开合个不停。这里的"门缝"就是滚动位置离底部的距离，而loading和finished就相当于有没有人在按"关门键"。你没有把这些状态管住，组件只能按照最保守的逻辑继续开门搬货。

2. 排查"重复触发"时要优先核对的五个位置

2.1 loading有没有真正实现"双向绑定"

这是出现频率最高的问题，没有之一。很多人写代码时意识到要在load事件里控制loading，但写法是：

<van-list :loading="loading" :finished="finished" @load="onLoad" >

注意这里用的是:loading，不是v-model:loading。当组件内部触发load时，虽然它想把loading改成true，但因为只是单向绑定，你外部的loading变量根本收不到这个变化。等滚动检查再次执行时，组件看到的仍然是loading = false，于是又触发一次。

正确写法应该是：

<van-list v-model:loading="loading" v-model:error="error" :finished="finished" @load="onLoad" >

如果你用的是 Options API 的 Vue 2 项目，v-model需要手动处理，或者写成:loading.sync。Vant 2 的 List 组件也支持v-model语法，用法类似。

经验之谈：调试这类问题时，先打开 Vue DevTools，看一下组件实例里loading的值是否会在触发load后自动变成true。如果一直停留在false，那大概率就是绑定方式写错了。

2.2 finished是不是被忘在角落里了

finished的作用是告诉组件："数据已经全部加载完了，别再触发load了。" 有一种常见的误操作是：只在onLoad里更新list，却从不判断数据是否已经全部加载完成。

举个例子，你请求第一页拿到了 10 条，第二页拿到了 5 条，第三页开始返回空数组。这时候如果不判断list.length >= total或data.length === 0然后设置finished = true，那么滚动到底部时，组件仍然认为"应该还有数据"，于是继续触发load，接口继续返回空数组，列表却一直在请求。这个问题在真机上尤其明显，因为网络请求有延迟，loading在请求完成后马上被置为false，你还没反应过来，下一次请求又发出去了。

一个比较稳妥的判断逻辑是：

if (list.value.length >= total || page.value > totalPages) { finished.value = true }

或者在接口返回的数组为空时直接设置finished = true，因为多数后端分页接口在下一页没有数据时都会返回空数组。

2.3 滚动容器和页面高度对不对

van-list对滚动容器的判定比较特殊，多数版本默认监听的是 window 的滚动事件。如果你的页面结构是：

<div class="page"> <div class="scroll-area"> <van-list @load="onLoad">...</van-list> </div> </div>

其中.scroll-area设置了height: 100vh; overflow-y: auto，而.page和body的高度都刚好是 100vh，那么真正滚动的是.scroll-area这个 div。但van-list监听的是 window 滚动，window 本身根本没动，组件自然无法正确判断"接近底部"这个条件。

这种场景下常见的结果有两种：一种是完全不触发load，页面滚到底也不会加载新数据；另一种是 mini 项目里 body 高度大于 100vh，window 也能滚，但滚动的距离和 div 内部不一致，导致load触发多次或时机错乱。

我处理这个问题时总结了两个方向：

• 如果可能，尽量让页面主体用 body 自身的滚动，也就是页面级滚动。van-list对页面级滚动的兼容是最好的，基本不会出问题。
• 如果必须用局部滚动容器，可以给滚动容器一个固定高度并让van-list保持在这个容器内，然后通过监听滚动容器的scroll事件手动判断是否接近底部，再用一个独立的函数去加载数据。注意这种方案下不要再依赖组件的自动触发，否则会叠加出重复请求。

补充一个小技巧：想知道当前页面到底是谁在滚动，可以在浏览器控制台执行：

document.scrollingElement.scrollTop = 100

然后看页面有没有变化。如果有变化，说明是页面级滚动；如果没有变化，说明滚动发生在某个子元素上。这样就能快速判断滚动容器对不对。

2.4 immediate-check带来的"首屏连环触发"

immediate-check默认是true，意思是组件初始化后立即检查一次是否需要触发load。这个检查会结合当前列表内容高度来判断——如果内容不足一屏，组件会认为"应该继续加载数据来填满屏幕"，于是触发load。加载完之后如果内容还是不足一屏，会再次触发，直到内容撑满或者finished为true。

很多同学看到页面刚加载就发出了五六个请求，第一反应是"组件坏了"，其实这是immediate-check的预期行为。解决方式有三种：

• 在数据量比较少、单页返回条数不多的情况下，把immediate-check设为false，让组件不要主动做首屏补全判断。
• 把单页数据量调大一点，比如一次返回 20 条，避免首屏内容不够。
• 在你的首次请求逻辑里，不要只处理第一页数据，可以一次性把前几页的数据合并返回，减少连续触发的次数。

不过我并不建议一味把immediate-check设为false，因为如果你确实是做移动端信息流，希望首屏能多加载几屏数据，那么组件这个自动补全行为其实是有价值的。关键是你要理解它为什么会连续触发，而不是因为它连续触发就一刀切关掉。

2.5 请求异常和参数更新不及时造成的"假重复"

还有一种"多次触发"不是组件的问题，是接口或参数的问题。

接口异常时，如果你的onLoad里没有try...catch...finally，请求失败后loading可能一直停在true或停在false。停在true会导致之后完全不触发；停在false则会导致用户再滚动一下，又发起相同的失败请求，看起来就像不断在加载，但其实每次都在调同一个报错接口。

分页参数不自增也是重灾区。很多新手会写：

const onLoad = async () => { const res = await fetchList(page.value, pageSize.value) list.value = list.value.concat(res.data.list) loading.value = false }

但忘了page.value += 1。这种情况下每次请求拿到的都是第一页数据，list的长度始终不变，finished永远不会为true，组件会一直触发load。这种问题从表面看就是"列表数据没增长，但请求发个没完"。

我的建议是：在onLoad里对分页参数的自增操作和finished的判断放在同一个代码块里，确保每次请求成功都同步推进状态。

3. 一套能直接抄的van-list加载方案

3.1 基础模板：Vant 4 + Vue 3

下面这套代码是我在实际项目里用得很顺的模板，已经处理了loading双向绑定、error状态、finished判断和分页自增，可以直接复制过去改接口地址使用。

<template> <div class="list-page"> <van-list v-model:loading="loading" v-model:error="error" :finished="finished" :finished-text="finishedText" :offset="offset" :immediate-check="immediateCheck" @load="onLoad" > <div class="list-item" v-for="item in list" :key="item.id" > {{ item.name }} </div> <template #empty> <div class="list-empty">暂无数据</div> </template> </van-list> </div> </template> <script setup> import { ref } from 'vue' const list = ref([]) const loading = ref(false) const finished = ref(false) const error = ref(false) const page = ref(1) const pageSize = 10 const total = ref(0) // 触发阈值：距离底部小于 100px 时触发加载 const offset = 100 // 关闭初始化时的自动检查，避免首屏不足一屏时连环触发 const immediateCheck = false const finishedText = '没有更多了' const fetchList = async (pageNo, size) => { // 这里替换成你的接口请求 const response = await fetch(`/api/list?page=${pageNo}&size=${size}`) const result = await response.json() return result } const onLoad = async () => { // 防御性判断：如果已经在加载或已加载完，直接返回 if (loading.value || finished.value) return try { const result = await fetchList(page.value, pageSize) list.value = list.value.concat(result.list) total.value = result.total if (list.value.length >= total.value) { finished.value = true } page.value += 1 } catch (e) { // 加载失败时显示错误状态，用户点击错误提示可重试 error.value = true } finally { loading.value = false } } </script>

Vant 2 + Vue 2 的写法差异不大，把<script setup>改成 Options API 的data和methods就行，核心逻辑保持一致。

3.2 关键参数解释和合理取值

有读者可能觉得参数太多记不住，我整理了一份速查表，按优先级从高到低排列：

offset的取值要结合屏幕高度来看。移动端屏幕高度一般在 600 到 800 像素之间，offset设成 300 意味着你才滑到屏幕一半左右，它就已经在请求下一批数据了。如果你的接口返回很快，用户感知不强，但如果接口比较慢，可能出现"页面数据还没渲染完，下一页又回来了"的情况。我一般取 100 到 200 之间。

3.3 加一个防并发和竞态处理的写法

前面提到，van-list自身会通过loading状态挡掉一部分重复触发，但在异步请求比较慢、用户滚动比较快的场景下，还是可能出现并发问题：上一次请求还没返回，下一次load已经触发，两次请求交叉返回，导致数据顺序错乱或重复。

一个简单有效的做法是在组件外部维护一个"请求序号"，每次load时递增，请求返回后判断序号是否还是最新的，不是就直接丢弃：

let requestSeq = 0 const onLoad = async () => { if (loading.value || finished.value) return const currentSeq = ++requestSeq try { const result = await fetchList(page.value, pageSize) if (currentSeq !== requestSeq) return list.value = list.value.concat(result.list) // 后续状态更新... } catch (e) { if (currentSeq !== requestSeq) return error.value = true } finally { if (currentSeq === requestSeq) { loading.value = false } } }

这个方案的好处是：即使用户滚动很快触发了多次load，只有最后一次请求的结果会被渲染，旧请求的结果不会污染列表。代价是实现稍微复杂一点，但对列表数据准确性要求高的项目，这点复杂度值得。

4. 真机调试经验与日志定位技巧

4.1 用日志把触发过程拉出来看看

遇到"load 触发多次"的问题，不要急着改代码，先把现象记录下来。我常用的方式是在onLoad里打印关键状态：

const onLoad = async () => { console.log('[van-list] onLoad triggered', { loading: loading.value, finished: finished.value, page: page.value, listLength: list.value.length }) // ... }

然后在浏览器里打开开发者工具，观察 Console 面板里的输出顺序。你会看到两种规律：

• 如果loading打印出来一直是false，说明双向绑定没生效。
• 如果page值在一串日志中保持不变，说明分页自增逻辑写错位置了。
• 如果listLength没有增加，但日志一直在刷，多半是接口返回的数据为空或数据格式不对。

在网络请求面板里，还可以看到请求的并发情况。如果出现多个请求几乎同时发出，说明loading的挡锁没有即时生效；如果请求是串行但很密集，说明是滚动触发链路中的状态没有及时复位。

4.2 三个真实的"假性多次触发"案例

案例一：首屏一口气发了 10 个请求。这是一个真实项目里遇到的，列表页一次返回 5 条数据，屏幕高度能容纳大约 15 条，immediate-check保持默认的true，组件在首屏反复触发load去补足高度。排查后确定的修复方案是：把immediate-check设为false，同时把单页数据量调整到 15 条，问题立刻消失。

案例二：页面滚动在一个 div 里，van-list完全不触发，但用户从上级页面返回后，它突然开始连续触发。这个问题的根因是页面的 body 高度因其他原因发生了变化，window 滚动事件被触发了一次，加上组件的immediate-check在重新激活时执行了一次检查，两个条件叠加导致没有经过正常滚动就触发了多次load。最终通过固定滚动容器为页面级滚动解决。

案例三：接口偶发超时，catch 里只弹了 toast，没有处理loading，导致报错后loading状态停在true，用户再滚动时无法触发新请求。但用户反复上拉下拽，页面表现是"一直在转圈"，网络请求却只有最开始那几次。这个不是"多次触发"，而是"触发后被卡死"，同样和状态管理有关。

4.3 容易和"load多次触发"搞混的周边报错

搜索这个问题时，你可能会看到一些看起来相似但根本不是一回事的报错，我列几个常见的帮你区分一下：

看到这些报错时，先判断它出现在哪个环节，再决定要不要往van-list的方向排查。很多时候问题根本不在这。

5. 一些容易被忽略的工程化细节

5.1 分页参数设计

分页参数设计看似简单，但决定了列表的稳定性和扩展性。

页码分页是最常见的，page从 1 开始，每次成功后自增，后端根据page和pageSize返回数据。优点是实现简单，前端逻辑直观，缺点是如果列表中间插入了新数据，页码翻页可能出现数据重复或遗漏。适合后台管理系统这种数据变动不剧烈的场景。

游标分页则是记录最后一条数据的唯一标识，比如lastId，每次请求带上这个值，后端返回该 ID 之后的数据。它的优势是列表新增数据时不会影响当前滚动位置，适合资讯流、评论列表这类实时性较强的场景。

我个人的建议是：如果后端愿意配合，优先使用游标分页；如果只能用页码分页，那就要在finished判断和加载状态上下更多功夫，避免重复数据带来的体验问题。

5.2 空数据、失败数据、全部加载完的边界处理

列表类组件的边界情况总是最考验代码健壮性的地方。

空数据：接口返回空数组时，直接给用户显示空状态，同时设置finished = true，避免组件继续触发load请求一个不会返回数据的接口。

失败数据：请求失败时设置error = true，Vant 会在列表底部显示错误提示，用户点击提示可以重新加载。注意重试时要把error先置为false，同时手动触发一次加载。有些项目会在失败时直接把error置为true后忘记复位，导致之后再怎么点都不触发加载，这个坑要小心。

全部加载完：设置finished = true后，组件会在底部显示finished-text指定的文案。如果你把文案设成"没有更多了"，用户一目了然。如果忘了设置finished-text，加载完之后底部会留白，用户可能还在傻等，以为页面卡住了。

5.3 封装一个通用列表组合式函数

当项目里有很多列表页时，重复的loading、finished、page、list状态管理会变得很啰嗦。我这里提供一个组合式函数的封装思路，你可以根据自己的业务习惯扩展：

import { ref } from 'vue' export function useList(fetcher, options = {}) { const list = ref([]) const loading = ref(false) const finished = ref(false) const error = ref(false) const page = ref(1) const pageSize = options.pageSize || 10 const load = async () => { if (loading.value || finished.value) return try { const result = await fetcher(page.value, pageSize) list.value = list.value.concat(result.list) if (list.value.length >= result.total || result.list.length === 0) { finished.value = true } page.value += 1 } catch (e) { error.value = true } finally { loading.value = false } } const refresh = () => { list.value = [] page.value = 1 finished.value = false error.value = false load() } return { list, loading, finished, error, load, refresh } }

页面里这样用：

const { list, loading, finished, error, load, refresh } = useList(fetchMyList, { pageSize: 15 })

模板里的van-list直接绑定返回的状态即可。收益是每次新增列表页，你只需要写接口函数和字段映射，重复的状态逻辑都在useList里统一处理了。

我在实际项目里踩过不少van-list的坑之后，最大的感受是：这类组件的"异常触发"绝大多数不是 bug，而是开发者和组件之间的状态契约没有对齐。loading、finished、page这三个变量，就像一个闭环里的三个齿轮，任何一个没有正确转动，整个链条都会出问题。调试时最快的路径，永远是先把这三个状态打出来看一遍，而不是去改offset或者加防抖。最后再分享一个小技巧：在页面上临时把loading和finished的值渲染出来，肉眼观察它们的变化节奏，往往比看控制台日志更直观，等逻辑稳定了再删掉。