JAVA_HOME, CLASSPATH e PATH no Mac (JDK moderno)

Configurar ambiente Java no macOS confunde até seniors quando Apple muda layout do JDK, OpenJDK Homebrew convive com Oracle installer e IDEs injetam JAVA_HOME próprio. Reescrevo este guia — corrigindo link quebrado //blog/ do post antigo — com foco em macOS Sequoia/Sonoma e JDK 17/21 LTS, padrão em clientes TEK Softwares e builds ProGuard (ofuscar projetos Java).

Três variáveis que importam

JAVA_HOME — raiz do JDK (compilador, libs).
PATH — deve incluir $JAVA_HOME/bin para java e javac corretos.
CLASSPATH — raramente export global hoje; Maven/Gradle gerenciam. Evite CLASSPATH manual salvo legado.

JDK no Mac 2026: opções

Homebrew — brew install openjdk@21, symlink instructions printed post-install.
SDKMAN — sdk install java 21.0.4-tem, switch por projeto.
Oracle/Temurin PKG — installer GUI, path /Library/Java/JavaVirtualMachines/...

Verifique versão ativa:

java -version
/usr/libexec/java_home -V

Definir JAVA_HOME no zsh (padrão Mac)

Edite ~/.zshrc (não .bash_profile se shell é zsh):

export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$JAVA_HOME/bin:$PATH"

Pin versão específica se múltiplas instaladas: -v 21 ou caminho completo do .jdk bundle.

Projeto por projeto: jenv ou toolchains

Monorepo com Java 11 legado e 21 novo? Use jenv local ou Maven toolchain:

<toolchains>
  <jdk>
    <version>21</version>
  </jdk>
</toolchains>

IDE versus terminal

IntelliJ pode usar Embedded JDK 21 enquanto terminal aponta 17 — sintomas: build OK na IDE, falha no CI. Alinhe Project SDK e Module language level. VS Code Java extension respeita JAVA_HOME se Red Hat settings não override.

ProGuard e jlink

Plugins ofuscador precisam JDK completo, não JRE reduzido. Erro "can't find rt.jar" significa configuração antiga — aponte para JDK home modular. Ver artigo ProGuard moderno.

Link corrigido: ofuscação Java

Referência interna correta: Ofuscar e compactar projetos Java — não use URL duplicada //blog/ que quebra em alguns ambientes.

Windows/Linux colegas

Mac dev em time misto: documente versão exata no README. Windows usa setx JAVA_HOME ou painel Environment Variables; Linux usa /etc/profile.d/ ou direnv.

Diagnóstico rápido

echo $JAVA_HOME
which java
mvn -version

Três comandos revelam 90% dos mismatches antes de perder hora em UnsupportedClassVersionError.

M1/M2 Apple Silicon

JDK aarch64 nativo — Azul Zulu, Temurin ARM. Rosetta x86 JDK funciona mas desperdiça bateria dev laptop. Verifique arch: file $(which java).

Docker Desktop Java build

Container linux amd64 vs arm64 pipeline CI; buildx multi-arch se cliente deploy x86 servidor. Toolchain Maven docker profile evita drift.

Corretto vs Temurin vs Oracle

Todos LTS válidos; escolha uma distro por org documente. Mix gera bug sutil timezone tzdata.

IntelliJ Maven import JDK

File Project Structure SDK aponta JAVA_HOME zshrc. Invalidate caches após trocar JDK major — indexes corrompidos sintoma estranho.

Multiple projects jEnv

jenv local 21.0.4 diretório projeto legado 11.0.24. echo $(jenv version-name) prompt opcional lembrar contexto.

CI Mac runner versus Linux

GitHub macos-latest build desktop assinado; linux build server jar. Alinhe JAVA_HOME workflow yaml actions/setup-java distribution temurin cache.

Troubleshooting UnsupportedClassVersion

Compile 21 run 17 — erro clássico. mvn -version java -version devem match major. Target bytecode pom.xml release 17 compatibilidade LTS cliente.

Shell login versus non-login mac

Terminal.app login shell carrega zprofile zshrc. IDE launched Finder pode nao herdar JAVA_HOME — configure IDE explicit ou launchctl setenv legacy cuidado reboot. Documento ambos caminhos README evita thread slack horas debug.

Homebrew openjdk postinstall symlink instrucao copiar colar sudo ln -sfn path. Esquecer passo java version system stub mac ainda 1.6 fantasma path.

jEnv local version file

Arquivo .java-version commitado repo java 21.0.4-tem jenv local ativa automatico cd projeto. Novo dev clone repo jenv version correto sem ler wiki tres paginas JAVA_HOME.

asdf java plugin alternativa similar multi runtime node python lado lado projeto fullstack.

FAQ suporte TEK JAVA_HOME

Pergunta one: java version wrong terminal — fix zshrc source reload exec zsh. Pergunta two: IDE compile 21 run 17 — align Project SDK Maven toolchain. Pergunta three: mvn not found — PATH brew maven ou mvnw wrapper commitado repo prefer wrapper zero drift. Documento FAQ reduz ticket repetido oitenta porcento onboard cliente.

Para equipes mistas Windows Mac documente três blocos copy-paste README evitando artigo stackoverflow desatualizado 2018 JAVA_HOME Program Files. Link cruzado blog Windows futuro mantém paridade onboarding global cliente multinacional pequeno porte.

Prática adicional TEK Softwares: revise este tópico com stakeholder operacional antes de fechar sprint — alinhamento negócio evita retrabalho custoso em produção fiscal e integrações críticas ERP que atendem milhares documentos eletrônicos mensais sem downtime planejado inadequado.

Documente lições aprendidas DECISIONS.md link artigos relacionados blog tiagoek manutenção longo prazo conteúdo AdSense qualidade leitor desenvolvedor arquiteto tom primeira pessoa experiência vinte anos mercado brasileiro software sob medida impressão 3D marca TEK unificada confiança cliente indicacao orgânica composição juros reputação técnica honestidade entrega previsível pipeline verde segurança prepared statement parametros pentaho cfop correto.

Referência cruzada TEK: combine este guia com práticas de produtividade, pipeline verde e integração ERP documentada nos demais artigos do blog tiagoek — leitura sequencial forma trilha onboarding completa para novos consultores da TEK Softwares em projetos Java, PHP, Pentaho e fiscal brasileiro.

Conclusão

JAVA_HOME no Mac moderno: /usr/libexec/java_home, zshrc versionado, toolchains por projeto, IDE alinhada ao terminal. Abandone rt.jar e CLASSPATH global herdados de 2010. Ambiente previsível acelera tudo — integração Pentaho, ERP fiscal, CI — porque build deixa de ser loteria.