Como Instalar o NVM para Node.js no Ubuntu: Guia Técnico Completo

NVM (Node Version Manager) é um script de shell compatível com POSIX que instala e gere múltiplos ambientes de execução Node.js isolados numa única máquina, sem necessitar de privilégios de root ou modificar caminhos do sistema. Cada versão do Node.js reside no seu próprio diretório em `~/.nvm/versions/node/`, proporcionando isolamento completo e sem conflitos entre projetos.

Este guia percorre uma instalação NVM de nível de produção no Ubuntu (20.04, 22.04 e 24.04), abordando não apenas os comandos básicos, mas também casos especiais de ficheiros de perfil de shell, automação de fluxo de trabalho `.nvmrc`, migração de pacotes globais e problemas específicos de servidor que a maioria dos tutoriais omite.

Por Que Usar NVM em Vez do Gestor de Pacotes do Sistema

Instalar o Node.js via `apt` coloca um único binário de sistema em `/usr/bin/node`. Atualizá-lo afeta todas as aplicações no servidor simultaneamente. Numa máquina de desenvolvimento partilhada ou num VPS a executar múltiplos projetos Node.js, isto cria ambientes frágeis e difíceis de reproduzir.

O NVM resolve isto instalando cada versão do Node.js num diretório de espaço de utilizador e manipulando `PATH` ao nível do shell. O resultado é controlo de versão por utilizador e por projeto sem qualquer impacto no estado de pacotes do sistema operativo.

NVM vs. Outros Gestores de Versão do Node.js

O NVM continua a ser a opção mais amplamente documentada e suportada pelo ecossistema, tornando-o a escolha mais segura por defeito para equipas e ambientes de servidor onde a reprodutibilidade importa mais do que a velocidade de inicialização.

Pré-requisitos

• Ubuntu 20.04, 22.04 ou 24.04 (desktop ou servidor)
• Uma conta de utilizador não-root com privilégios `sudo`
• `curl` ou `wget` instalado (ambos estão presentes por defeito na maioria das imagens Ubuntu)
• Familiaridade básica com Bash ou Zsh

Para confirmar o seu shell e versão do Ubuntu antes de começar:

“`bash

echo $SHELL

lsb_release -a

“`

Passo 1: Atualizar o Índice de Pacotes do Sistema

Atualize as listas de pacotes APT para garantir que quaisquer dependências resolvidas durante a sessão estão atualizadas:

“`bash

sudo apt-get update && sudo apt-get upgrade -y

“`

Confirme também que `curl` está disponível:

“`bash

curl –version || sudo apt-get install -y curl

“`

Passo 2: Descarregar e Executar o Script de Instalação do NVM

O instalador oficial do NVM está alojado no GitHub. Clona o repositório NVM para `~/.nvm` e acrescenta o bloco de inicialização de shell necessário ao seu ficheiro de perfil.

Opção A — Usando curl (recomendado):

“`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

“`

Opção B — Usando wget:

“`bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

“`

Verifique sempre a tag de versão mais recente na página de lançamentos do NVM no GitHub antes de executar. Substitua `v0.40.1` pela tag estável atual se uma versão mais recente tiver sido publicada.

O que o instalador realmente faz:

1. Clona o repositório NVM para `~/.nvm`
2. Deteta o seu shell ativo (`bash`, `zsh`, `ksh` ou `fish`)
3. Acrescenta o seguinte bloco de inicialização ao ficheiro de perfil apropriado (`~/.bashrc`, `~/.zshrc`, `~/.profile` ou `~/.bash_profile`)

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

[ -s "$NVM_DIR/bash_completion" ] && . "$NVM_DIR/bash_completion"

“`

Nota de segurança: Redirecionar um script remoto diretamente para `bash` é um padrão comum, mas comporta riscos inerentes. Para servidores de produção ou ambientes de servidor dedicado, descarregue o script primeiro, inspecione-o e depois execute:

“`bash

curl -o install_nvm.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh

cat install_nvm.sh # review before running

bash install_nvm.sh

“`

Passo 3: Ativar o NVM na Sessão de Shell Atual

O instalador modifica o seu perfil, mas essas alterações só têm efeito em novas sessões de shell. Para ativar o NVM imediatamente sem abrir um novo terminal:

Para Bash:

“`bash

source ~/.bashrc

“`

Para Zsh:

“`bash

source ~/.zshrc

“`

Carregamento manual (funciona em qualquer shell):

“`bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

“`

Problema Comum: Ficheiro de Perfil Não Carregado em Shells Não Interativos

No Ubuntu, `~/.bashrc` é carregado apenas para shells interativos não-login. Se estiver a ligar via SSH (um shell de login), o Bash lê `~/.bash_profile` ou `~/.profile` em vez disso. Se o NVM não for encontrado após o login SSH, adicione o bloco de carregamento ao `~/.bash_profile`:

“`bash

echo 'source ~/.bashrc' >> ~/.bash_profile

source ~/.bash_profile

“`

Este é um dos problemas mais frequentemente encontrados ao configurar o NVM em servidores remotos.

Passo 4: Verificar a Instalação do NVM

“`bash

nvm –version

