Node.js 故障排除
本文档旨在帮助使用 ServBay 本地开发环境的开发者解决在使用 Node.js 软件包时可能遇到的一些常见问题。
Node.js/npm/pnpm/yarn 命令版本找不到或未找到
当您在 ServBay 中使用 Node.js、npm、pnpm 或 yarn 时,如果遇到类似以下错误提示,表明系统无法找到您尝试使用的特定版本 Node.js 可执行文件:
bash
Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.
1
2
3
2
3
这通常是由于您尝试使用的特定版本 Node.js 在 ServBay 中尚未安装,或者您希望使用通过 nvm
或 homebrew
等其他工具安装的 Node.js 版本,但由于环境配置问题导致 ServBay 无法正确找到它们。
提示
安装 ServBay 后,系统会配置 ServBay 的脚本别名 (Script Alias),使其优先使用 ServBay 所安装的 Node.js 软件包。当 ServBay 中找不到指定版本时,会依次尝试回落到 nvm
安装的默认版本,然后是 homebrew
安装的版本。如果在这些位置都无法找到,就会报告上述错误。
原因分析:
- 尝试使用的 Node.js 版本未在 ServBay 应用内安装。
- 系统安装了
nvm
或homebrew
,并且您期望使用它们管理的 Node.js 版本,但由于 shell 环境配置(尤其是PATH
或NVM_BIN
环境变量)不正确,导致 ServBay 的回落机制无法找到这些外部安装的 Node.js。
解决方案:
如果您已安装 nvm
并使用其安装了 Node.js 版本,但仍然遇到此错误,一个常见原因是您的 shell 环境配置中缺少或配置不正确的 NVM_BIN
环境变量。nvm
在正确安装时会自动配置此变量,它指向 nvm
安装的 Node.js 可执行文件的位置,是 nvm
正常工作的关键。
您只需要检查并修复您的 shell 配置文件(如 ~/.zshrc
, ~/.bash_profile
等)中的 nvm
相关配置,确保 NVM_BIN
变量被正确设置并导出,然后重新加载配置文件(例如运行 source ~/.zshrc
或重启终端)。修复后,ServBay 的回落机制应该能够正确找到 nvm
管理的 Node.js 版本。
如果您没有使用 nvm
或 homebrew
,或者希望使用 ServBay 管理的 Node.js 版本,请确保您尝试使用的 Node.js 版本已在 ServBay 应用的“软件包”界面中安装。
使用 node-sass
等 npm 包时提示架构不支持
对于使用 Apple Silicon (M1/M2/M3/M4 等 Arm64 架构) 芯片的 macOS 用户,在使用一些较旧或依赖原生模块的 npm 包(例如 node-sass
)时,可能会遇到类似 Unsupported architecture (arm64)
的错误。这是因为这些旧版本的包可能只提供了针对 x86_64 架构的二进制文件或编译配置。
bash
ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1
1
2
3
4
5
2
3
4
5
原因分析:
某些 npm 包包含需要编译的 C++ 或其他原生代码。这些代码需要针对特定的 CPU 架构进行编译。较旧版本的这些包可能没有为 Arm64 架构(如 Apple Silicon)提供编译好的版本或支持。
解决方案:
更换为现代的、支持 Arm64 的替代品(推荐):
最推荐的解决方案是替换为现代的、完全支持 Arm64 架构的替代品。例如,将功能受限且已不再积极维护的
node-sass
替换为功能更强大且维护更积极的sass
包。大多数现代前端项目和工具链都已迁移到sass
。bashnpm uninstall node-sass npm install --save-dev sass
1
2在 ServBay 中安装 x86_64 架构的 Node.js 并通过 Rosetta 2 运行(不推荐):
ServBay 提供了安装
x86_64
架构 Node.js 软件包的选项。在 Apple Silicon Mac 上,这允许您通过 macOS 内置的 Rosetta 2 翻译层来运行 Node.js 及其依赖的x86_64
原生模块。您可以在 ServBay 应用的“软件包”界面中选择安装x86_64
版本的 Node.js。请注意: 这通常不建议作为长期解决方案,因为它依赖于 Rosetta 2 模拟,可能引入性能开销,并且与原生 Arm64 环境相比可能存在兼容性问题。优先考虑方案 1。