解决idea中可以成功执行maven命令但是通过Terminal命令行执行失败的问题

问题

通过Terminal命令行执行maven命令报错：

 mvn clean
[INFO] Scanning for projects...
[INFO] Artifact com.example:example-bom:pom:1.2.2 is present in the local repository, but cached from a remote repository ID that is unavailable in current build context, verifying that is downloadable from [central (https://repo.maven.apache.org/maven2, default, releases)]
[INFO] Artifact com.example:example-bom:pom:1.2.2 is present in the local repository, but cached from a remote repository ID that is unavailable in current build context, verifying that is downloadable from [central (https://repo.maven.apache.org/maven2, default, releases)]
[ERROR] [ERROR] Some problems were encountered while processing the POMs:
[FATAL] Non-resolvable parent POM for com.example:example-common:1.2.3-SNAPSHOT: The following artifacts could not be resolved: com.example:example-bom:pom:1.2.2 (present, but unavailable): com.example:example-bom:pom:1.2.2 was not found in https://repo.maven.apache.org/maven2 during a previous attempt. This failure was cached in the local repository and resolution is not reattempted until the update interval of central has elapsed or updates are forced and 'parent.relativePath' points at no local POM @ line 4, column 13
 @ 
[ERROR] The build could not read 1 project -> [Help 1]
[ERROR]   
[ERROR]   The project com.example:example-common:1.2.3-SNAPSHOT (/Users/bjsttlp176/WorkSpace/Public/example-common/pom.xml) has 1 error
[ERROR]     Non-resolvable parent POM for com.example:example-common:1.2.3-SNAPSHOT: The following artifacts could not be resolved: com.example:example-bom:pom:1.2.2 (present, but unavailable): com.example:example-bom:pom:1.2.2 was not found in https://repo.maven.apache.org/maven2 during a previous attempt. This failure was cached in the local repository and resolution is not reattempted until the update interval of central has elapsed or updates are forced and 'parent.relativePath' points at no local POM @ line 4, column 13 -> [Help 2]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/ProjectBuildingException
[ERROR] [Help 2] http://cwiki.apache.org/confluence/display/MAVEN/UnresolvableModelException

不止是mvn clean，执行其他的maven命令也会失败，报错原因大同小异。

但是通过idea中的maven面板执行就能成功：

[INFO] Reactor Summary for example-common 1.2.3-SNAPSHOT:
[INFO] 
[INFO] example-common ...................................... SUCCESS [  0.054 s]
[INFO] example-common-constants ............................ SUCCESS [  0.001 s]
[INFO] example-common-swagger .............................. SUCCESS [  0.001 s]
[INFO] example-common-utils ................................ SUCCESS [  0.001 s]
[INFO] example-common-redis-tools .......................... SUCCESS [  0.001 s]
[INFO] redis-common-core .................................. SUCCESS [  0.001 s]
[INFO] redis-common-starter ............................... SUCCESS [  0.001 s]
[INFO] example-common-regular .............................. SUCCESS [  0.002 s]
[INFO] example-common-security ............................. SUCCESS [  0.002 s]
[INFO] example-common-web .................................. SUCCESS [  0.001 s]
[INFO] spring-common-util ................................. SUCCESS [  0.001 s]
[INFO] example-common-datasource ........................... SUCCESS [  0.002 s]
[INFO] example-common-dtp .................................. SUCCESS [  0.024 s]
[INFO] example-common-lb ................................... SUCCESS [  0.000 s]
[INFO] example-common-center-config ........................ SUCCESS [  0.001 s]
[INFO] example-apollo-config-starter ....................... SUCCESS [  0.001 s]
[INFO] example-common-trace ................................ SUCCESS [  0.001 s]
[INFO] web-common-config .................................. SUCCESS [  0.001 s]
[INFO] example-common-http ................................. SUCCESS [  0.002 s]
[INFO] example-common-mq ................................... SUCCESS [  0.000 s]
[INFO] kafka-swim-line .................................... SUCCESS [  0.001 s]
[INFO] example-kafka-starter ............................... SUCCESS [  0.001 s]
[INFO] example-common-mybatis .............................. SUCCESS [  0.001 s]
[INFO] example-rocketmq-starter ............................ SUCCESS [  0.003 s]
[INFO] kafka-swim-line-2.8.x .............................. SUCCESS [  0.001 s]
[INFO] example-common-auth ................................. SUCCESS [  0.001 s]
[INFO] example-auth-client ................................. SUCCESS [  0.001 s]
[INFO] example-common-transport ............................ SUCCESS [  0.001 s]
[INFO] example-transport-auth .............................. SUCCESS [  0.002 s]
[INFO] example-transport-auth-client-starter ............... SUCCESS [  0.002 s]
[INFO] example-transport-auth-client-javax-starter ......... SUCCESS [  0.001 s]
[INFO] example-collect ..................................... SUCCESS [  0.002 s]
[INFO] context-collect-javax .............................. SUCCESS [  0.002 s]
[INFO] example-transport-starter ........................... SUCCESS [  0.001 s]
[INFO] example-transport-javax-starter ..................... SUCCESS [  0.002 s]
[INFO] example-transport-jakarta-starter ................... SUCCESS [  0.001 s]
[INFO] example-common-log .................................. SUCCESS [  0.001 s]
[INFO] example-common-sentinel ............................. SUCCESS [  0.001 s]
[INFO] sentinel-common-core ............................... SUCCESS [  0.001 s]
[INFO] sentinel-app-starter ............................... SUCCESS [  0.001 s]
[INFO] sentinel-gateway-starter ........................... SUCCESS [  0.000 s]
[INFO] example-common-job .................................. SUCCESS [  0.001 s]
[INFO] example-auth-client-starter ......................... SUCCESS [  0.001 s]
[INFO] example-auth-client-javax-starter ................... SUCCESS [  0.001 s]
[INFO] example-common-liquibase ............................ SUCCESS [  0.001 s]
[INFO] web-common-util .................................... SUCCESS [  0.002 s]
[INFO] example-common-graceful-shutdown .................... SUCCESS [  0.001 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.400 s
[INFO] Finished at: 2025-07-23T15:33:32+08:00
[INFO] ------------------------------------------------------------------------

问题排查

一开始以为是maven版本不一致导致的。

IDEA 使用的是内置 Maven 3.9.9（路径：/Applications/IntelliJ IDEA.app/Contents/plugins/maven/lib/maven3）

系统环境使用的是 Homebrew 安装的 Maven 3.9.9（路径：/opt/homebrew/Cellar/maven/3.9.9/libexec）

虽然版本号相同，但路径不同可能导致配置冲突。

所以修改了idea的maven路径，和系统环境的一致，结果问题依旧。

后来通过比较idea的maven命令参数，发现其实idea执行maven命令的时候，通过命令行参数（-s）指定了项目的配置文件，这个配置文件中的仓库地址是私服的仓库地址。

而系统环境执行maven则使用的是maven默认的配置文件，导致Maven 在本地仓库中找到了依赖包，但由于某些原因无法验证其有效性，因此尝试从中央仓库重新下载。然而中央仓库并没有我自己的依赖包，导致下载失败。

通过Terminal命令行加-s参数的方式也验证了这个问题：

 mvn clean -s /WorkSoft/maven/common/settings.xml

解决办法

解决办法有两种，一种是使用-s指定配置文件，不过这样太麻烦，每次执行命令都需要加；第二个办法就是修改Maven的默认配置文件。

下面说几个修改maven配置文件的办法：

Maven 默认配置文件的设置方法

Maven 支持两种配置文件，并且会按照特定的优先级加载它们。要设置默认配置文件而不使用 -s 参数，可以通过以下方式实现：

1. 全局配置文件（System-wide Settings）

Maven 会自动读取其安装目录下的 conf/settings.xml 文件：

${MAVEN_HOME}/conf/settings.xml

优点：所有项目默认使用此配置，无需额外配置。
缺点：修改需要管理员权限，不适合多环境切换。

2. 用户配置文件（User-specific Settings）

Maven 会自动读取用户主目录下的 settings.xml 文件：

${user.home}/.m2/settings.xml

配置步骤：

1. 在用户主目录下创建 .m2 文件夹（如果不存在）：

   mkdir -p ~/.m2

2. 在 .m2 目录下创建或编辑 settings.xml 文件：

   touch ~/.m2/settings.xml

3. 添加你的配置（如镜像、仓库、认证等）：

   <settings>
   <mirrors>
       <mirror>
           <id>private-repo</id>
           <mirrorOf>*</mirrorOf>
           <url>http://your-private-repo.com/repository/maven-public/</url>
       </mirror>
   </mirrors>
   </settings>

3. 环境变量配置（高级方法）

通过设置 MAVEN_OPTS 或 MAVEN_SKIP_RC 环境变量，可以覆盖默认行为：

方法 1：设置 MAVEN_OPTS

在 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）中添加：

export MAVEN_OPTS="-s /path/to/your/settings.xml"

效果：所有 Maven 命令都会自动使用指定的配置文件。

方法 2：使用 mavenrc 文件

1. 在用户主目录下创建 .mavenrc 文件：

   touch ~/.mavenrc

2. 添加以下内容：

   MAVEN_SKIP_RC=true  # 跳过默认配置
   MAVEN_OPTS="-s /path/to/your/settings.xml"

4. IDE 中的配置

在 IntelliJ IDEA 中设置默认配置文件：

1. 打开 File > Settings > Build, Execution, Deployment > Build Tools > Maven。
2. 在 User settings file 字段中指定路径（如 ~/.m2/settings.xml）。
3. 勾选 Override 选项，确保 IDEA 使用此配置。

优先级顺序

Maven 加载配置的优先级从高到低为：

1. 命令行参数 -s /path/to/settings.xml
2. MAVEN_OPTS 环境变量中指定的 -s 参数
3. 用户主目录下的 ~/.m2/settings.xml
4. Maven 安装目录下的 ${MAVEN_HOME}/conf/settings.xml

验证方法

使用以下命令查看 Maven 实际使用的配置：

mvn help:effective-settings

输出会显示当前生效的配置文件路径和内容。

注意事项

• 如果同时存在全局和用户配置文件，Maven 会合并它们，用户配置优先级更高。
• 修改配置后，可能需要重启 IDE 或终端会话才能生效。
• 对于企业环境，推荐使用用户配置文件，避免修改全局配置。