Guia Completo do Arquivo settings.xml do Maven

O que é o arquivo settings.xml e por que configurá-lo?

O arquivo settings.xml é o arquivo de configuração usado para definir parâmetros do Maven. Trata-se do arquivo de configuração global do Maven, enquanto o pom.xml representa configurações locais de cada projeto.

O settings.xml contém configurações como o caminho do repositório local, servidores de repositório remoto alternativos e informações de autenticação.

Localização do arquivo settings.xml

O arquivo settings.xml pode ser encontrado em dois locais:

  • Configuração global: ${M2_HOME}/conf/settings.xml
  • Configuração do usuário: ${user.home}/.m2/settings.xml

Observação: A configuração do usuário tem precedência sobre a configuração global. A variável {user.home} e outras propriedades do sistema estão disponíveis apenas a partir da versão 3.0+ do Maven. É importante注意到 no Windows e Linux.

Precedência de Configurações

É fundamental compreender que configurações locais prevalecem sobre as globais.

A ordem de precedência, da mais alta para a mais baixa, é:

  1. pom.xml
  2. configurações do usuário (user settings)
  3. configurações globais (global settings)

Quando esses arquivos coexistem, o Maven mescla seu conteúdo. Em caso de duplicatas, a configuração de maior precedência sobrescreve a de menor precedência.

Elementos do settings.xml

Visão Geral dos Elementos Raiz

O arquivo settings.xml contém os seguintes elementos principais:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                          https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <usePluginRegistry/>
  <offline/>
  <pluginGroups/>
  <servers/>
  <mirrors/>
  <proxies/>
  <profiles/>
  <activeProfiles/>
</settings>

LocalRepository

Função: Define o caminho do repositório local no sistema de build.

Valor padrão: ~/.m2/repository

<localRepository>/home/desenvolvedor/.m2/repositorio</localRepository>

InteractiveMode

Função: Define se o Maven deve interagir com o usuário para obter entrada de dados.

Defina como true para interação ativa, ou false para execução automatizada. O valor padrão é true.

<interactiveMode>true</interactiveMode>

UsePluginRegistry

Função: Define se o Maven deve utilizar o arquivo plugin-registry.xml para gerenciar versões de plugins.

Defina como true para usar o arquivo ~/.m2/plugin-registry.xml no gerenciamento de plugins. O valor padrão é false.

<usePluginRegistry>false</usePluginRegistry>

Offline

Função: Define se o Maven deve operar em modo offline.

Defina como true quando o servidor de build não puder se conectar a repositórios remotos devido a configurações de rede ou fatores de segurança. O valor padrão é false.

<offline>false</offline>

PluginGroups

Função: Lista de grupos de plugins usados para pesquisar o groupId de plugins quando não for especificado explicitamente.

Cada elemento pluginGroup contém um groupId. Quando um plugin é utilizado sem especificar o groupId na linha de comando, o Maven pesquisa nesta lista. Por padrão, a lista inclui org.apache.maven.plugins e org.codehaus.mojo.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <pluginGroups>
    <pluginGroup>org.codehaus.mojo</pluginGroup>
  </pluginGroups>
</settings>

Servers

Função: Define configurações de autenticação para repositórios.

Geralmente, o download e deploy de repositórios são definidos no pom.xml através dos elementos repositories e distributionManagement. No entanto, informações confidenciais como nomes de usuário e senhas não devem ser configuradas no pom.xml; essas informações devem ser configuradas no settings.xml.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>servidorproducao</id>
      <username>admin</username>
      <password>senha123</password>
      <privateKey>${user.home}/.ssh/id_rsa</privateKey>
      <passphrase>fraseSegura</passphrase>
      <filePermissions>644</filePermissions>
      <directoryPermissions>755</directoryPermissions>
    </server>
  </servers>
</settings>

O elemento id deve corresponder ao id definido no elemento repository do distributionManagement. A partir do Maven 2.1.0, existe suporte para senhas criptografadas.

Mirrors

Função: Lista de espelhos para download de repositórios.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <mirrors>
    <mirror>
      <id>espelhoBrasil</id>
      <name>Mirror Brasil</name>
      <url>http://mirror.ufscar.br/maven2</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

O elemento mirrorOf especifica qual repositório será redirecionado para este espelho. Para espelhar o repositório central, utilize central.

Proxies

