如果你在跑 ruoyi-ui 的时候撞见了This dependency was not found: readline in ./node_modules/sass/sass.dart.js先别急着删node_modules我试过删了没用。这是一个典型的“前端依赖生态版本错位”问题不是你的代码写错了也不是项目模板坏了。它通常出现在npm install之后启动开发服务器的阶段表面看是 webpack 找不到一个叫readline的模块但根子在于 sass 相关包的版本和你用的构建工具链不匹配。我最早遇到这个错误是在一个后台管理项目上接手后第一跑就翻车。网上搜到的答复五花八门有人说装readline包有人说降 Node 版本还有人说直接用 node-sass。每个看起来都能跑但直接照着做很容易踩到新的坑。这篇文章我会把报错原理拆清楚再给你几条能落地的方案最后附上我自己的调试记录和团队协作时的处理经验。适合刚接触 RuoYi 的初学者也同样适合在维护旧项目的朋友。1. 先看报错本身这不是个新问题1.1 报错长什么样用官方仓库或者模板拉下来的 ruoyi-ui直接执行npm run dev终端大概率会输出这样一大段$ npm run dev ERROR in ./node_modules/sass/sass.dart.js Module not found: Error: Cant resolve readline in /your-project/node_modules/sass ... This dependency was not found: * readline in ./node_modules/sass/sass.dart.js第一次看到这个报错的人都会慌因为报错关键字很多有模块名、有路径、有 webpack 的提示。但我们要冷静拆一下这不是语法错误也不是编译错误这是“依赖解析失败”。也就是说webpack 在打包时顺着sass.dart.js这个文件里的引用关系去找一个叫readline的模块结果在所有能解析的范围内都找不到它于是构建中断。很多帖子会让你配 fallback、装 polyfill但在动手之前先搞清楚这个readline到底从哪来比盲目复制命令重要得多。1.2 readline 是什么readline是 Node.js 的内置模块主要用来从可读流里逐行读取数据。比如你在命令行工具里需要读取用户的输入就会用到它。这个模块在 Node 环境里天然存在但在浏览器环境里没有对应的东西。问题就出在这里webpack 打包的时候默认是把自己当成浏览器环境来处理的。它走到sass.dart.js里看到require(readline)就尝试去解析这个模块。浏览器环境里没有readlinenode_modules 里一般也不会装一个叫readline的包于是 webpack 直接给你报了个“找不到”。至于为什么要去解析 sass 内部的 JS 文件是因为sass这个 npm 包本身是 Dart Sass 的纯 JS 实现核心代码都打包在sass.dart.js里面。这个文件是由 Dart 编译过来的代码量很大引用关系也很复杂里面保留了对 Node.js 内置模块的直接引用。这不能全怪 ruoyi-ui要怪就怪 npm install 默认给你装了太新的 sass。2. 为什么 ruoyi-ui 会踩中这个坑2.1 脚手架和依赖版本的历史包袱ruoyi-ui 这类后台管理前端项目大多诞生于 webpack 4 时期脚手架默认用 vue-cli 4.x。如果你按官方文档装好依赖直接启动大概率没问题。但很多人不会一直守着旧版本git pull 下来之后会习惯性升级依赖或者直接从一个老项目里拷贝 dependencies这时候sass可能会被解析成最新的版本。更有意思的是npm 在install的时候如果项目里没有 package-lock.json它会按 SemVer 规则拉取符合^的最新版本。比如sass: ^1.32.0它不会停在 1.32而是装当前最新稳定版。等你在本机一跑就撞上了新版本 sass 的 readline 引用。2.2 Webpack 5 默认不再处理 Node.js 内置模块这是最核心的机制变化。webpack 4 提供了node配置项默认会为很多 Node 内置模块生成 polyfill 或置空处理。webpack 5 出于体积和安全考虑把这个自动行为删了改成了resolve.fallback手动处理。也就是说如果你用的是 vue-cli 5 / webpack 5readline没有被自动提供自然就找不到了。即便你还在用 webpack 4如果 vue-cli 内部配置默认没有给readline留 polyfill同样会翻车。环境readline 可用性结果Node.js支持正常运行浏览器不支持运行时报错webpack 4 默认 node 配置部分内置模块有 polyfill可能通过webpack 5 无 manual fallback无 polyfill构建失败2.3 sass 版本的“漂移”npm install 对版本锁定不严格是另一个帮凶。不同版本的 sass 内部实现不同。我本地实测sass 1.32.x 系列构建正常到 1.49.x 及以上时sass.dart.js里能看到对readline的直接引用。这里给一个版本对照参考sass 1.32.13无该问题sass 1.32.8无该问题sass 1.55.0有该问题sass 1.69.5有该问题所以与其装完各种补丁不如直接把 sass 锁定到一个已知安全的版本。3. 现场复现与排查流程3.1 一套可复现的命令序列想稳定复现需要先把环境摆到“不推荐”的状态一个干净的目录Node 18没有 lock 文件。然后git clone 你的项目地址 cd ruoyi-ui npm install npm run dev这个命令序列几乎是万能复现器。关键是npm install没有锁文件会把 packages 拉到最新兼容版本其中就包括 sass。3.2 三步定位根因第一步看node_modules/sass/package.json里的 versionnode -p require(./node_modules/sass/package.json).version如果版本号是 1.49 以上基本就锁定了。第二步看 vue-cli 版本npx vue --version如果是 5.x那就是 webpack 5不存在内置 polyfill。如果是 4.x则要检查vue.config.js里是否自定义了 webpack 配置。第三步看 sass-loader 版本node -p require(./node_modules/sass-loader/package.json).versionsass-loader 的版本决定它怎么调用 sass新版通常配新版 sass旧版配旧版混装也会出现奇怪问题。3.3 几个容易误导的“伪根因”删node_modules、清 npm cache、重新 clone 项目这些我都试过。第一次犯傻删完重装还是报错因为装回来的还是那个 sass。把package.json里的 sass 升级到最新也一样。真正的解释只有一个依赖图里出现了当前构建工具无法解析的内置模块。4. 四种可落地的解决方案4.1 方案一安装 polyfill 插件时间最快用一个插件统一兜底npm install -D node-polyfill-webpack-pluginvue.config.js 里const NodePolyfillPlugin require(node-polyfill-webpack-plugin) module.exports { configureWebpack: { plugins: [new NodePolyfillPlugin()] } }这个插件会把 Node 内置模块映射成对应的 npm 包实现。对于 readline它也会给一个“能用的替身”。好处是改动小、见效快坏处是打包体积会变大而且 readline 这种模块的浏览器端 polyfill 不保证完整。我实测过编译能过但如果业务代码真的调用了 readline API页面里依然会报readline is not defined。所以这个方案适合只求项目先跑起来的情况。4.2 方案二将 sass 锁定到旧版本最省事这是我在几个项目里用下来最干净的办法npm uninstall sass npm install -D sass1.32.13 sass-loader10.1.1如果项目已经装了 sass-loader 10只改 sass 就行。锁定后sass.dart.js里不会再出现 readline 引用webpack 能顺利通过。有人担心锁旧版会不会丢失语法支持。后台管理系统的样式方案一般就是 scss 变量、嵌套、mixin这些在 1.32.x 上完全够用。新版本 Sass 的模块系统use/forward在旧版也支持只是部分新函数缺失。绝大多数业务场景感知不到差别。4.3 方案三给 Webpack 单独配置 fallback进阶如果你不想换依赖版本可以告诉 webpack这个模块你别管了。const { defineConfig } require(vue/cli-service) module.exports defineConfig({ configureWebpack: { resolve: { fallback: { readline: false } } } })fallback: false的意思是用空对象替代 readline任何代码真的调用require(readline)时会得到 undefined。好处是零额外依赖坏处是如果某些代码在运行时真调用了会炸出新的错误。因为 sass.dart.js 的 readline 引用只在特定环境下执行多数情况下不会触发所以这条路也能跑。但如果团队没人能说清楚为什么我建议别用这个方案容易埋雷。4.4 方案四换一套构建链路长期维护如果你本来就是新项目或者有条件折腾可以考虑把 Vue CLI 换成 Vite。Vite 使用 esbuild 预编译 sass不经过 webpack 的依赖图解析通常不会触发 readline 这个错误。至少我在同样保持 sass 新版的情况下Vite 构建没有问题。但这属于“动手术”方案迁移 vue.config.js 里的插件、代理、环境变量都要重配。项目已经稳定运行的话不建议为了这个报错做迁移新项目可以一开始就选 Vite。5. 实操记录我在配置中的每一步5.1 第一轮先看清楚了再动手我先在项目里跑了一遍复现命令报错后查看了三样版本。当时我手上是个 Node 18 环境npm 9项目的 vue-cli 版本是 5.0.8sass 被装成了 1.69.5。这个组合基本就是问题标准配置。我没有急着去装插件而是先看sass.dart.js里到底引用了什么模块grep -o require([^]*) node_modules/sass/sass.dart.js | grep -w readline能看到类似require(readline)的调用。虽然它不一定在执行路径上但 webpack 静态分析不会管这些只看到有引用就会去 resolve。5.2 第二轮先用 polyfill 插件试一下我先加了 node-polyfill-webpack-plugin编译确实通过了。但启动页面后控制台很快出现readline is not defined说明有些代码真的跑到了这个分支。虽然不影响主要业务但说明 polyfill 并没有百分百兜住。如果把项目让别人接手这会成为新的困惑点。5.3 第三轮锁定 sass 旧版本问题彻底消失我卸载了新 sass换成npm uninstall sass npm install -D sass1.32.13顺便把sass-loader也确认在 10.xnpm install -D sass-loader10.1.1再次npm run dev编译通过开发服务器秒起。我又把样式文件里的嵌套、变量、mixin 都检查了一遍没有异常。5.4 一个更干净的收尾问题解决后我还在 package.json 里加了注释JSON 不支持注释所以我写在 README明确写了建议组合Node 16、webpack 4/5 均可、sass 1.32.13、sass-loader 10。如果 package-lock.json 存在直接推送 lock 也能帮团队锁定版本。但很多仓库把 lock 忽略了所以最好约定一个固定版本。6. 常见问题与独家避坑建议6.1 问题速查表现场可能原因最推荐动作报错指向 readline in sass.dart.jssassdart-sass版本过新降级 sass 到 1.32.13编译通过但页面 readline is not defined用了 fallback:false 或 polyfill 不完整避免在运行期使用 readline优先降级改了 sass 版本后 sass-loader 报错sass-loader 与 sass 版本不匹配sass-loader 降到 10.x团队其他人本机不报错本机 Node 或锁文件不一致统一 lock 文件并提交不想动依赖版本环境是 webpack 5使用 node-polyfill-webpack-plugin6.2 为什么有时安装 polyfill 反而引入新错误polyfill 类插件通常会给所有 Node 内置模块做聚合填充比如http、https、zlib、readline。这些模块在浏览器端本来就没有完整实现插件只是给了一个替身或者干脆是空壳。当你遇到一个新错误第一反应可能是“插件在乱塞东西”实际上它就是在把不可用模块强行改成“能用”但运行时的问题依然存在。因此我建议能通过锁定版本解决的问题就不要用 polyfill。6.3 团队多人开发如何统一环境除了提交 lock 文件还可以在 package.json 里加 npm overridesnpm 8 以上或 yarn resolutions 强制指定 sass 版本{ overrides: { sass: 1.32.13 } }或{ resolutions: { sass: 1.32.13 } }这两种方式能确保不管谁安装、在什么时间安装sass 都是同一个版本。不过要说明overrides 只对间接依赖和符合版本的直接依赖生效直接在 devDependencies 里写死版本号才是最容易做到的一致性方案。6.4 我的使用心得排查 “This dependency was not found” 这一类 webpack 报错时切忌一上来就照着网上的命令乱试。先看版本、看 lock、看 webpack 配置比任何技巧都重要。这个 readline 报错本质上是“依赖生态不同步”不是代码 bug搞清楚机制后花两分钟就能解决。我个人最后保留了 sass 1.32.13 的固定版本方案后续半年没再遇到同样问题也没有任何组件样式编译异常。如果你已经中招优先尝试降级 sass如果业务必须用新版本再考虑 polyfill 插件。希望这篇记录能帮你在 ruoyi-ui 的启动路上少绕几个弯。