Instalando Node.js e npm

Como baixar e instalar Node.js e npm no macOS e Windows - incluindo o que LTS significa, os diferentes métodos de instalação e qual escolher.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Verifica se o Node.js já está instalado
node --version
 
# Verifica a versão do npm
npm --version
 
# Instala o Node.js via nvm (recomendado para macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
nvm use --lts
 
# Verifica a instalação
node --version   # ex: v22.15.0
npm --version    # ex: 10.9.2

Quando usar isso: Antes de iniciar qualquer projeto React, Next.js ou Node.js, você precisa ter Node.js e npm instalados. Este é sempre o passo zero.

Links de Download

Sempre baixe de nodejs.org ou de um gerenciador de versões confiável. A página de download oferece duas opções: LTS e Current.

Mergulho Profundo

O que é LTS?

LTS significa Long Term Support (Suporte de Longo Prazo). O Node.js segue um cronograma de lançamento onde as versões principais de número par (18, 20, 22, 24...) entram em status LTS e recebem correções de bugs e patches de segurança por 30 meses. As versões de número ímpar (19, 21, 23...) são versões "Current" de curta duração que recebem suporte por apenas 6 meses.

Regra geral: Sempre use a versão LTS mais recente, a menos que você tenha um motivo específico para usar a Current. Todas as implantações de produção, pipelines de CI e tutoriais neste cookbook assumem LTS.

O que é npm?

npm (Node Package Manager) é o gerenciador de pacotes padrão que vem incluído em todas as instalações do Node.js. Ele faz três coisas:

1. Instala pacotes do registro npm (o maior registro de software do mundo - mais de 2 milhões de pacotes).
2. Gerencia dependências via package.json e package-lock.json.
3. Executa scripts definidos em package.json (por exemplo, npm run dev, npm test).

Quando você instala o Node.js, você ganha o npm gratuitamente. Você não precisa instalá-lo separadamente.

# Instala um pacote
npm install react
 
# Instala dependências de desenvolvimento
npm install --save-dev typescript
 
# Executa um script do package.json
npm run dev
 
# Instala todas as dependências do package.json
npm install

Instalando no macOS

Opção 1: nvm (recomendado)

nvm (Node Version Manager) permite que você instale e alterne entre várias versões do Node.js. Esta é a melhor opção para desenvolvedores que trabalham em vários projetos que podem exigir versões diferentes do Node.

# Instala o nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
 
