Instalação e Gerenciamento de Versões

Q: Qual versão do Node a produção deve rodar?

Node.js 24.18.0 (Active LTS) para novas implantações. Node 22.23.1 (Maintenance LTS) é aceitável durante a migração, mas planeje atualizar antes que a manutenção termine.

Q: Qual a diferença entre fnm e nvm?

Ambos trocam versões do Node via hooks de shell. fnm é mais rápido (escrito em Rust) e suporta o mesmo formato de arquivo .nvmrc.

Q: Devo commitar o .nvmrc?

Sim. Commite .nvmrc ou .node-version para que cada desenvolvedor e job de CI resolva a mesma versão.

Q: Como o Volta fixa as versões?

Adicione uma seção volta ao package.json: Volta troca automaticamente quando você entra no diretório do projeto.

Q: O que faz o engineStrict?

Quando engine-strict=true em .npmrc, npm se recusa a instalar se o Node/npm em execução não satisfizer engines.

Q: Posso usar Corepack para pnpm ou Yarn?

Sim. corepack enable ativa a versão do gerenciador de pacotes declarada no campo packageManager:

Q: E os desenvolvedores Windows?

fnm, nvm-windows e Volta suportam Windows. Documente uma ferramenta canônica no README da equipe.

Q: Versões de número ímpar como Node 25 devem ser usadas?

Não para produção. Lançamentos ímpares são "Current" e de curta duração. Use Active LTS (números pares) para serviços.

Q: Como verifico o que está instalado globalmente?

Prefira devDependencies locais do projeto em vez de globais para reprodutibilidade.

Q: O Alpine Linux precisa de imagens Node especiais?

Alpine usa musl libc - alguns add-ons nativos precisam de etapas de compilação extras. bookworm-slim (Debian) é mais seguro para módulos nativos.

Versões consistentes do Node entre laptops, CI e produção evitam falhas do tipo "funciona na minha máquina" - fixe o Active LTS e o aplique no momento da instalação.

Receita

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

// package.json
{
  "engines": {
    "node": ">=24.18.0 <25",
    "npm": ">=10.0.0"
  },
  "engineStrict": true
}

# .nvmrc
24.18.0

Quando usar isso:

Onboarding de um novo desenvolvedor em um serviço Node existente
Atualização do Node 22 Maintenance LTS para o Node 24 Active LTS
Pipelines de CI que silenciosamente selecionam o runtime incorreto
Monorepos onde múltiplos serviços compartilham uma política de versão do Node

Exemplo de Trabalho

# Instalar fnm (macOS/Linux) - gerenciador de versões rápido e cross-shell
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 24.18.0
fnm use 24.18.0
node --version  # v24.18.0

// Trecho do package.json
{
  "name": "billing-api",
  "type": "module",
  "engines": { "node": ">=24.18.0 <25" },
  "scripts": {
    "preinstall": "node scripts/check-node-version.mjs"
  }
}

// scripts/check-node-version.mjs
const required = 24;
const major = Number(process.versions.node.split('.')[0]);
if (major !== required) {
  console.error(`Node ${required}.x é necessário, mas obteve ${process.version}`);
  process.exit(1);
}

O que isso demonstra:

Arquivos .nvmrc / .node-version integram-se com fnm, nvm e asdf
engines documenta o intervalo suportado para humanos e ferramentas
Um script preinstall falha rapidamente antes que npm install baixe pacotes
Fixar <25 exclui lançamentos Atuais (de número ímpar) inadequados para produção

Mergulho Profundo

Como Funciona

Gerenciadores de versão instalam múltiplos binários do Node lado a lado e trocam o ativo via hooks de shell.
engines é consultivo, a menos que engine-strict=true em .npmrc ou você adicione scripts de aplicação.
Docker/Kubernetes devem usar imagens oficiais node:24.18.0-bookworm-slim - não node:latest.
Volta fixa versões por projeto no campo volta do package.json e troca automaticamente ao usar cd.

Comparação de Gerenciadores de Versão

Ferramenta	Velocidade	Modelo de fixação	Melhor para
fnm	Rápido (Rust)	`.nvmrc`, hook de shell	Desenvolvimento diário em macOS/Linux
nvm	Moderada	`.nvmrc`, amplamente conhecido	Documentação e tutoriais legados
Volta	Rápido	Bloco `volta` do `package.json`	Equipes que desejam `use` manual zero
asdf	Baseado em plugin	`.tool-versions`	Repositórios políglotos (Node + Ruby + Go)

Notas de TypeScript

// Lê a versão do runtime na inicialização e a expõe em /health
export function runtimeInfo(): { node: string; platform: string } {
  return {
    node: process.version,
    platform: `${process.platform}-${process.arch}`,
  };
}

Armadilhas

