Lenis 平滑滚动快速指南：几行代码让网站滚动不卡顿-平芜编程栈

Lenis 平滑滚动快速指南：几行代码让网站滚动不卡顿

【免费下载链接】lenisSmooth scroll as it should be项目地址: https://gitcode.com/GitHub_Trending/le/lenis

Lenis 是一款压缩后仅几 KB、零依赖的平滑滚动库，直接包裹浏览器原生滚动工作。读完这篇，你能用几行代码接入 Lenis 平滑滚动，调出自己想要的滚动手感，并把它和 GSAP、React、Vue、Three.js 串联起来。

为什么是 Lenis

原生滚动一帧一帧地跳；自己写 transform 假滚动，又会把 sticky、锚点、无障碍全搞坏。Lenis 走的是第三条路：滚动位置仍是浏览器自己的，position: sticky、锚点跳转、读屏软件照常工作，它只负责把每一帧算平滑。

体积上，核心库压缩后仅几 KB，无任何运行时依赖。单个实例同时支持垂直、水平、嵌套容器滚动；一个循环就能驱动 parallax、WebGL 场景和 GSAP ScrollTrigger，不会出现多个动画循环互相打架。React、Vue、Framer 有官方适配包，lenis/snap 插件补齐分段吸附。

🚀 3 行代码接入 Lenis

import Lenis from 'lenis' import 'lenis/dist/lenis.css' const lenis = new Lenis({ autoRaf: true }) lenis.on('scroll', (e) => { console.log(e.scroll, e.progress) })

autoRaf: true表示由 Lenis 自己跑 requestAnimationFrame 循环，否则你需要每帧手动调用lenis.raf(time)。那行 CSS 别省，缺了它就会出现抖动、sticky 错位这类布局问题。没有构建步骤的项目也可以只挂一个 script 加 CSS 跑起来，顺便开autoToggle和anchors，能自动处理弹窗和锚点跳转。

🎛 调出你想要的滚动手感

参数不多，每个都有明确用途：

参数	默认值	它是干什么的，调了会怎样
`duration`	1.2	滚动缓动时长（秒），调大停得更慢
`lerp`	0.1	惯性强度（0–1），调大滑行余韵更长
`easing`	内置指数衰减	缓动曲线，换一条曲线手感全变
`wheelMultiplier`/`touchMultiplier`	1	滚轮 / 触摸灵敏度，调小更细腻
`smoothWheel`	true	滚轮是否平滑，设 false 回到即时滚动
`syncTouch`	false	让触屏设备的滚动也平滑

建议先只调lerp和duration，手感定下来之后再碰倍率。

✨ 让 GSAP 动画跟着滚动走

GSAP ScrollTrigger 卡帧的典型原因，是滚动和动画跑在两个时钟上。把 Lenis 挂到 GSAP 的 ticker 上，两者就对齐到同一帧：

const lenis = new Lenis() lenis.on('scroll', ScrollTrigger.update) gsap.ticker.add((time) => lenis.raf(time * 1000)) gsap.ticker.lagSmoothing(0)

time * 1000是因为 GSAP 用秒、Lenis 用毫秒；lagSmoothing(0)关掉 GSAP 的滞后补偿，否则快速滚动后动画会明显"追帧"。这套 Lenis GSAP 集成搭好后，scrub 视差、文字逐行浮现这类滚动驱动动画就都顺了。

Lenis React 使用：框架里更省心

React 适配包给了<ReactLenis>组件和useLenis钩子，不用手动传实例、也不用自己写 raf 循环：

import { ReactLenis, useLenis } from 'lenis/react' function App() { const lenis = useLenis((l) => console.log(l.progress)) return ( <> <ReactLenis root /> {/* 页面内容 */} </> ) }

useLenis的回调在每次滚动时执行，适合在里面读l.progress驱动样式。Vue 侧有对等的<VueLenis>+useLenis，Nuxt 直接在 modules 里加'lenis/nuxt'。SSR 框架下记住一点：实例只在客户端初始化，别让它碰服务端环境。

3D 场景：把滚动映射给相机

Three.js 项目里不需要研究源码：在scroll事件回调中取e.scroll（当前位置）或e.progress（0–1 进度），映射到相机 z 轴或场景旋转上，就得到跟着手指走的 3D 滚动。配合上面 GSAP ticker 的同步方式，3D 场景和 DOM 动画跑在同一个循环里；生态里还有 r3f-scroll-rig 这类现成插件可以直接用。

⚠️ 避坑清单

症状：元素抖动、sticky 错位→ 原因：没引 lenis.css → 解法：import 'lenis/dist/lenis.css'
症状：移动端触摸不响应→ 原因：平滑默认只管滚轮，或嵌套容器冲突 → 解法：开syncTouch: true，或给容器加data-lenis-prevent
症状：和第三方滚动库打架→ 原因：两套滚动机制同时跑 → 解法：第三方操作前后lenis.stop()/lenis.start()
症状：滚动时掉帧→ 原因：scroll 回调里做了重计算 → 解法：DOM 读写移出回调
症状：加载后滚动位置不对→ 原因：DOM 没就绪就初始化 → 解法：等加载完再初始化，确认autoRaf: true