Instalar o Node.js

Esta página explica como instalar o Node.js no Windows, macOS e Linux. O Desktop e a versão da Microsoft Store não incluem mais o Node.js: eles usam diretamente o node e o npm do seu sistema, dos quais o OpenSpec e a maioria dos Agent CLIs também dependem.

Requisito de versão

É necessário o Node.js 24 ou superior, e o requisito mínimo também é 24. Em geral, basta instalar a versão LTS mais recente. O npm é instalado junto com o Node.js e não precisa ser instalado separadamente.

Quais métodos de instalação precisam dele

• Microsoft Store / Desktop: necessário, e o node e o npm precisam ser encontrados no PATH do sistema.

Instalar o Node.js

Windows

Método 1: instalador oficial (recomendado)

1. Acesse o site oficial do Node.js
2. Baixe o instalador do Windows (arquivo .msi) da versão LTS (suporte de longo prazo) e confirme que o número da versão não é inferior a 24
3. Clique duas vezes para executar o instalador
4. Siga as instruções do assistente de instalação para concluir:
   • Aceite o contrato de licença
   • Escolha o caminho de instalação (o padrão é suficiente)
   • Mantenha “Add to PATH” marcado
   • Clique em “Install” para iniciar a instalação
5. Quando a instalação terminar, clique em “Finish”

Método 2: usando o winget

Abra o PowerShell ou o Prompt de Comando e execute o comando abaixo:

winget install OpenJS.NodeJS.LTS

Depois da instalação, reabra o terminal para que as alterações tenham efeito.

macOS

Método 1: instalador oficial (recomendado)

1. Acesse o site oficial do Node.js
2. Baixe o instalador do macOS (arquivo .pkg) da versão LTS (suporte de longo prazo) e confirme que o número da versão não é inferior a 24
3. Clique duas vezes para executar o instalador
4. Siga as instruções do assistente de instalação para concluir:
   • Clique em “Continuar”
   • Aceite o contrato de licença
   • Escolha o disco de instalação
   • Clique em “Instalar” e digite a senha de administrador
5. Quando a instalação terminar, clique em “Fechar”

Método 2: usando o Homebrew

Se você já tem o Homebrew instalado, pode instalar o Node.js pelo terminal:

brew install node

O Homebrew adiciona automaticamente o Node.js ao seu PATH. Se o comando não estiver disponível, reinicie o terminal ou execute:

eval "$(/opt/homebrew/bin/brew shellenv)"

Ubuntu/Debian

Usando o repositório NodeSource (recomendado)

O Node.js dos repositórios que acompanham a distribuição costuma ser anterior ao 24; use o repositório 24.x fornecido pelo NodeSource:

# Use o curl para baixar o script de instalação
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

Não instale diretamente a versão que acompanha a distribuição com sudo apt-get install nodejs npm; é muito provável que ela não atenda ao requisito mínimo de 24.

Se você não quiser adicionar uma fonte de software de terceiros, também pode usar o nvm ou o fnm, descritos adiante.

CentOS/RHEL

Usando o repositório NodeSource (recomendado)

# Use o curl para baixar o script de instalação
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
sudo yum install -y nodejs

O Node.js dos repositórios que acompanham a distribuição costuma ser anterior ao 24, por isso não é recomendável usá-lo diretamente. Você também pode optar pelo nvm ou pelo fnm, descritos adiante.

Fedora

Usando o gerenciador de pacotes dnf

sudo dnf install -y nodejs npm

Depois da instalação, execute node --version para confirmar que a versão não é inferior a 24. Se a versão do repositório for mais antiga, use o repositório 24.x do NodeSource ou o nvm ou o fnm, descritos adiante.

Usar um gerenciador de versões

Se você precisa alternar entre várias versões do Node.js, pode usar um gerenciador de versões.

Atenção, usuários do Desktop

No macOS e no Linux, ferramentas como nvm e fnm costumam definir o PATH apenas nos arquivos de configuração do shell (como .bashrc e .zshrc). O Desktop aberto pelo Dock, pelo menu de aplicativos ou por um ícone da área de trabalho não lê essas configurações e pode não encontrar o node. Se você usa um gerenciador de versões, abra o Desktop a partir de um terminal em que o node já funcione ou use o método de instalação em nível de sistema descrito acima.

nvm (Node Version Manager)

Instalar o nvm

Linux/macOS

Copie diretamente o comando de instalação mais recente indicado no README do repositório oficial do nvm; não use endereços de scripts de instalação de versões antigas.

Depois da instalação, recarregue a configuração do shell:

source ~/.bashrc
# Ou, para usuários do Zsh
source ~/.zshrc

Windows

No Windows, recomendamos usar o nvm-windows:

1. Baixe o nvm-setup.exe mais recente em nvm-windows releases
2. Execute o instalador
3. Reabra o Prompt de Comando ou o PowerShell

Usar o nvm

Depois de instalar o nvm, você pode usá-lo para instalar e gerenciar versões do Node.js:

# Instalar o Node.js 24
nvm install 24

# Mudar para o Node.js 24
nvm use 24

# Definir a versão padrão
nvm alias default 24

# Listar as versões instaladas
nvm list

O comando alias do nvm-windows não está disponível; basta usar nvm install 24 e nvm use 24.

fnm (Fast Node Manager)

O fnm é um gerenciador de versões do Node.js mais rápido e simples, construído com Rust.

Instalar o fnm

Linux/macOS

# Instalar usando o curl
curl -fsSL https://fnm.vercel.app/install | bash