Função: Configuração de proxies para acesso à internet.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <proxies>
    <proxy>
      <id>proxycorporativo</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.empresa.com.br</host>
      <port>3128</port>
      <username>usuarioProxy</username>
      <password>senhaProxy</password>
      <nonProxyHosts>localhost|*.empresa.local</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

O elemento nonProxyHosts lista os hosts que não devem usar o proxy, separados por pipe (|) ou vírgula.

Profiles

Função: Lista de perfis que ajustam a configuração de build conforme parâmetros ambientais.

O elemento profile no settings.xml é uma versão reduzida do elemento profile presente no pom.xml. Ele contém apenas os elementos id, activation, repositories, pluginRepositories e properties. Quando um profile no settings.xml é ativado, seus valores substituem qualquer profile definido no pom.xml com o mesmo id.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <profiles>
    <profile>
      <id>desenvolvimento</id>
      <activation />
      <properties />
      <repositories />
      <pluginRepositories />
    </profile>
  </profiles>
</settings>

Activation

Função: Define condições para ativação automática do profile.

Assim como no pom.xml, o profile pode ser ativado automaticamente em ambientes específicos através do elemento activation. O profile também pode ser ativado manualmente através do elemento activeProfiles no settings.xml ou pela flag -P na linha de comando.

<activation>
  <activeByDefault>false</activeByDefault>
  <jdk>11</jdk>
  <os>
    <name>Linux</name>
    <family>Linux</family>
    <arch>amd64</arch>
    <version>5.4.0</version>
  </os>
  <property>
    <name>ambiente</name>
    <value>desenvolvimento</value>
  </property>
  <file>
    <exists>${basedir}/config/dev.properties</exists>
    <missing>${basedir}/config/prod.properties</missing>
  </file>
</activation>

Dica: Execute mvn help:active-profiles no diretório do projeto para verificar quais profiles estão ativos.

Properties

Função: Lista de propriedades extensíveis para o profile.

As propriedades do Maven funcionam como no Ant, armazenando valores que podem ser usados em qualquer lugar do pom.xml através da notação ${X}, onde X é o nome da propriedade.

<properties>
  <projeto.local>${user.home}/projetos/meu-projeto</projeto.local>
</properties>

Existem cinco formas de acessar propriedades:

  1. env.X: Variáveis de ambiente (ex: ${env.PATH})
  2. project.x: Elementos do POM (ex: ${project.version})
  3. settings.x: Elementos do settings.xml (ex: ${settings.offline})
  4. Propriedades do Sistema Java: Ex: ${java.home}
  5. x: Propriedades definidas no elemento properties

Repositories

Função: Lista de repositórios remotos usados para preencher o repositório local.

<repositories>
  <repository>
    <id>repoInterno</id>
    <name>Repositório Interno</name>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>daily</updatePolicy>
      <checksumPolicy>warn</checksumPolicy>
    </releases>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
      <checksumPolicy>fail</checksumPolicy>
    </snapshots>
    <url>http://repo.empresa.com.br/maven2</url>
    <layout>default</layout>
  </repository>
</repositories>

O elemento updatePolicy define a frequência de atualização: always (sempre), daily (diário), interval:X (intervalo em minutos), ou never (nunca). O elemento checksumPolicy define o comportamento quando a validação de checksum falha: ignore, fail, ou warn.

PluginRepositories

Função: Lista de repositórios remotos para descoberta de plugins.

Assim como repositories gerencia dependências JAR, pluginRepositories gerencia plugins. Plugins são um tipo especial de artefato, por isso seus repositórios são independentes.

<pluginRepositories>
  <pluginRepository>
    <releases>
      <enabled>true</enabled>
      <updatePolicy>daily</updatePolicy>
    </releases>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
    <id>pluginRepo</id>
    <name>Plugin Repository</name>
    <url>http://plugins.empresa.com.br</url>
    <layout>default</layout>
  </pluginRepository>
</pluginRepositories>

ActiveProfiles

Função: Lista de profiles ativados manualmente.

Este elemento contém um conjunto de elementos activeProfile, cada um com um id de profile. Qualquer profile definido em activeProfiles será ativado independentemente das condições ambientais.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <activeProfiles>
    <activeProfile>ambiente-desenvolvimento</activeProfile>
  </activeProfiles>
</settings>

Por exemplo, se ambiente-desenvolvimento for um activeProfile, o profile correspondente no pom.xml será ativado durante a execução do Maven.

Tags: maven java build-automation settings.xml dependency-management

Publicado em 6-3 16:25 por Thomas

Tags em Destaque

©2026 Doido Dev