Gerenciamento de Versão Node.js

fnm fornece recursos poderosos de gerenciamento de versão, permitindo que você alterne facilmente entre múltiplas versões do Node.js.

Operações Básicas

Visualizar Versões Instaladas

fnm list

Exemplo de saída:

* v20.10.0 default
  v18.19.0
  v16.20.2

• * indica a versão atualmente em uso
• default indica a versão padrão

Visualizar Versão Atual

fnm current

Alternar Versão

# Alternar para versão específica
fnm use 20

# Alternar para versão exata específica
fnm use 20.10.0

# Se a versão não estiver instalada, instalar automaticamente e alternar
fnm use 18 --install-if-missing

Versão Padrão

Definir Versão Padrão

fnm default 20

A versão padrão é:

• A versão usada quando uma nova sessão de terminal é iniciada
• A versão usada quando não há arquivo de versão

Visualizar Versão Padrão

fnm default

Aliases de Versão

Aliases permitem que você defina nomes fáceis de lembrar para versões.

Criar Alias

# Definir alias para versão
fnm alias 20 default
fnm alias 18 legacy
fnm alias 16 old

Usar Alias

# Alternar versão via alias
fnm use default
fnm use legacy

Excluir Alias

fnm unalias legacy

Troca Automática de Versão

fnm pode alternar automaticamente as versões do Node.js com base no diretório do projeto.

Habilitar Troca Automática

Adicione --use-on-cd à configuração do Shell:

eval "$(fnm env --use-on-cd)"

Criar Arquivo de Versão

Crie um arquivo .node-version ou .nvmrc na raiz do projeto:

# Usando .node-version (recomendado)
echo "20" > .node-version

# Ou usando .nvmrc (compatível com nvm)
echo "v18.17.0" > .nvmrc

Formato do Arquivo de Versão

.node-version suporta os seguintes formatos:

20           # Versão principal, usar último 20.x.x
20.10        # Versão secundária, usar último 20.10.x
20.10.0      # Versão exata
lts/iron     # Nome da versão LTS

Estratégia de Análise de Arquivo de Versão

fnm suporta duas estratégias de análise de arquivo de versão:

# local (padrão) - Apenas pesquisa no diretório atual
fnm env --version-file-strategy=local

# recursive - Pesquisa recursivamente nos diretórios pai
fnm env --version-file-strategy=recursive

Suporte package.json engines

fnm pode ler o campo engines.node do package.json:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

Habilitado por padrão, pode ser desabilitado via variável de ambiente:

export FNM_RESOLVE_ENGINES=false

Melhores Práticas de Gerenciamento de Versão

1. Bloqueio de Versão em Nível de Projeto

Crie um arquivo .node-version em cada projeto:

cd my-project
echo "20" > .node-version
fnm install
fnm use

2. Colaboração em Equipe

Adicione .node-version ao Git:

git add .node-version
git commit -m "chore: add .node-version"

3. Configuração CI/CD

Use fnm em ambientes CI/CD:

# GitHub Actions
- name: Instalar fnm
  run: curl -fsSL https://fnm.vercel.app/install | bash

- name: Instalar Node.js
  run: fnm install && fnm use

4. Desenvolvimento Multi-Versão

# Instalar múltiplas versões
fnm install 20
fnm install 18
fnm install 16

# Definir aliases para troca fácil
fnm alias 20 current
fnm alias 18 legacy
fnm alias 16 old

# Usar versões diferentes em projetos diferentes
cd project-new && fnm use current
cd project-old && fnm use legacy

Desinstalar Versões

# Desinstalar versão específica
fnm uninstall 16.20.2

# Desinstalar via alias (excluirá versão e todos os aliases relacionados)
fnm uninstall old

Problemas Comuns

Comando node Não Atualiza Após Troca de Versão

Certifique-se de que a configuração do Shell está correta:

# Verificar caminho do node
which node

# Deve apontar para diretório fnm
# ~/.fnm/node-versions/.../bin/node

Troca Automática Não Funciona

1. Confirme se --use-on-cd foi adicionado à configuração do Shell
2. Confirme se o arquivo de versão existe
3. Recarregue a configuração do Shell

Prioridade de Arquivo de Versão

fnm pesquisa versões na seguinte ordem:

1. Versão especificada na linha de comando
2. Arquivo .node-version
3. Arquivo .nvmrc
4. package.json engines.node
5. Versão padrão

Links Relacionados

• Instalar Node.js - Guia de instalação
• Referência de Comandos - Todas as informações de comandos
• Gerenciamento de Download - Recursos relacionados a download