10分钟上手Lenis：为你的网页添加平滑滚动

给你的网站装上「丝绸般顺滑」的滚动：Lenis 实战教程

网页滚动卡顿是前端体验的隐形杀手。当页面结构复杂或动画密集时，浏览器的原生滚动渲染管线容易丢失视觉连续性，让用户产生“卡帧 PPT”的错觉。解决这一痛点并不需要重构整个渲染逻辑，引入 Lenis 平滑滚动库是目前最高效的工程方案。它将平滑过渡计算叠加在浏览器原生滚动之上，完整保留 position: sticky、锚点跳转、无障碍访问等默认行为。跟随本文步骤，你将掌握从环境配置到高级联动的完整流程，为项目赋予专业级交互体验。

为什么选 Lenis？

选择 Lenis 而非其他同类库，核心在于其“非劫持”架构设计。许多历史滚动方案会完全接管滚动条行为，强行覆盖原生事件流，极易导致移动端手势冲突或辅助功能失效。Lenis 选择在原生滚动之上添加一层数学插值缓冲层。开发者拿到的依然是完整的 DOM 控制力与原生事件流，同时获得可配置的物理手感。这种设计大幅降低了接入成本，团队无需担心破坏已有的交互逻辑或浏览器底层行为。

第一步：安装与必加的 CSS

打开终端执行 npm i lenis 完成依赖安装。这里存在一个极易被新手忽略的关键细节：CSS 资源引入。Lenis 的平滑计算高度依赖一套特定的容器样式规则，用于规范滚动容器的溢出行为与高度计算。跳过样式加载直接编写 JavaScript，必然导致页面布局错乱或滚动事件静默失败。

务必在应用入口文件顶部添加：

import 'lenis/dist/lenis.css'

若项目为传统多页架构，可通过 <link> 标签直接引入 CDN 资源。确认样式正确挂载后，方可进入逻辑开发阶段。

第二步：核心初始化与参数调优

完成依赖准备，进入核心初始化环节。实例化 Lenis 时，传入的配置参数直接决定滚动物理手感：

import Lenis from 'lenis'

const lenis = new Lenis({
  duration: 1.2,
  lerp: 0.1,
  autoRaf: true
})

• duration：控制单次滚动的动画衰减总时长，数值越大拖尾感越明显。
• lerp：代表线性插值强度，区间为 0 到 1。官方推荐默认值 0.1。调高该值会提升跟手灵敏度，但可能损失平滑过渡的细腻感。
• autoRaf: true：自动将平滑计算绑定至 requestAnimationFrame 循环，免除手动维护渲染帧的繁琐工作。

建议项目初期严格采用默认配置跑通全流程，待性能基线稳定后再进行微调。过早将插值系数调至极端区间，极易引发主线程阻塞。可在 Chrome DevTools 的 Performance 面板中监控 Scripting 耗时，确保主线程空闲时间充足。

第三步：滚动事件监听与视差动画

掌握基础滚动后，下一步是将滚动数据实时映射为视觉动画。利用 lenis.on('scroll') 暴露的事件回调，可精准获取当前 scroll 位移量与瞬时 velocity 速度值。构建包含 Hero 区域标题与副标题的基础 DOM 结构后，在回调函数中编写映射逻辑：

const title = document.querySelector('.title')
const subtitle = document.querySelector('.subtitle')

lenis.on('scroll', ({ scroll, velocity }) => {
  // 标题随滚动淡出并上移
  title.style.opacity = Math.max(0, 1 - scroll / 400)
  title.style.transform = `translateY(${scroll * 0.3}px)`
  
  // 速度越大，副标题旋转越明显
  subtitle.style.transform = `rotate(${velocity * 0.05}deg)`
})

操作样式时必须严格遵循 GPU 合成原则，仅修改 transform 与 opacity 属性。这两类属性由合成线程独立处理，避免触发重排重绘，是维持 60fps 稳定帧率的铁律。绝对禁止在高频回调中修改 top、margin 或 height。

与 GSAP ScrollTrigger 帧同步

对于依赖 GSAP 生态制作复杂时间轴动画的团队，Lenis 提供了官方级同步方案：

const lenis = new Lenis()

lenis.on('scroll', ScrollTrigger.update)

gsap.ticker.add((time) => {
  lenis.raf(time * 1000)
})

gsap.ticker.lagSmoothing(0)

将 ScrollTrigger.update 直接绑定至 Lenis 滚动事件，同时通过 gsap.ticker.add 将 Lenis 的 raf 计算注入 GSAP 的独立时钟循环。配合关闭延迟平滑补偿，这套机制强制两套动画系统共享同一帧渲染周期，彻底消除因时间轴偏移导致的动画跳帧、元素错位或轨迹断裂问题。在组件销毁时，记得调用 lenis.destroy() 与 gsap.ticker.remove() 清理副作用。

常见坑点与防御性配置

生产环境部署时，需提前规避若干高频陷阱：

1. 锚链接跳转失效：Lenis 默认不拦截标准锚点跳转。需在初始化配置中显式声明 anchors: true 参数。
2. 嵌套滚动区域冲突：当页面存在弹窗、侧边栏等局部可滚动容器时，配置 allowNestedScroll: true 允许嵌套滚动，或在特定 DOM 节点上添加 data-lenis-prevent 属性阻断全局平滑介入。
3. iframe 环境失效：部分开发者在 <iframe> 嵌套场景中遭遇滚动失效，这源于浏览器同源策略与事件转发限制，属于底层安全规范而非库缺陷。
4. Safari 帧率限制：Safari 浏览器在特定版本或开启低电量模式时，会强制将渲染帧率锁定在 60fps 或 30fps。这是 WebKit 引擎的硬件调度策略，无需尝试通过参数突破。
5. 遗漏 CSS 资源：再次强调，这是导致表现异常的最常见原因，发布前务必通过 Network 面板校验样式加载状态。

进阶探索

跑通基础集成后，可进一步探索 lenis/snap 模块，实现类似幻灯片翻页的段落强吸附效果。React 与 Vue 生态开发者可直接引入 lenis/react 或 lenis/vue 官方适配器，利用生命周期 Hook 自动管理实例销毁与事件解绑。追求极致视觉表现的团队，可结合无限滚动机制与 WebGL 渲染管线，构建沉浸式数据可视化大屏。平滑滚动的工程本质是消除用户指尖操作与屏幕像素响应之间的认知摩擦。理解底层插值逻辑与性能边界，即可在任何复杂度项目中稳健落地。