“`

Saída esperada (o número de versão pode variar):

“`

0.40.1

“`

Se o comando retornar `nvm: command not found`, o perfil de shell não foi carregado corretamente. Execute novamente o comando de carregamento do Passo 3 e verifique se o bloco de inicialização existe no seu ficheiro de perfil:

“`bash

grep -n 'NVM_DIR' ~/.bashrc

“`

Passo 5: Instalar o Node.js Usando o NVM

Instalar a Versão LTS Mais Recente (Recomendado para Produção)

“`bash

nvm install –lts

“`

O sinalizador `–lts` instala a versão de Suporte de Longo Prazo mais recente, que recebe patches de segurança durante 30 meses. Para cargas de trabalho de produção num VPS com cPanel ou qualquer ambiente de servidor, a versão LTS é fortemente preferida em relação à versão atual.

Instalar a Versão Mais Recente Absoluta

“`bash

nvm install node

“`

Instalar uma Versão Específica

“`bash

nvm install 20.14.0

“`

Listar Todas as Versões Remotas Disponíveis

“`bash

nvm ls-remote

“`

Para filtrar apenas versões LTS:

“`bash

nvm ls-remote –lts

“`

Passo 6: Verificar as Versões Ativas do Node.js e npm

“`bash

node -v

npm -v

“`

Confirme também o caminho do binário para garantir que não está a usar acidentalmente uma instalação Node.js de sistema:

“`bash

which node

Expected: /home/<username>/.nvm/versions/node/v20.14.0/bin/node

“`

Passo 7: Gerir Múltiplas Versões do Node.js

Listar Todas as Versões Instaladas Localmente

“`bash

nvm ls

“`

Exemplo de saída:

“`

-> v20.14.0

v18.20.3

v16.20.2

