Locomotive Scroll 失效通常是因为缺少必需的 data-scroll-container 和 data-scroll-section 属性，且未正确初始化实例；本文详解配置要点、HTML 结构修正与 JS 初始化方法，并提供可直接运行的完整示例。
locomotive scroll 失效通常是因为缺少必需的 `data-scroll-container` 和 `data-scroll-section` 属性，且未正确初始化实例；本文详解配置要点、html 结构修正与 js 初始化方法，并提供可直接运行的完整示例。
要使 Locomotive Scroll 正常工作，HTML 结构、CSS 布局与 JavaScript 初始化三者必须协同配合。你当前代码中虽引入了库文件和 CSS，但存在三个关键缺失：
- 缺少容器标识：data-scroll-container 必须添加在最外层滚动容器上（如 <div id="main">）；
- 缺少分节标识：每个垂直“页面”（如 #page-1、#page-2）需包裹在 data-scroll-section 元素内；
- 未初始化实例：必须通过 new LocomotiveScroll({ el: ... }) 显式启动滚动引擎。
✅ 正确结构应如下（精简核心部分）：
<!-- ✅ 关键：添加 data-scroll-container -->
<div id="main" data-scroll-container>
<!-- ✅ 关键：每个 section 包裹在 data-scroll-section 中 -->
<div data-scroll-section>
<div data-scroll data-scroll-speed="-5" id="page-1">
<!-- 页面1内容 -->
<video src="..." autoplay loop muted></video>
<h2>Experience Real Estate Agility</h2>
</div>
</div>
<div data-scroll-section>
<!-- ✅ #page-2 现在是独立 section，支持平滑滚动进入 -->
<div id="page-2" data-scroll>
<p>PAGE 2 — now scrollable and positioned correctly</p>
</div>
</div>
</div>? CSS 注意事项：
- #main 不应设置 height: 100vh 或 overflow: hidden，否则会截断后续内容；保持 overflow: visible（你已正确设置）；
- 所有 data-scroll-section 内的子元素（如 #page-1, #page-2）必须为块级、有明确高度（如 height: 100vh），否则 Locomotive Scroll 无法计算滚动锚点；
- 避免对 body 或 html 设置 overflow: hidden —— 这会直接禁用原生滚动，导致插件失去监听基础。
? JavaScript 初始化（务必放在所有 DOM 加载后）：
<script>
// ✅ 确保 DOM 已就绪（推荐使用 DOMContentLoaded）
document.addEventListener('DOMContentLoaded', () => {
const scroll = new LocomotiveScroll({
el: document.querySelector('[data-scroll-container]'),
smooth: true,
multiplier: 1,
class: 'is-revealed',
firefoxMultiplier: 50,
smartphone: {
smooth: true,
breakpoint: 767
}
});
// ✅ 可选：与 GSAP ScrollTrigger 同步（如需高级动画联动）
// gsap.registerPlugin(ScrollTrigger);
// ScrollTrigger.scrollerProxy('[data-scroll-container]', {
// scrollTop(value) {
// return arguments.length ? scroll.scrollTo(value, 0, 0) : scroll.scroll.instance.scroll.y;
// },
// getBoundingClientRect() {
// return { top: 0, left: 0, width: window.innerWidth, height: window.innerHeight };
// }
// });
});
</script>⚠️ 常见陷阱提醒：
- ❌ 不要在 <body> 上直接加 data-scroll-container（LoCo 不支持 body 作为容器）；
- ❌ 不要遗漏 data-scroll 属性在需要动效的子元素上（如 #page-1 的 data-scroll-speed="-5" 依赖该属性触发）；
- ❌ 初始化脚本必须在 locomotive-scroll.js 加载之后执行，且不能早于 DOM 渲染 —— 使用 DOMContentLoaded 是最稳妥方式；
- ✅ 若启用 smooth: true，请确保已引入 locomotive-scroll.css（你已正确引入）。
最后验证：打开浏览器开发者工具 → Elements 面板 → 检查 #main 是否有 data-scroll-container，其子 div[data-scroll-section] 是否存在，且控制台无 LocomotiveScroll is not defined 报错。满足以上条件后，滚动将立即生效，#page-2 将平滑上浮覆盖 #page-1 视口区域，实现预期视差与分页效果。
