Instalar o Node.js e o npm no Debian

O Node.js é o ambiente de execução por trás de inúmeras aplicações web, APIs e bots de Discord. Num servidor próprio, a instalação fica pronta em poucos minutos. Neste guia, instala o Node.js e o npm em Debian 13, Debian 12 e Debian 11. Em Ubuntu, os comandos são exatamente os mesmos.

Decisiva é a escolha da versão certa. Os guias outrora muito divulgados para o Node.js 10 e o Node.js 12 estão ultrapassados: ambas as versões já não recebem atualizações de segurança há anos e não deveriam continuar a correr em servidor nenhum.

Que versão do Node.js deve instalar?

O Node.js lança uma nova versão principal duas vezes por ano. Só os números de versão pares passam a uma linha LTS (Long Term Support) e recebem manutenção durante cerca de três anos. As versões ímpares são linhas de desenvolvimento de vida curta e não se destinam a sistemas em produção.

• Node.js 24 LTS ("Krypton"): a recomendação atual para projetos novos e servidores em produção.
• Node.js 22 LTS: continua muito difundido, faz sentido quando uma aplicação exige expressamente esta versão.
• Node.js 10 e 12: sem suporte desde 2021 e 2022, respetivamente. Não voltar a usar.

Em caso de dúvida, verifique as indicações da sua aplicação. Muitos projetos registam a versão exigida no campo "engines" do respetivo ficheiro package.json.

Requisitos

• Acesso root ao seu vServer ou servidor root através de SSH.
• Um Debian atualizado. Comece por colocar o sistema no estado mais recente:

apt update && apt upgrade -y

Para obter a fonte de pacotes, precisa ainda de algumas ferramentas padrão:

apt install -y ca-certificates curl gnupg

Variante 1: Node.js a partir das fontes de pacotes do Debian

O caminho mais simples passa pelas fontes de pacotes já incluídas:

apt install nodejs npm -y

A vantagem: as atualizações chegam automaticamente com as restantes atualizações do sistema. A desvantagem: os pacotes do Debian costumam ficar uma a duas versões principais atrás da linha LTS atual. Para saber que versão está disponível no seu sistema antes de instalar, use:

apt-cache policy nodejs

Em julho de 2026, as fontes de pacotes fornecem: Debian 13 "Trixie" Node.js 20.19, Debian 12 "Bookworm" Node.js 18.20, Ubuntu 24.04 Node.js 18.19, Ubuntu 22.04 Node.js 12.22. Se isso lhe chegar, o trabalho termina aqui. Se precisar de uma linha LTS atual, siga a variante 2.

Variante 2: instalar o Node.js 24 LTS através da NodeSource

A NodeSource disponibiliza fontes de pacotes oficiais para Debian e Ubuntu. Assim, obtém exatamente a versão principal pretendida e continua a receber atualizações através do apt.

Guardar a chave de assinatura

O antigo caminho através do apt-key deixou de existir. Desde o Debian 11, as chaves de assinatura pertencem a um diretório próprio em /etc/apt/keyrings/:

mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

Registar a fonte de pacotes e instalar

Registe em seguida a fonte de pacotes. Através da variável, define a versão principal pretendida, aqui a 24:

NODE_MAJOR=24
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

Para o Node.js 22, defina antes NODE_MAJOR=22. Segue-se depois a instalação propriamente dita:

apt update
apt install nodejs -y

O npm já vem incluído no pacote da NodeSource. Não instale aqui adicionalmente o pacote "npm" do Debian, caso contrário surge um conflito de pacotes.

O caminho rápido através do script de instalação

A NodeSource oferece ainda um script que junta os dois passos anteriores:

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install nodejs -y

É cómodo, mas está a executar com privilégios de root um script transferido da internet. Em servidores de produção, o caminho através da chave e da fonte de pacotes é a opção mais limpa.

Verificar a instalação

Para terminar, consulte as duas versões:

node --version
npm --version

Se o node devolver uma saída que começa por v22. e o npm indicar um número de versão, a instalação foi bem-sucedida.

Caso queira usar o yarn ou o pnpm: ambos podem ser ativados através do Corepack, que já vem no Node.js, pelo que não é necessária uma instalação separada:

corepack enable

Manter várias versões do Node.js em paralelo

Se tiver várias aplicações com requisitos diferentes no mesmo servidor, o Node Version Manager (nvm) ajuda. Instala o Node.js na pasta do utilizador, o que permite manter várias versões lado a lado e alternar entre elas em cada projeto.

Depois de instalar o nvm (siga para isso as instruções do projeto oficial), bastam estes comandos:

nvm install 24
nvm use 24
nvm alias default 24

Importante: o nvm pertence sempre a um único utilizador. Os serviços de sistema que correm com outro utilizador não encontram esta instalação do Node.js. Para serviços, a instalação por pacote é o caminho mais fiável.

Mudar para uma versão mais recente

Se mais tarde precisar de passar para uma nova linha LTS, basta alterar o número de versão na fonte de pacotes e atualizar:

NODE_MAJOR=24
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
apt update && apt install nodejs -y

Teste a sua aplicação depois de um salto de versão. Entre duas versões principais, as interfaces podem mudar e os módulos nativos mais antigos podem ter de ser recompilados.

Erros frequentes

• "E: Unable to locate package nodejs": depois de registar a fonte de pacotes, ficou esquecido o apt update.
• Conflito de pacotes entre nodejs e npm: instalou o pacote "npm" do Debian ao lado do pacote da NodeSource. Remova o npm com apt remove npm, porque a versão adequada vem com o próprio Node.js.
• "NO_PUBKEY" ou "signatures couldn't be verified": a chave de assinatura não está em /etc/apt/keyrings/ ou a linha da fonte de pacotes não contém a referência signed-by correspondente.
• Continua a ser apresentada uma versão antiga: restam no sistema vestígios de uma instalação anterior. Apague os ficheiros antigos em /etc/apt/sources.list.d/ que apontam para o nodesource e instale novamente a seguir.
• Um pacote npm falha durante a compilação: faltam as ferramentas de compilação para os módulos nativos. Instale-as com apt install -y build-essential python3.