Instalando Node.js

Este guia cobre a instalação do Node.js no Windows, macOS e Linux. Node.js é uma dependência chave para ferramentas locais HagiCode, incluindo OpenSpec, ferramentas de frontend e vários CLIs de desenvolvedor.

Requisitos de versão

HagiCode recomenda Node.js 24+ (Node.js mínimo suportado >= 18.0). Na maioria dos casos, instale a versão LTS mais recente e verifique se sua versão atende aos requisitos.

Instalando Node.js

Windows

Método um: instalador oficial (recomendado)

1. Visite o Site oficial do Node.js.
2. Baixe a versão LTS (Long Term Support) do instalador do Windows (.msi arquivo)
3. Clique duas vezes para executar o instalador
4. Siga as instruções do assistente de instalação para concluir a instalação:
   • Aceite o contrato de licença
   • Escolha o caminho de instalação (o padrão é bom)
   • Certifique-se de que a opção “Instalar automaticamente as ferramentas necessárias” esteja marcada
   • Clique em “Instalar” para iniciar a instalação
5. Após a conclusão da instalação, clique em “Concluir”

Método dois: usando winget

Abra o PowerShell ou prompt de comando e execute:

winget install OpenJS.NodeJS.LTS

Após a instalação, reabra o terminal para que as alterações tenham efeito.

macOS

Método um: instalador oficial (recomendado)

1. Visite o Site oficial do Node.js.
2. Baixe o instalador do macOS da versão LTS (Long Term Support) (.pkg arquivo)
3. Clique duas vezes para executar o instalador
4. Siga as instruções do assistente de instalação para concluir a instalação:
   • Clique em “Continuar”
   • Aceite o contrato de licença
   • Escolha o disco de instalação
   • Clique em “Instalar” e digite a senha do administrador
5. Após a conclusão da instalação, clique em “Fechar”

Método dois: usando Homebrew

Se você tiver Cerveja caseira instalado, você pode instalar o Node.js via terminal:

brew install node

O Homebrew adicionará 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)

Esta é a melhor maneira de obter a versão mais recente do Node.js:

# Use curl to download the installation script
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Usando o Gerenciador de Pacotes apt

Se não precisar da versão mais recente, você pode usar o repositório padrão do Ubuntu:

sudo apt-get update
sudo apt-get install -y nodejs npm

A versão do Node.js no repositório padrão pode ser mais antiga. Após a instalação, verifique a versão para garantir que ela atenda aos requisitos do Node.js >= 18.0 (Node.js 24+ é recomendado).

CentOS/RHEL

Usando o repositório NodeSource (recomendado)

# Use curl to download the installation script
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

Usando o Gerenciador de Pacotes yum

sudo yum install -y nodejs npm

Fedora

Usando o Gerenciador de Pacotes dnf

sudo dnf install -y nodejs npm

O repositório de software do Fedora geralmente contém versões mais recentes do Node.js e pode ser instalado diretamente via dnf.

Usando ferramentas de gerenciamento de versão

Se precisar alternar entre várias versões do Node.js, você pode usar ferramentas de gerenciamento de versão.

nvm (gerenciador de versão do nó)

Installing nvm

Linux/macOS

# Install using curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Or install using wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Após a instalação, recarregue a configuração do shell:

source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Janelas

No Windows, recomendamos usar janelas nvm:

1. Baixe o mais recente nvm-setup.exe de lançamentos nvm-windows
2. Execute o instalador
3. Reabra o prompt de comando ou PowerShell

Using nvm

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

# Install the latest LTS version (recommended)
nvm install --lts

# Install Node.js 24 (recommended version)
nvm install 24

# Install a specific Node.js version
nvm install 18.20.0

# List installed versions
nvm list

# Switch to a specified Node.js version
nvm use 24

# Set default version
nvm alias default 24

# Windows nvm-windows syntax is slightly different
nvm install 24
nvm use 24

fnm (gerenciador de nó rápido)

fnm é uma ferramenta de gerenciamento de versão Node.js mais rápida e simples construída com Rust.

Installing fnm

Linux/macOS

# Install using curl
curl -fsSL https://fnm.vercel.app/install | bash

# After installation, reload shell configuration
source ~/.bashrc
# Or for Zsh users
source ~/.zshrc

Janelas

Usar colher ou asa:

# Use scoop
scoop install fnm

# Or use winget
winget install Schniz.fnm

Using fnm

# Install the latest LTS version (recommended)
fnm install --lts

# Install Node.js 24 (recommended version)
fnm install 24

# Install a specific Node.js version
fnm install 18.20.0

# List installed versions
fnm list

# Switch to a specified Node.js version
fnm use 24

# Set default version
fnm default 24

Aceleração para usuários da China Continental

Se você estiver na China continental, o download dos pacotes Node.js e npm pode ser lento. Aqui estão algumas soluções de aceleração.

Usando fontes de espelho doméstico

