LocomotiveScroll导入失败：无法使用平滑滚动功能求助

云上老周

2026-8-18

解决LocomotiveScroll导入失败无法使用平滑滚动的问题

先确认依赖包是否正确安装
去项目根目录的package.json里找locomotive-scroll依赖项，要是没有就执行npm install locomotive-scroll或yarn add locomotive-scroll重新安装，安装完务必重启开发服务器。
检查导入语法是否匹配项目环境
要是你的项目用的是CommonJS环境（比如旧版Node.js、未配置ES模块的Webpack），别用ES模块的import语法，改成const LocomotiveScroll = require('locomotive-scroll');。
验证初始化代码是否正确
导入后得确保实例初始化步骤没出错，比如：
```
document.addEventListener('DOMContentLoaded', function() {
  const scroll = new LocomotiveScroll({
    el: document.querySelector('[data-scroll-container]'),
    smooth: true
  });
});
```
别忘了给滚动容器加data-scroll-container属性，需要监听滚动的元素加data-scroll属性，这是LocomotiveScroll生效的必要配置。
排查版本兼容问题
不同版本的LocomotiveScroll API有差异，比如v4之后的初始化参数和旧版不一样，先确认你用的版本对应的文档要求；要是有依赖冲突，试试删除node_modules和package-lock.json（或yarn.lock），然后重新安装所有依赖。
检查构建工具配置
用Webpack、Vite这类工具时，要确保它们支持ES模块导入。比如Vite默认支持，但Webpack可能需要在webpack.config.js里配置resolve.extensions包含.js，还要确认没给locomotive-scroll设错别名。
查看浏览器控制台错误提示
打开开发者工具的Console面板，看具体报错信息：如果是Cannot find module，就是包没装对；如果是window is not defined，大概率是在SSR环境里直接导入了，这种情况要先判断环境再导入：
```
let LocomotiveScroll;
if (typeof window !== 'undefined') {
  LocomotiveScroll = require('locomotive-scroll').default;
}
```