企业官网建设流程全解析

如果你在跑 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: Can't 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')，就尝试去解析这个模块。浏览器环境里没有readline，node_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 5，readline没有被自动提供，自然就找不到了。即便你还在用 webpack 4，如果 vue-cli 内部配置默认没有给readline留 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里的 version：

node -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').version"

sass-loader 的版本决定它怎么调用 sass，新版通常配新版 sass，旧版配旧版，混装也会出现奇怪问题。

3.3 几个容易误导的“伪根因”

删node_modules、清 npm cache、重新 clone 项目，这些我都试过。第一次犯傻删完重装，还是报错，因为装回来的还是那个 sass。把package.json里的 sass 升级到最新，也一样。真正的解释只有一个：依赖图里出现了当前构建工具无法解析的内置模块。

4. 四种可落地的解决方案

4.1 方案一：安装 polyfill 插件（时间最快）

用一个插件统一兜底：

npm install -D node-polyfill-webpack-plugin

vue.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 sass@1.32.13 sass-loader@10.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.8，sass 被装成了 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 sass@1.32.13

顺便把sass-loader也确认在 10.x：

npm install -D sass-loader@10.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 问题速查表

6.2 为什么有时安装 polyfill 反而引入新错误

polyfill 类插件通常会给所有 Node 内置模块做聚合填充，比如http、https、zlib、readline。这些模块在浏览器端本来就没有完整实现，插件只是给了一个替身，或者干脆是空壳。当你遇到一个新错误，第一反应可能是“插件在乱塞东西”，实际上它就是在把不可用模块强行改成“能用”，但运行时的问题依然存在。因此我建议：能通过锁定版本解决的问题，就不要用 polyfill。

6.3 团队多人开发如何统一环境

除了提交 lock 文件，还可以在 package.json 里加 npm overrides（npm 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 的启动路上少绕几个弯。