default -> lts/* (-> v20.14.0)

node -> stable (-> v20.14.0) (default)

lts/* -> lts/iron (-> v20.14.0)

“`

Alternar Entre Versões

“`bash

nvm use 18.20.3

“`

Esta alteração aplica-se apenas à sessão de terminal atual. Abrir um novo terminal reverte para o alias predefinido.

Verificar Qual a Versão Atualmente Ativa

“`bash

nvm current

“`

Passo 8: Definir uma Versão Padrão Persistente do Node.js

Para tornar uma versão específica a predefinida para todas as novas sessões de shell:

“`bash

nvm alias default 20.14.0

“`

Também pode criar um alias para uma linha de lançamento em vez de uma versão de patch específica, que rastreia automaticamente as atualizações dentro dessa linha:

“`bash

nvm alias default lts/*

“`

Passo 9: Automatizar a Troca de Versão com `.nvmrc`

Esta é uma das funcionalidades mais poderosas e subutilizadas do NVM. Coloque um ficheiro `.nvmrc` na raiz do seu projeto contendo a versão Node.js necessária:

“`bash

echo "20.14.0" > /path/to/your/project/.nvmrc

“`

Depois, quando fizer `cd` para esse diretório:

“`bash

nvm use

Found '/path/to/your/project/.nvmrc' with version <20.14.0>

Now using node v20.14.0

“`

Troca Automática de Versão ao Mudar de Diretório

Adicione o seguinte ao seu `~/.bashrc` (ou `~/.zshrc`) para acionar `nvm use` automaticamente sempre que entrar num diretório contendo um ficheiro `.nvmrc`:

Para Bash:

“`bash

cdnvm() {

command cd "$@" || return $?

nvm_path="$(nvm_find_up .nvmrc | command tr -d 'n')"

if [[ ! $nvm_path = *[^[:space:]]* ]]; then

declare default_version

default_version="$(nvm version default)"

if [[ $default_version == "N/A" ]]; then

nvm use default

elif [[ $(nvm current) != "$default_version" ]]; then

nvm use default

fi

elif [[ -r "$nvm_path/.nvmrc" && -r "$nvm_path" ]]; then

declare nvm_version

nvm_version=$(<"$nvm_path/.nvmrc")

declare locally_resolved_nvm_version

locally_resolved_nvm_version="$(nvm ls –no-colors "$nvm_version" | command tail -1 | command tr -d '->*' | command tr -d '[:space:]')"

if [[ "$locally_resolved_nvm_version" == "N/A" ]]; then

nvm install "$nvm_version"

elif [[ $(nvm current) != "$locally_resolved_nvm_version" ]]; then

nvm use "$nvm_version"

fi

fi

}

alias cd='cdnvm'

“`

Este padrão é especialmente valioso em pipelines CI/CD e ambientes de equipa onde múltiplos programadores trabalham em projetos com diferentes requisitos de runtime.

Passo 10: Gerir Pacotes npm Globais Entre Versões

Cada versão do Node.js instalada pelo NVM tem o seu próprio diretório `node_modules` isolado para pacotes instalados globalmente. Isto significa que ferramentas como `pm2`, `yarn` ou `typescript` instaladas globalmente sob `v18` não estão disponíveis sob `v20`.

Instalar um Pacote Global para a Versão Ativa

“`bash

npm install -g yarn

npm install -g pm2

npm install -g typescript

“`

Migrar Pacotes Globais ao Instalar uma Nova Versão

O NVM fornece um sinalizador integrado para copiar todos os pacotes globais de uma versão para uma nova instalação:

“`bash

nvm install 20.14.0 –reinstall-packages-from=18.20.3

“`

Isto é fundamental ao atualizar versões do Node.js num servidor que executa processos persistentes geridos pelo PM2 ou ferramentas semelhantes.

Listar Pacotes Instalados Globalmente para a Versão Atual

“`bash

npm list -g –depth=0

“`

Passo 11: Desinstalar uma Versão do Node.js

Antes de desinstalar, mude para uma versão diferente da que pretende remover:

“`bash

nvm use 20.14.0

nvm uninstall 16.20.2

“`

Não é possível desinstalar a versão atualmente ativa. Tentar fazê-lo retorna um erro.

Avançado: Usar o NVM em Ambientes Não Interativos (CI/CD, Cron, Systemd)

O NVM depende de ficheiros de inicialização de shell que não são carregados em shells não interativos. Isto causa erros `node: command not found` em tarefas cron, ficheiros de unidade systemd e alguns ambientes CI.

Solução 1: Usar o caminho completo do binário

“`bash

/home/username/.nvm/versions/node/v20.14.0/bin/node /path/to/app.js

“`

Solução 2: Carregar o NVM explicitamente em scripts

“`bash

#!/bin/bash

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

nvm use 20.14.0

node /path/to/app.js

“`

Solução 3: Criar um symlink para acesso em todo o sistema (usar com precaução)

“`bash

sudo ln -s /home/username/.nvm/versions/node/v20.14.0/bin/node /usr/local/bin/node

“`

Esta abordagem sacrifica o isolamento por utilizador, mas é por vezes necessária para serviços systemd a executar como um utilizador de serviço dedicado.

NVM em Alojamento Partilhado vs. VPS vs. Servidores Dedicados

Para equipas que executam aplicações Node.js juntamente com outros serviços, um VPS dá-lhe o controlo ao nível do shell que o NVM requer sem a sobrecarga de gerir hardware físico.

Lista de Verificação de Pontos-Chave Práticos

Use isto como referência de implementação e configuração:

• Verifique o tipo de shell (`echo $SHELL`) antes de instalar — Zsh e Bash requerem ficheiros de perfil diferentes
• Use sempre `–lts` para instalações Node.js de produção; reserve `node` (mais recente) para trabalho experimental
• Confirme `.nvmrc` no controlo de versão para que cada membro da equipa e executor CI use a versão de runtime idêntica
• Use `–reinstall-packages-from` ao atualizar versões do Node.js para evitar reinstalar manualmente ferramentas globais
• Carregue o NVM explicitamente em qualquer script não interativo (cron, systemd, pipelines CI) — nunca assuma que o perfil de shell foi carregado
• Audite os pacotes globais por versão com `npm list -g –depth=0` após mudar de versão para detetar dependências em falta precocemente
• Fixe versões exatas em `.nvmrc` (ex.: `20.14.0`) em vez de aliases (ex.: `lts`) para máxima reprodutibilidade em produção
• Verifique `which node` após mudar de versão para confirmar que não está a usar acidentalmente um binário instalado pelo sistema

Perguntas Frequentes

O NVM requer sudo ou acesso root para instalar o Node.js?

Não. O NVM instala tudo em `~/.nvm` no diretório home do utilizador atual. Não são necessários privilégios de root para instalar ou mudar versões do Node.js. Esta é uma das suas principais vantagens em relação aos gestores de pacotes ao nível do sistema.

Por que aparece `nvm: command not found` após a instalação?

O bloco de inicialização do NVM foi adicionado ao seu perfil de shell, mas o perfil não foi recarregado na sessão atual. Execute `source ~/.bashrc` (Bash) ou `source ~/.zshrc` (Zsh). Se o erro persistir após abrir um novo terminal, verifique se o bloco de inicialização foi realmente escrito no ficheiro correto usando `grep NVM_DIR ~/.bashrc`.

Podem múltiplos utilizadores no mesmo servidor ter versões diferentes do Node.js via NVM?

Sim. Como o NVM instala no diretório home de cada utilizador (`~/.nvm`), cada utilizador mantém um conjunto completamente independente de versões do Node.js e pacotes globais. Esta é a arquitetura correta para servidores multi-inquilino.

O que acontece aos pacotes npm instalados globalmente quando mudo de versão do Node.js com o NVM?

Cada versão do Node.js tem o seu próprio diretório de pacotes globais isolado. Os pacotes instalados globalmente sob uma versão não são visíveis para outra. Use `nvm install <new-version> –reinstall-packages-from=<old-version>` para os migrar automaticamente.

O NVM é adequado para executar aplicações Node.js em produção num servidor?

O NVM é bem adequado para gerir qual a versão do Node.js utilizada, mas para gestão de processos em produção deve combiná-lo com um gestor de processos como o PM2 ou usar ficheiros de unidade systemd. Certifique-se de que esses ambientes não interativos carregam explicitamente o NVM ou referenciam o caminho completo do binário, conforme descrito na secção CI/CD acima.