npm Taobao Mirror (recomendado)

# Temporarily use Taobao mirror
npm install --registry=https://registry.npmmirror.com

# Permanently set Taobao mirror
npm config set registry https://registry.npmmirror.com

# Verify mirror is set successfully
npm config get registry

Usando nrm para gerenciar fontes de espelho

nrm (gerenciador de registro npm) ajuda você a alternar rapidamente as fontes de espelho npm:

# Install nrm
npm install -g nrm

# List available mirror sources
nrm ls

# Switch to Taobao mirror
nrm use taobao

# Test mirror source speed
nrm test

Acelerando downloads do instalador Node.js

Taobao Node.js Mirror

Taobao fornece downloads espelhados para instaladores Node.js:

• Endereço de download: https://npmmirror.com/mirrors/node/

Visite o endereço acima e selecione a versão que deseja baixar.

FastGit Acceleration

Se o download do nvm ou de outras ferramentas do GitHub for lento, você pode usar o espelho FastGit:

# Use FastGit to accelerate nvm installation
curl -o- https://fastgit.org/nvm-sh/nvm/raw/master/install.sh | bash

O serviço FastGit pode mudar, consulte as informações oficiais.

Espelhos caseiros domésticos

Se você usa o Homebrew na China continental, você pode configurar espelhos domésticos para aceleração:

# Install Homebrew using domestic mirror
/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

# Or use USTC mirror
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles

Gerenciadores de pacotes específicos da China continental

cnpm

cnpm é um cliente npm fornecido pela equipe Taobao que usa o espelho Taobao por padrão:

# Install cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com

# Use cnpm to install packages
cnpm install <package-name>

cnpm é principalmente compatível com comandos npm e pode ser usado como um substituto direto.

Verificando o efeito de aceleração do espelho

Depois de configurar os espelhos, verifique:

# Test download speed
time npm install express --registry=https://registry.npmmirror.com

# Compare with official source speed
time npm install express --registry=https://registry.npmjs.org

Verificando a instalação

Após a instalação, verifique se o Node.js e o npm estão instalados corretamente:

# Check Node.js version
node --version

# Check npm version
npm --version

Certifique-se de que a versão do Node.js seja >= 18.0 (Node.js 24+ é recomendado). Se a versão for muito baixa, reinstale usando os métodos acima ou use ferramentas de gerenciamento de versão para instalar a versão correta.

Exemplo de saída de verificação

O resultado da verificação bem-sucedida deve ser semelhante a:

$ node --version
v24.3.0

$ npm --version
10.2.3

Solução de problemas

Problemas do Windows

Command Not Available

Se node ou npm comandos não estão disponíveis após a instalação:

1. Reinicie o prompt de comando ou PowerShell
2. Se ainda não estiver disponível, adicione manualmente o Node.js ao PATH:
   • Procure por “Variáveis de ambiente” e abra “Editar variáveis de ambiente do sistema”
   • Clique em “Variáveis de Ambiente”
   • Encontre “Caminho” em “Variáveis do sistema” 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

PowerShell Execution Policy

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

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problemas do macOS

Permission Errors

Se você encontrar erros de permissão ao instalar pacotes npm globais:

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Command Not Available

Se os comandos não estiverem disponíveis após a instalação, reinicie o terminal ou adicione manualmente ao PATH (geralmente em /usr/local/bin).

Problemas do Linux

Permission Errors

Se você encontrar erros de permissão ao instalar pacotes npm globais, é recomendado usar ferramentas de gerenciamento de versão Node.js (como nvm ou fnm) em vez de gerenciadores de pacotes do sistema.

Version Too Old

Se a versão do Node.js instalada por meio do gerenciador de pacotes do sistema for muito antiga:

1. Use o repositório NodeSource (recomendado, veja acima)
2. Ou use ferramentas de gerenciamento de versão (nvm/fnm)

Verificando o ambiente

Se a verificação falhar, verifique o seguinte:

Windows

# Check if Node.js is in PATH
where node

# Check installation path
Get-Command node

macOS

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

Linux

# Check if Node.js is in PATH
which node

# Check installation path
ls -l $(which node)

# Check version details
node -v

Próximas etapas

Após a conclusão da instalação do Node.js, você pode continuar com as seguintes etapas:

Install OpenSpec Install the OpenSpec specification-driven development tool to manage proposals, specs, and changes.

Install AI Agent CLI Use one registry for the official install entries for Claude Code, Codex, Gemini, GitHub Copilot, CodeBuddy, OpenCode, Kimi, QoderCLI, and Kiro.

Return to Installation Guide Return to the main installation guide to continue configuring other dependencies.

Precisa de mais ajuda?

Se você encontrar problemas não abordados aqui:

1. Visite o Documentação oficial do Node.js.
2. Revise o Visão geral do produto HagiCode para o contexto atual do produto e das ferramentas
3. Visite o Site HagiCode para obter os pontos de entrada de suporte mais recentes