开发日志PC 端 Swiper 滚动顶部留白问题日期2026-07-09问题现象PC 端进入 Swiper Pin 区域后Swiper 顶部出现较大的白色留白影响页面展示。Mobile 端同样存在留白但留白大小符合设计作为上下间距正常因此无需修改 Mobile。排查过程1. 查看 Section 配置项首先检查与 Pin、Swiper 相关的配置项enable_pin: true,pin_position: ,pin_position_m: ,pin_scrollHeight:window.innerHeight * 5,pin_tabbar_distance: true初步怀疑问题与 Pin 固定逻辑有关。2. 阅读 Liquid 与 JavaScript发现pin_position是一个 Section 配置项在 Liquid 中读取后会传递给 GSAP ScrollTriggersection.settings.pin_position最终生成ScrollTrigger.create({start:trigger_str,end:scrollHeight,pin:true,scrub:true})由此确认pin_position实际对应的是ScrollTrigger 的start参数。它决定了Pin 从页面哪个位置开始生效并不是控制 CSS 样式。3. 使用 Chrome DevTools 分析使用 Chrome DevTools 观察 DOM 结构及页面表现。滚动前从代码结构看pin-spacer └── featured-swiper-container两者本身就是父子关系。但从页面视觉效果来看pin-spacer占据页面布局空间featured-swiper-container尚未进入固定状态。当页面滚动到 Pin 触发位置后featured-swiper-container进入 Pin 状态被固定在视口中pin-spacer继续负责占位保证元素脱离文档流后页面高度不会塌陷。因此可以确定顶部留白不是普通 CSSmargin、padding造成的而是 ScrollTrigger Pin 定位后元素固定位置导致的视觉留白。4. 验证过程分别尝试修改pin_scrollHeightpin_tabbar_distance均无法解决问题。继续定位到pin_position修改该配置后PC 端留白立即消失而 Mobile 端保持正常。原因分析默认的pin_position会根据代码自动计算distance_height_swiperwindow.innerHeight/2-swiperHeight/260;然后作为 ScrollTrigger 的start参数。由于计算结果使 Swiper 固定的位置距离浏览器顶部较远因此 PC 端进入 Pin 后上方出现了较大的空白区域。修改pin_position后Swiper 固定到更合适的位置因此顶部留白消失。最终解决方案修改配置项pin_position:top top调整 ScrollTrigger 的开始固定位置。结果✅ PC 端顶部留白消失。✅ Mobile 端保持原有间距效果。本次收获本次问题并不是CSSmarginCSSpaddingSwiper 本身而是GSAP ScrollTrigger 的 Pin 定位问题。以后遇到 Pin 模块相关问题可优先排查pin_positionpin_position_mpin_scrollHeightScrollTrigger.create()中的start、end、pinChrome DevTools 中pin-spacer的占位情况及 Pin 生效后的固定位置知识点GSAPGreenSock Animation Platform用于实现网页动画的 JavaScript 动画库。当前模块使用的是GSAP ScrollTrigger插件。ScrollTrigger负责监听页面滚动并控制动画执行。主要参数trigger监听的元素start开始触发的位置end结束位置pin是否固定元素scrub动画与滚动同步pin-spacerpin-spacer并不是 Liquid 输出的 HTML而是GSAP 在开启pin: true后自动创建的占位元素。作用保持原来的页面高度防止被 Pin 的元素脱离文档流后页面发生跳动配合固定定位实现滚动吸附效果。可以理解为页面滚动 │ ▼ ScrollTrigger 到达 start │ ▼ 创建 pin-spacer │ ▼ 固定 featured-swiper-container │ ▼ pin-spacer 保持原来的布局高度 │ ▼ 继续滚动Swiper 根据 Timeline 切换内容