# Depois da instalação, recarregue a configuração do shell
source ~/.bashrc
# Ou, para usuários do Zsh
source ~/.zshrc

Windows

Use o scoop ou o winget:

# Usando o scoop
scoop install fnm

# Ou usando o winget
winget install Schniz.fnm

Usar o fnm

# Instalar o Node.js 24
fnm install 24

# Mudar para o Node.js 24
fnm use 24

# Definir a versão padrão
fnm default 24

# Listar as versões instaladas
fnm list

Aceleração para usuários da China continental

Se você está na China continental, o download do Node.js e dos pacotes do npm pode ser lento; nesse caso, é possível usar espelhos locais.

Espelho do npm

# Usar o espelho temporariamente na instalação
npm install --registry=https://registry.npmmirror.com

# Definir o espelho de forma permanente
npm config set registry https://registry.npmmirror.com

# Verificar se o espelho foi configurado com sucesso
npm config get registry

Espelho dos instaladores do Node.js

Os instaladores do Node.js também têm um endereço de download espelhado: https://npmmirror.com/mirrors/node/. Depois de acessá-lo, escolha uma versão não inferior a 24 para baixar.

Espelho do Homebrew

Se você usa o Homebrew na China continental, pode configurar o espelho da USTC para os bottles:

export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

Verificar a instalação

Depois da instalação, verifique em um terminal recém-aberto se o Node.js e o npm estão disponíveis:

# Verifique a versão do Node.js; é necessário v24.0.0 ou superior
node --version

# Verifique a versão do npm
npm --version

Uma saída bem-sucedida deve ser semelhante a:

$ node --version
v24.3.0

$ npm --version
11.4.2

Se node --version mostrar uma versão inferior a 24, reinstale conforme os métodos acima ou use um gerenciador de versões para mudar para 24 ou superior.

Configurar o diretório global do npm

O Desktop instala pacotes gerenciados, como os Agent CLIs, no diretório global do npm da sua máquina. Se o diretório global estiver em um local que exige privilégios de administrador, podem ocorrer erros de permissão EACCES durante a instalação. Recomendamos mudar o diretório global para a pasta do usuário, em vez de alterar as permissões de um diretório do sistema:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

Depois, adicione ~/.npm-global/bin (no Windows, o próprio diretório global do npm) ao PATH do sistema e reinicie o terminal e o Desktop. Ao usar nvm ou fnm, o diretório global já fica dentro da pasta do usuário, e esta etapa não é necessária.

Solução de problemas

Problemas no Windows

Comando indisponível

Se os comandos node ou npm não estiverem disponíveis depois da instalação:

1. Reinicie o Prompt de Comando ou o PowerShell
2. Se ainda não estiverem disponíveis, adicione manualmente o Node.js ao PATH:
   • Pesquise “Variáveis de ambiente” e abra “Editar as variáveis de ambiente do sistema”
   • Clique em “Variáveis de Ambiente”
   • Em “Variáveis do sistema”, localize “Path” e clique em “Editar”
   • Adicione o caminho de instalação do Node.js (padrão: C:\Program Files\nodejs\)
   • Clique em “OK” para salvar as alterações
3. Feche o Desktop por completo e abra-o novamente

Política de execução do PowerShell

Se você encontrar erros de política de execução ao usar scripts do nvm ou do npm:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problemas no macOS

Erros de permissão

Se você encontrar erros de permissão ao instalar pacotes globais do npm, consulte Configurar o diretório global do npm acima ou use o nvm / fnm.

Comando indisponível

Se os comandos não estiverem disponíveis depois da instalação, reinicie o terminal e confirme que o diretório onde o Node.js está (geralmente /usr/local/bin ou /opt/homebrew/bin) está no PATH.

Problemas no Linux

Erros de permissão

Se você encontrar erros de permissão ao instalar pacotes globais do npm, consulte Configurar o diretório global do npm acima ou use o nvm / fnm, em vez de instalar pacotes globais com sudo.

Versão muito antiga

Se a versão do Node.js instalada pelo gerenciador de pacotes do sistema for inferior a 24:

1. Use o repositório 24.x do NodeSource (veja acima)
2. Ou use um gerenciador de versões (nvm / fnm)

Verificar o ambiente

Se a verificação falhar, confira os itens abaixo:

Windows

# Verificar se o Node.js está no PATH
where node

# Verificar o caminho de instalação
Get-Command node

macOS

# Verificar se o Node.js está no PATH
which node

# Verificar o caminho de instalação
ls -l $(which node)

Linux

# Verificar se o Node.js está no PATH
which node

# Verificar o caminho de instalação
ls -l $(which node)

Próximos passos

Depois de instalar o Node.js, você pode seguir com os passos abaixo:

Voltar ao guia de instalaçãoConclua pré-requisitos como o Git e escolha o método de instalação mais adequado ao seu caso.

Introdução ao OpenSpecVá ao site de documentação independente do OpenSpec para conhecer as formas de instalação, os conceitos centrais e o fluxo de trabalho orientado por especificações.

Instalar o AI Agent CLIVeja os pontos de entrada oficiais de instalação dos Agent CLIs compatíveis atualmente e diferencie a instalação com um clique da instalação / autenticação manual.

Precisa de mais ajuda?

Se você encontrar problemas que não são tratados aqui:

1. Acesse a documentação oficial do Node.js
2. Consulte Como o Desktop usa o seu ambiente Node
3. Consulte a Visão geral do produto HagiCode para conhecer o produto atual e as explicações sobre as ferramentas relacionadas