# Reinicie o terminal e, em seguida:
nvm install --lts        # Instala a versão LTS mais recente
nvm use --lts            # Ativa-a
nvm alias default lts/*  # Torna-a o padrão para novos shells
 
# Alterne entre versões
nvm install 20           # Instala o Node 20
nvm use 20               # Alterna para o Node 20
nvm ls                   # Lista as versões instaladas

O nvm instala o Node.js em ~/.nvm/, portanto, não requer sudo e evita problemas de permissão com pacotes globais.

Opção 2: Homebrew

brew install node        # Instala a versão current mais recente
brew install node@22     # Instala uma versão LTS específica

Simples, mas gerencia apenas uma versão por vez. Se você precisar alternar entre versões, use o nvm em vez disso.

Opção 3: fnm (alternativa rápida)

brew install fnm
fnm install --lts
fnm use --lts
 
# Adicione ao perfil do shell (~/.zshrc ou ~/.bashrc)
eval "$(fnm env --use-on-cd)"

O fnm é escrito em Rust e é notavelmente mais rápido que o nvm para alternar versões. Ele também suporta arquivos .node-version e .nvmrc.

Opção 4: Volta

curl https://get.volta.sh | bash
volta install node@lts

O Volta fixa as versões das ferramentas por projeto em package.json, para que cada colaborador use a mesma versão automaticamente.

Opção 5: Instalador oficial

Baixe o arquivo .pkg de https://nodejs.org/en/download e execute-o. Instala o Node.js e o npm em todo o sistema em /usr/local/. Funciona, mas é mais difícil gerenciar várias versões e pode exigir sudo para instalações globais.

Instalando no Windows

Opção 1: nvm-windows (recomendado)

nvm-windows é um projeto separado do nvm (não é um port), mas fornece o mesmo fluxo de trabalho de alternância de versão.

1. Baixe o instalador de https://github.com/coreybutler/nvm-windows/releases
2. Execute o instalador .exe
3. Abra um novo terminal (Prompt de Comando ou PowerShell):

nvm install lts          # Instala a versão LTS mais recente
nvm use lts              # Ativa-a
nvm list                 # Lista as versões instaladas

Opção 2: winget (Gerenciador de Pacotes do Windows)

winget install OpenJS.NodeJS.LTS

Integrado ao Windows 11 e disponível para Windows 10. Instala uma única versão em todo o sistema.

Opção 3: Chocolatey

choco install nodejs-lts

Requer que o Chocolatey seja instalado primeiro. Semelhante ao Homebrew no macOS - gerencia uma versão por vez.

Opção 4: fnm

winget install Schniz.fnm
fnm install --lts
fnm use --lts

Funciona no Windows, macOS e Linux. Troca rápida de versão.

Opção 5: Volta

# Baixe o instalador de https://volta.sh
volta install node@lts

Opção 6: Instalador oficial

Baixe o arquivo .msi de https://nodejs.org/en/download e execute-o. Instala o Node.js, npm e opcionalmente adiciona ao PATH. A opção mais simples, mas a mais difícil para gerenciar várias versões.

Qual Método Escolher?

Verificando sua Instalação

Após a instalação, abra um novo terminal e execute:

node --version
# v22.15.0 (ou versão LTS similar)
 
npm --version
# 10.9.2 (ou similar)
 
# Teste rápido - execute uma linha de comando
node -e "console.log('Node.js está funcionando!')"

Mantendo o Node.js Atualizado

# Com nvm
nvm install --lts --reinstall-packages-from=current
nvm use --lts
 
# Com Homebrew
brew upgrade node
 
# Com fnm
fnm install --lts
fnm use --lts
 
# Com Volta
volta install node@lts

Ao atualizar o Node.js, os pacotes npm instalados globalmente podem precisar ser reinstalados. A flag --reinstall-packages-from=current no nvm cuida disso automaticamente.

Armadilhas

1. Esquecer de abrir um novo terminal. Após instalar o nvm ou qualquer gerenciador de versões, seu shell atual não pega as novas entradas do PATH. Sempre abra uma nova janela de terminal.
2. Erros de permissão com instalações globais. Se você instalou o Node.js pelo instalador oficial e npm install -g falha com EACCES, mude para o nvm - ele instala no seu diretório home e evita completamente problemas de permissão. Nunca use sudo npm install -g.
3. Múltiplos gerenciadores de versão competindo. Se você tem o nvm e o Node.js do Homebrew instalados, seu PATH determina qual deles vence. Escolha um método e desinstale o outro.
4. .nvmrc não troca automaticamente. O nvm não troca automaticamente as versões do Node quando você dá cd para um diretório com .nvmrc por padrão. Adicione autoload à sua configuração de shell ou use fnm/Volta, que fazem isso nativamente.
5. Confusão entre npm e npx. npm instala e gerencia pacotes. npx executa um binário de pacote - seja do seu node_modules/.bin local ou baixando-o temporariamente. Por exemplo, npx create-next-app executa o gerador create-next-app sem instalá-lo globalmente.
6. Problemas de PATH no Windows. No Windows, se node não for reconhecido após a instalação, verifique se o diretório de instalação foi adicionado ao PATH do seu sistema. Reinicie o terminal ou saia e entre novamente.
7. Diferença de versão do Node.js no terminal do VS Code. O VS Code pode usar um perfil de shell diferente do seu terminal regular. Se node --version mostrar uma versão diferente no VS Code, reinicie o VS Code após instalar ou alternar versões.

FAQs

Relacionados

• pnpm vs npm
• Executando Scripts Node.js em JavaScript
• Executando Scripts TypeScript
• Módulos ESM vs CommonJS