SpringBoot使用Jib推送镜像至DockerHub时出现401未授权错误

计划通过Jib将微服务项目容器化并推送至DockerHub时，触发DockerHub仓库401未授权错误，相关配置及错误信息如下：

pom.xml配置 #

<plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.2.1</version>
        <configuration>
          <from>
            <image>eclipse-temurin:17.0.4.1_1-jre</image>
          </from>
          <to>
            <image>registry.hub.docker.com/freelance_platform/${artifactId}</image>
          </to>

        </configuration>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>build</goal>
            </goals>
          </execution>
        </executions>
      </plugin>

.m2/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
            http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <servers>
    <server>
    <id>registry.hub.docker.com</id>
    <username>*****</username>
    <password>****</password>
</server>
    </servers>
    <interactiveMode/>
    <userPluginRegistry/>
    <offline/>
    <pluginGroups/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

错误信息 #

[ERROR] Failed to execute goal com.google.cloud.tools:jib-maven-plugin:3.2.1:build (default) on project userjob: Build image failed, perhaps you should make sure your credentials for 'registry.hub.docker.com/freelance_platform/userjob' are set up correctly. See https://github.com/GoogleContainerTools/jib/blob/master/docs/faq.md#what-should-i-do-when-the-registry-responds-with-unauthorized for help: Unauthorized for registry.hub.docker.com/freelance_platform/userjob: 401 Unauthorized -> [Help 1]

排查与解决步骤 #

1. 验证DockerHub凭证有效性 #

• 确认settings.xml中的用户名是DockerHub的账户用户名（不是注册邮箱），这是常见错误点。
• 若使用账户密码，检查密码是否未过期；若使用个人访问令牌（PAT），确保令牌已开启write仓库权限，且未被撤销或过期。

2. 修正Maven Server ID匹配 #

Jib默认匹配DockerHub的server ID为docker.io，而非registry.hub.docker.com，修改settings.xml中的server配置：

<server>
  <id>docker.io</id>
  <username>你的DockerHub用户名</username>
  <password>你的DockerHub密码/PAT</password>
</server>

也可以在Jib插件配置中显式指定server ID，确保匹配：

<to>
  <image>registry.hub.docker.com/freelance_platform/${artifactId}</image>
  <serverId>docker.io</serverId>
</to>

3. 检查仓库权限与命名空间 #

• 确认freelance_platform是你DockerHub账户下的有效命名空间：个人仓库格式应为用户名/仓库名，组织仓库需确保你的账户拥有该组织仓库的写入权限。
• 若命名空间错误，需修改<image>中的路径为正确格式，比如registry.hub.docker.com/你的用户名/${artifactId}。

4. 复用Docker CLI登录凭证 #

执行docker login registry.hub.docker.com，输入正确的用户名和密码完成登录，Jib会自动读取Docker的本地登录凭证，跳过Maven settings的配置验证。

5. 清理缓存与升级插件 #

• 执行mvn clean install -U清理Maven本地缓存，强制更新依赖并重新加载凭证。
• 尝试升级Jib插件到较新的稳定版本（如3.4.0及以上），修复旧版本可能存在的凭证处理bug。

内容的提问来源于stack exchange，提问作者user20112858