Solução de Problemas do Node.js

Este documento tem como objetivo ajudar desenvolvedores que utilizam o ambiente de desenvolvimento local ServBay a resolver alguns problemas comuns ao usar pacotes Node.js.

Versão do comando Node.js/npm/pnpm/yarn não encontrada

Ao usar Node.js, npm, pnpm ou yarn no ServBay, se você encontrar mensagens de erro como a seguinte, isso indica que o sistema não conseguiu localizar a versão específica do executável Node.js que você tentou utilizar:

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.

Isso geralmente ocorre porque a versão específica do Node.js que você tentou usar ainda não foi instalada no ServBay, ou porque você deseja usar versões do Node.js instaladas por outros gerenciadores, como nvm ou homebrew, mas devido a configuração do ambiente, o ServBay não consegue localizá-las corretamente.

Dica

Após instalar o ServBay, o sistema configura aliases de script do ServBay para priorizar os pacotes Node.js fornecidos por ele. Quando não encontra a versão especificada dentro do ServBay, tenta automaticamente recorrer à versão padrão instalada pelo nvm e, em seguida, à versão instalada via homebrew. Se não encontrar em nenhum desses locais, será reportado o erro acima.

Análise de Causas:

1. A versão do Node.js que você deseja utilizar não está instalada no aplicativo ServBay.
2. O sistema possui o nvm ou homebrew instalados e você espera usar as versões do Node.js gerenciadas por eles, mas devido à configuração incorreta do ambiente do shell (especialmente das variáveis de ambiente PATH ou NVM_BIN), o mecanismo de fallback do ServBay não consegue localizar as instalações externas do Node.js.

Soluções:

Se você já instalou o nvm e utilizou para instalar uma versão do Node.js, mas continua recebendo este erro, uma causa comum é a ausência ou configuração incorreta da variável de ambiente NVM_BIN no seu ambiente de shell. O nvm configura automaticamente essa variável ao ser instalado corretamente; ela aponta para onde os executáveis do Node.js gerenciados pelo nvm estão localizados, sendo essencial para o funcionamento esperado do nvm.

Basta revisar e corrigir as configurações relacionadas ao nvm em seu arquivo de configuração de shell (como ~/.zshrc, ~/.bash_profile etc.), garantindo que a variável NVM_BIN esteja corretamente definida e exportada. Em seguida, recarregue o arquivo de configuração (por exemplo, executando source ~/.zshrc ou reiniciando seu terminal). Depois disso, o mecanismo de fallback do ServBay deverá conseguir localizar corretamente as versões do Node.js gerenciadas pelo nvm.

Se você não utiliza nvm ou homebrew, ou deseja usar versões do Node.js gerenciadas diretamente pelo ServBay, verifique se a versão pretendida do Node.js está instalada na interface “Pacotes” do aplicativo ServBay.

Erro de arquitetura não suportada ao utilizar pacotes npm como node-sass

Para usuários de macOS com chips Apple Silicon (M1/M2/M3/M4, arquitetura Arm64), ao utilizar pacotes npm mais antigos ou dependentes de módulos nativos (como node-sass), podem surgir erros como Unsupported architecture (arm64). Isso ocorre porque algumas versões antigas desses pacotes oferecem apenas binários ou opções de compilação para a arquitetura 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

Análise de Causas:

Certos pacotes npm incluem código-fonte em C++ ou outras linguagens nativas que precisam ser compilados para uma arquitetura de CPU específica. Versões antigas desses pacotes podem não oferecer binários prontos ou compatibilidade para arquitetura Arm64 (como nos Macs com Apple Silicon).

Soluções:

1. Troque para alternativas modernas e compatíveis com Arm64 (Recomendado):

   A recomendação principal é substituir por alternativas modernas que ofereçam suporte total à arquitetura Arm64. Por exemplo, substitua o já descontinuado e pouco mantido node-sass pelo pacote sass, que é mais robusto e ativamente mantido. A maioria dos projetos e ferramentas frontend atuais já migraram para o sass.

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

2. Instale a versão x86_64 do Node.js no ServBay e execute via Rosetta 2 (Não recomendado):

   O ServBay permite instalar versões do Node.js compiladas para a arquitetura x86_64. Nos Macs com Apple Silicon, isso possibilita rodar o Node.js e módulos nativos x86_64 via a camada de tradução Rosetta 2 do macOS. Você pode selecionar a instalação da versão x86_64 do Node.js na interface “Pacotes” do ServBay.

   

   Atenção: Esta alternativa geralmente não é recomendada como solução de longo prazo, pois depende da emulação via Rosetta 2, podendo causar impacto de performance e esbarrar em limitações de compatibilidade em relação ao ambiente Arm64 nativo. Prefira sempre a opção 1 quando possível.

---