# Lenis

> 分类：`libs/animation/` · 档位：**采纳** · 更新时间：2026-11-17

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 1.x |
| License | MIT |
| 维护方 | Darkroom Engineering（原 Studio Freight） |
| 仓库 / 文档 | https://github.com/darkroomengineering/lenis · https://lenis.darkroom.engineering |
| 最近 release | 见官方 releases |

## 2. 一句话定位

把浏览器原生滚动替换为"每帧驱动的平滑滚动"，提供统一的滚动位置与 `scrollTo` 控制。
它**不提供**滚动触发、pin、时间轴等动画能力，需与动画库配合。

## 3. 体积

| 引入方式 | min | gzip |
|---|---|---|
| 全量 | 约 10 KB | 约 3 KB（估算，待实测） |

## 4. 核心 API

```js
import Lenis from 'lenis';

const lenis = new Lenis({
  duration: 1.2,
  smoothWheel: true,
  easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
});

// 接入动画引擎的帧循环
lenis.on('scroll', ScrollTrigger.update);
gsap.ticker.add((time) => lenis.raf(time * 1000));
gsap.ticker.lagSmoothing(0);

lenis.scrollTo('#section', { duration: 1.4 });
lenis.resize();
lenis.destroy();
```

## 5. 适用 / 不适用

- **适用**：需要"顺滑滚动"观感的品牌页、产品页；与 GSAP/ScrollTrigger 或 Anime.js 的滚动观察器配合。
- **不适用**：需要保留系统原生滚动行为（如部分后台、长文档阅读）的场景；已有框架自带平滑滚动的项目。

## 6. 硬缺口与已知坑

- 接管整页滚动，可能影响宿主的 sticky 头部、锚点与嵌套滚动容器；嵌套区域需 `data-lenis-prevent`。
- 与原生 `scroll-behavior: smooth` 冲突，必须置为 `auto`，并保留官方推荐样式（`html.lenis` 等）。
- 原生 `#hash` 跳转会与 Lenis 脱节，需拦截并改用 `lenis.scrollTo`。
- 没有 pin 能力，钉住效果要靠 CSS `position: sticky` 或动画库实现。
- 动态插入/重渲染的页面需要 `destroy()` 后重建，避免多实例。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（`<script>`） | 可用 | 使用包内构建产物 |
| ESM / 打包器 | 可用 | 推荐方式 |
| SSR | 需守卫 | 仅在浏览器端初始化 |
| 客户端重渲染（SPA / 局部刷新） | 需处理生命周期 | 重渲染前 `destroy()` |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 5 | 持续迭代，社区使用广 |
| 版本与破坏性变更 | 4 | 1.x 稳定，迁移有文档 |
| 采用度 | 5 | 大量品牌站点使用 |
| 体积与按需 | 5 | 约 3 KB gzip |
| 生态兼容 | 4 | 纯 JS，可与主流动画库配合 |
| License | 5 | MIT |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| 原生滚动 + CSS `scroll-behavior` | 零依赖、无接管风险 | 手感不可调，无法统一 scrollTo | 简单页面 |
| GSAP ScrollSmoother | 与 ScrollTrigger 深度集成 | 体积大、需 Club 授权（现已免费但仍重） | 已是 GSAP 全家桶 |
| Luge | 轻量平滑滚动 | 生态与维护弱于 Lenis | 仅需平滑滚动 |