Usar node:latest no Docker - cada build pode obter uma versão principal diferente. Correção: fixe node:24.18.0-bookworm-slim com um digest.
Ignorar datas de fim do Maintenance LTS - Node 22 entra em fim de vida em 2027; planeje atualizações antes que os patches de segurança parem. Correção: acompanhe o cronograma de lançamentos do Node.
engines sem aplicação - npm avisa, mas instala mesmo assim por padrão. Correção: engine-strict=true em .npmrc ou um portão de CI.
Pacotes npm globais vinculados a uma versão do Node - atualizar o Node quebra CLIs globais. Correção: use npx, pnpm dlx ou devDependencies locais do projeto.
npm e Node incompatíveis - Node 24 vem com npm 10; npm mais antigo com Node mais novo causa diferenças sutis no lockfile. Correção: use o npm incluído ou fixe via Corepack.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Volta	Troca automática por projeto	Você precisa de suporte ao Windows com atrito mínimo de configuração
asdf	Uma ferramenta para várias linguagens	Equipes focadas apenas em Node que desejam o caminho mais simples
Somente Container (sem gerenciador local)	Workflows Devcontainers / Somente Docker	Iteração local rápida sem sobrecarga de container
Gerenciador de pacotes do sistema (`apt`, `brew`)	Instalações rápidas únicas	Paridade de produção ou troca de múltiplas versões

FAQs

Qual versão do Node a produção deve rodar?

Node.js 24.18.0 (Active LTS) para novas implantações. Node 22.23.1 (Maintenance LTS) é aceitável durante a migração, mas planeje atualizar antes que a manutenção termine.

Qual a diferença entre fnm e nvm?

Ambos trocam versões do Node via hooks de shell. fnm é mais rápido (escrito em Rust) e suporta o mesmo formato de arquivo .nvmrc.

Devo commitar o .nvmrc?

Sim. Commite .nvmrc ou .node-version para que cada desenvolvedor e job de CI resolva a mesma versão.

Como o Volta fixa as versões?

Adicione uma seção volta ao package.json:

"volta": { "node": "24.18.0", "npm": "10.9.0" }

Volta troca automaticamente quando você entra no diretório do projeto.

O que faz o engineStrict?

Quando engine-strict=true em .npmrc, npm se recusa a instalar se o Node/npm em execução não satisfizer engines.

Posso usar Corepack para pnpm ou Yarn?

Sim. corepack enable ativa a versão do gerenciador de pacotes declarada no campo packageManager:

"packageManager": "pnpm@9.15.0"

Como atualizar o Node na CI?

Combine a CI com .nvmrc:

- uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'

E os desenvolvedores Windows?

fnm, nvm-windows e Volta suportam Windows. Documente uma ferramenta canônica no README da equipe.

Versões de número ímpar como Node 25 devem ser usadas?

Não para produção. Lançamentos ímpares são "Current" e de curta duração. Use Active LTS (números pares) para serviços.

Como verifico o que está instalado globalmente?

npm list -g --depth=0

Prefira devDependencies locais do projeto em vez de globais para reprodutibilidade.

O Alpine Linux precisa de imagens Node especiais?

Alpine usa musl libc - alguns add-ons nativos precisam de etapas de compilação extras. bookworm-slim (Debian) é mais seguro para módulos nativos.

Como migro do Node 20 para o 24?

Atualize primeiro as máquinas de desenvolvimento e a CI, execute a suíte de testes, verifique os avisos de API depreciados com NODE_OPTIONS=--pending-deprecation, depois faça o rollout para produção.

Relacionados

Política de Lançamento e LTS do Node.js - Current vs Active vs Maintenance
Noções Básicas de Node.js - primeiros comandos após a instalação
Executando Scripts e Shebang - bins executáveis e linhas shebang
Lendo a Documentação Oficial e Diagnósticos - quando as atualizações surpreendem

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Receita

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

// package.json
{
  "engines": {
    "node": ">=24.18.0 <25",
    "npm": ">=10.0.0"
  },
  "engineStrict": true
}

# .nvmrc
24.18.0

Quando usar isso:

Onboarding de um novo desenvolvedor em um serviço Node existente
Atualização do Node 22 Maintenance LTS para o Node 24 Active LTS
Pipelines de CI que silenciosamente selecionam o runtime incorreto
Monorepos onde múltiplos serviços compartilham uma política de versão do Node

Exemplo de Trabalho

# Instalar fnm (macOS/Linux) - gerenciador de versões rápido e cross-shell
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 24.18.0
fnm use 24.18.0
node --version  # v24.18.0

// Trecho do package.json
{
  "name": "billing-api",
  "type": "module",
  "engines": { "node": ">=24.18.0 <25" },
  "scripts": {
    "preinstall": "node scripts/check-node-version.mjs"
  }
}

// scripts/check-node-version.mjs
const required = 24;
const major = Number(process.versions.node.split('.')[0]);
if (major !== required) {
  console.error(`Node ${required}.x é necessário, mas obteve ${process.version}`);
  process.exit(1);
}

O que isso demonstra:

Arquivos .nvmrc / .node-version integram-se com fnm, nvm e asdf
engines documenta o intervalo suportado para humanos e ferramentas
Um script preinstall falha rapidamente antes que npm install baixe pacotes
Fixar <25 exclui lançamentos Atuais (de número ímpar) inadequados para produção

