Node.js 故障排除

本文档旨在帮助使用 ServBay 本地开发环境的开发者解决在使用 Node.js 软件包时可能遇到的一些常见问题。

Node.js/npm/pnpm/yarn 命令版本找不到或未找到

当您在 ServBay 中使用 Node.js、npm、pnpm 或 yarn 时，如果遇到类似以下错误提示，表明系统无法找到您尝试使用的特定版本 Node.js 可执行文件：

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.

这通常是由于您尝试使用的特定版本 Node.js 在 ServBay 中尚未安装，或者您希望使用通过 nvm 或 homebrew 等其他工具安装的 Node.js 版本，但由于环境配置问题导致 ServBay 无法正确找到它们。

提示

安装 ServBay 后，系统会配置 ServBay 的脚本别名 (Script Alias)，使其优先使用 ServBay 所安装的 Node.js 软件包。当 ServBay 中找不到指定版本时，会依次尝试回落到 nvm 安装的默认版本，然后是 homebrew 安装的版本。如果在这些位置都无法找到，就会报告上述错误。

原因分析：

1. 尝试使用的 Node.js 版本未在 ServBay 应用内安装。
2. 系统安装了 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 架构的二进制文件或编译配置。

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

原因分析：

某些 npm 包包含需要编译的 C++ 或其他原生代码。这些代码需要针对特定的 CPU 架构进行编译。较旧版本的这些包可能没有为 Arm64 架构（如 Apple Silicon）提供编译好的版本或支持。

解决方案：

1. 更换为现代的、支持 Arm64 的替代品（推荐）：

   最推荐的解决方案是替换为现代的、完全支持 Arm64 架构的替代品。例如，将功能受限且已不再积极维护的 node-sass 替换为功能更强大且维护更积极的 sass 包。大多数现代前端项目和工具链都已迁移到 sass。

   npm uninstall node-sass
   npm install --save-dev sass

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。

---