Node.js 18与Bigcommerce Stencil CLI中node-sass兼容问题求助

问题描述 #

当前使用Node.js 18.20.3版本，尝试用低于18的Node.js版本运行Stencil CLI时，收到Stencil不支持的错误提示；使用Node.js 18虽可正常启动，但本地运行时SCSS未被正常编译，出现以下报错：

This usually happens because your environment has changed since running `npm install`.
Run `npm rebuild node-sass` to download the binding for your current environment.
    at module.exports (/home/sagmetic/.nvm/versions/node/v18.20.3/lib/node_modules/@bigcommerce/stencil-cli/node_modules/node-sass/lib/binding.js:15:13)
    at Object.<anonymous> (/home/sagmetic/.nvm/versions/node/v18.20.3/lib/node_modules/@bigcommerce/stencil-cli/node_modules/node-sass/lib/index.js:13:35)
    at Module._compile (node:internal/modules/cjs/loader:1364:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1422:10)
    at Module.load (node:internal/modules/cjs/loader:1203:32)
    at Module._load (node:internal/modules/cjs/loader:1019:10)
    at Module.require (node:internal/modules/cjs/loader:1231:19)
    at require (node:internal/modules/helpers:177:18)
    at ScssCompiler.activateNodeSassEngine (/home/sagmetic/.nvm/versions/node/v18.20.3/lib/node_modules/@bigcommerce/stencil-cli/node_modules/@bigcommerce/stencil-styles/lib/ScssCompiler.js:21:23)
    at StencilStyles.activateEngine (/home/sagmetic/.nvm/versions/node/v18.20.3/lib/node_modules/@bigcommerce/stencil-cli/node_modules/@bigcommerce/stencil-styles/lib/styles.js:52:36)

已尝试操作 #

• 执行错误提示中的npm rebuild node-sass命令
• 确认环境及依赖配置正确

环境信息 #

• Node.js版本：18.20.3
• Stencil CLI

咨询问题 #

1. 如何解决SCSS未被正常编译的问题？
2. Node.js 18与node-sass是否存在特定兼容问题？
3. 需额外执行哪些步骤确保Stencil CLI与Node.js 18正常协作？

解决方案与解答 #

1. 解决SCSS编译问题 #

• 彻底清理现有依赖：删除项目根目录下的node_modules文件夹和package-lock.json（或yarn.lock）文件
• 全局卸载旧版Stencil CLI：npm uninstall -g @bigcommerce/stencil-cli
• 重新安装适配Node.js 18的最新版Stencil CLI：npm install -g @bigcommerce/stencil-cli@latest
• 回到项目目录，重新安装本地依赖：npm install
• 如果上述操作无效，直接替换node-sass为sass（dart-sass）：修改项目package.json，将node-sass依赖替换为sass，再执行npm install。dart-sass是官方推荐的替代方案，对高版本Node.js支持更稳定。

2. Node.js 18与node-sass的兼容问题 #

node-sass从v7.0.0版本开始才正式支持Node.js 18，但node-sass已于2022年停止维护，后续没有任何更新。而旧版Stencil CLI依赖的node-sass版本大概率低于v7.0.0，这就是你遇到编译报错的核心原因——低版本node-sass无法适配Node.js 18的运行环境。

3. 确保Stencil CLI与Node.js 18正常协作的额外步骤 #

• 锁定Node.js版本：用nvm管理Node.js环境，执行nvm use 18.20.3确保项目使用指定版本，避免全局环境冲突
• 清理npm缓存：执行npm cache clean --force，清除缓存中的旧依赖文件，避免安装时出现异常
• 检查Stencil配置：确认项目根目录的.stencil配置文件中，SCSS编译相关的配置项正确，比如指定了正确的编译器路径
• 避免全局安装冲突：如果项目有本地安装的Stencil CLI依赖，优先使用本地版本执行命令（npx stencil ...），而非全局版本

内容的提问来源于stack exchange，提问作者Portgas D. Ace