Mergulho Profundo

Como Funciona

Gerenciadores de versão instalam múltiplos binários do Node lado a lado e trocam o ativo via hooks de shell.
engines é consultivo, a menos que engine-strict=true em .npmrc ou você adicione scripts de aplicação.
Docker/Kubernetes devem usar imagens oficiais node:24.18.0-bookworm-slim - não node:latest.
Volta fixa versões por projeto no campo volta do package.json e troca automaticamente ao usar cd.

Comparação de Gerenciadores de Versão

Ferramenta	Velocidade	Modelo de fixação	Melhor para
fnm	Rápido (Rust)	`.nvmrc`, hook de shell	Desenvolvimento diário em macOS/Linux
nvm	Moderada	`.nvmrc`, amplamente conhecido	Documentação e tutoriais legados
Volta	Rápido	Bloco `volta` do `package.json`	Equipes que desejam `use` manual zero
asdf	Baseado em plugin	`.tool-versions`	Repositórios políglotos (Node + Ruby + Go)

Notas de TypeScript

// Lê a versão do runtime na inicialização e a expõe em /health
export function runtimeInfo(): { node: string; platform: string } {
  return {
    node: process.version,
    platform: `${process.platform}-${process.arch}`,
  };
}

Armadilhas

Usar node:latest no Docker - cada build pode obter uma versão principal diferente. Correção: fixe node:24.18.0-bookworm-slim com um digest.
Ignorar datas de fim do Maintenance LTS - Node 22 entra em fim de vida em 2027; planeje atualizações antes que os patches de segurança parem. Correção: acompanhe o cronograma de lançamentos do Node.
engines sem aplicação - npm avisa, mas instala mesmo assim por padrão. Correção: engine-strict=true em .npmrc ou um portão de CI.
Pacotes npm globais vinculados a uma versão do Node - atualizar o Node quebra CLIs globais. Correção: use npx, pnpm dlx ou devDependencies locais do projeto.
npm e Node incompatíveis - Node 24 vem com npm 10; npm mais antigo com Node mais novo causa diferenças sutis no lockfile. Correção: use o npm incluído ou fixe via Corepack.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Volta	Troca automática por projeto	Você precisa de suporte ao Windows com atrito mínimo de configuração
asdf	Uma ferramenta para várias linguagens	Equipes focadas apenas em Node que desejam o caminho mais simples
Somente Container (sem gerenciador local)	Workflows Devcontainers / Somente Docker	Iteração local rápida sem sobrecarga de container
Gerenciador de pacotes do sistema (`apt`, `brew`)	Instalações rápidas únicas	Paridade de produção ou troca de múltiplas versões

FAQs

Qual versão do Node a produção deve rodar?

Node.js 24.18.0 (Active LTS) para novas implantações. Node 22.23.1 (Maintenance LTS) é aceitável durante a migração, mas planeje atualizar antes que a manutenção termine.

Qual a diferença entre fnm e nvm?

Ambos trocam versões do Node via hooks de shell. fnm é mais rápido (escrito em Rust) e suporta o mesmo formato de arquivo .nvmrc.

Devo commitar o .nvmrc?

Sim. Commite .nvmrc ou .node-version para que cada desenvolvedor e job de CI resolva a mesma versão.

Como o Volta fixa as versões?

Adicione uma seção volta ao package.json:

"volta": { "node": "24.18.0", "npm": "10.9.0" }

Volta troca automaticamente quando você entra no diretório do projeto.

O que faz o engineStrict?

Quando engine-strict=true em .npmrc, npm se recusa a instalar se o Node/npm em execução não satisfizer engines.

Posso usar Corepack para pnpm ou Yarn?

Sim. corepack enable ativa a versão do gerenciador de pacotes declarada no campo packageManager:

"packageManager": "pnpm@9.15.0"

Como atualizar o Node na CI?

Combine a CI com .nvmrc:

- uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'

E os desenvolvedores Windows?

fnm, nvm-windows e Volta suportam Windows. Documente uma ferramenta canônica no README da equipe.

Versões de número ímpar como Node 25 devem ser usadas?

Não para produção. Lançamentos ímpares são "Current" e de curta duração. Use Active LTS (números pares) para serviços.

Como verifico o que está instalado globalmente?

npm list -g --depth=0

Prefira devDependencies locais do projeto em vez de globais para reprodutibilidade.

O Alpine Linux precisa de imagens Node especiais?

Alpine usa musl libc - alguns add-ons nativos precisam de etapas de compilação extras. bookworm-slim (Debian) é mais seguro para módulos nativos.

Como migro do Node 20 para o 24?

Relacionados

Política de Lançamento e LTS do Node.js - Current vs Active vs Maintenance
Noções Básicas de Node.js - primeiros comandos após a instalação
Executando Scripts e Shebang - bins executáveis e linhas shebang
Lendo a Documentação Oficial e Diagnósticos - quando as atualizações surpreendem

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Instalação e Gerenciamento de Versões

Buscar na documentação

Instalação e Gerenciamento de Versões