软件包仓库中的 Maven 软件包

xuxiaowei · 2026 年3 月 13 日 09:30

软件包仓库中的 Maven 软件包

https://gitlab.xuxiaowei.com.cn/help/user/packages/maven_repository/_index.md

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com，私有化部署

发布 Maven 产物到项目的软件包仓库。然后，随时安装这些软件包以便将它们作为依赖使用。

有关 Maven 软件包管理器客户端使用的特定 API
端点的文档，请参阅 Maven API 文档。

支持的客户端：

mvn。了解如何构建 Maven 软件包。
gradle。了解如何构建 Gradle
软件包。
sbt。

发布到极狐GitLab软件包仓库

身份验证到软件包仓库

您需要一个令牌来发布软件包。根据您的目标，有不同的令牌可用。有关更多信息，请查看令牌的指南。

创建一个令牌并保存以便在流程中使用。

不要使用这里未记录的身份验证方法。未记录的身份验证方法可能会在将来被删除。

编辑客户端配置

更新配置以使用 HTTP 验证到 Maven 存储库。

自定义 HTTP 头

您必须将身份验证详细信息添加到客户端的配置文件中。

`mvn`

令牌类型	名称必须是	令牌
个人访问令牌	`Private-Token`	直接粘贴令牌，或定义环境变量来保存令牌
部署令牌	`Deploy-Token`	直接粘贴令牌，或定义环境变量来保存令牌
CI 作业令牌	`Job-Token`	`${CI_JOB_TOKEN}`

<name> 字段必须命名以匹配您选择的令牌。

将如下内容添加到您的 settings.xml 文件中。

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>REPLACE_WITH_NAME</name>
            <value>REPLACE_WITH_TOKEN</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

`gradle`

令牌类型	名称必须是	令牌
个人访问令牌	`Private-Token`	直接粘贴令牌，或定义环境变量来保存令牌
部署令牌	`Deploy-Token`	直接粘贴令牌，或定义环境变量来保存令牌
CI 作业令牌	`Job-Token`	`System.getenv("CI_JOB_TOKEN")`

<name> 字段必须命名以匹配您选择的令牌。

在你的 GRADLE_USER_HOME 目录中，创建一个包含以下内容的 gradle.properties 文件：

gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

添加 repositories 部分到你的 build.gradle 文件：

In Groovy DSL:

repositories {
    maven {
        url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'REPLACE_WITH_NAME'
            value = gitLabPrivateToken
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

In Kotlin DSL:

repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven")
        name = "GitLab"
        credentials(HttpHeaderCredentials::class) {
            name = "REPLACE_WITH_NAME"
            value = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("header", HttpHeaderAuthentication::class)
        }
    }
}

基本 HTTP 身份验证

您还可以使用基本 HTTP 身份验证来验证到 Maven 软件包仓库。

`mvn`

令牌类型	名称必须是	令牌
个人访问令牌	用户的用户名	直接粘贴令牌，或定义环境变量来保存令牌
部署令牌	部署令牌的用户名	直接粘贴令牌，或定义环境变量来保存令牌
CI 作业令牌	`gitlab-ci-token`	`${CI_JOB_TOKEN`

将如下内容添加到 settings.xml 文件中。

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <username>REPLACE_WITH_NAME</username>
      <password>REPLACE_WITH_TOKEN</password>
      <configuration>
        <authenticationInfo>
          <userName>REPLACE_WITH_NAME</userName>
          <password>REPLACE_WITH_TOKEN</password>
        </authenticationInfo>
      </configuration>
    </server>
  </servers>
</settings>

`gradle`

令牌类型	名称必须是	令牌
个人访问令牌	用户的用户名	直接粘贴令牌，或定义环境变量来保存令牌
部署令牌	部署令牌的用户名	直接粘贴令牌，或定义环境变量来保存令牌
CI 作业令牌	`gitlab-ci-token`	`System.getenv("CI_JOB_TOKEN")`

在您的 GRADLE_USER_HOME 目录中，创建一个包含以下内容的 gradle.properties 文件：

在 Groovy DSL 中：

repositories {
    maven {
        url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
        name "GitLab"
        credentials(PasswordCredentials) {
            username = 'REPLACE_WITH_NAME'
            password = gitLabPrivateToken
        }
        authentication {
            basic(BasicAuthentication)
        }
    }
}

在 Kotlin DSL 中：

repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven")
        name = "GitLab"
        credentials(BasicAuthentication::class) {
            username = "REPLACE_WITH_NAME"
            password = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("basic", BasicAuthentication::class)
        }
    }
}

`sbt`

令牌类型	名称必须是	令牌
个人访问令牌	用户的用户名	直接粘贴令牌，或定义环境变量来保存令牌
部署令牌	部署令牌的用户名	直接粘贴令牌，或定义环境变量来保存令牌
CI 作业令牌	`gitlab-ci-token`	`sys.env.get("CI_JOB_TOKEN").get`

SBT 的身份验证基于基本 HTTP 身份验证。您必须提供名称和密码。

名称字段必须与您选择的令牌匹配。

要使用 sbt 从 Maven GitLab 软件包仓库安装软件包，您必须配置 Maven
解析器。如果您正在访问私有或内部项目或群组，您需要设置凭证。配置解析器和身份验证后，您可以从项目、群组或命名空间安装软件包。

在您的 build.sbt 中，添加以下行：

命名约定

您可以使用三个端点之一安装 Maven 软件包。您必须将软件包发布到项目，但您选择的端点决定了您在 pom.xml 文件中添加的用于发布的设置。

这三个端点是：

项目级：当您有一些 Maven 软件包且它们不在同一个极狐GitLab群组中时使用。
群组级：当您想要安装来自同一个极狐GitLab群组中许多不同项目的软件包时使用。极狐GitLab不保证群组内的软件包名称的唯一性。您可以有两个项目具有相同的软件包名称和软件包版本。因此，极狐GitLab提供最新的软件包。
实例级：当您有许多软件包在不同的极狐GitLab群组或它们自己的命名空间中时使用。

对于实例级端点，请确保相关部分在您的 Maven 中 pom.xml 看起来像这样：

  <groupId>group-slug.subgroup-slug</groupId>
  <artifactId>project-slug</artifactId>

只有与项目路径相同的软件包 才能通过实例级端点访问。

Project	Package	Instance-level endpoint available
`foo/bar`	`foo/bar/1.0-SNAPSHOT`	Yes
`gitlab-org/gitlab`	`foo/bar/1.0-SNAPSHOT`	No
`gitlab-org/gitlab`	`gitlab-org/gitlab/1.0-SNAPSHOT`	Yes

端点 URL

Endpoint	Endpoint URL for `pom.xml`	Additional information
Project	`https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven`	Replace `gitlab.example.com` with your domain name. Replace `<project_id>` with your project ID, found on your project overview page.
Group	`https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven`	Replace `gitlab.example.com` with your domain name. Replace `<group_id>` with your group ID, found on your group’s homepage.
Instance	`https://gitlab.example.com/api/v4/packages/maven`	Replace `gitlab.example.com` with your domain name.

编辑发布的配置文件

您必须将发布详细信息添加到客户端的配置文件中。

`mvn`

No matter which endpoint you choose, you must have:

A project-specific URL in the distributionManagement section.
A repository and distributionManagement section.

The relevant repository section of your pom.xml in Maven should look like this:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url><your_endpoint_url></url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

The id is what you defined in settings.xml.
The <your_endpoint_url> depends on which endpoint you choose.
Replace gitlab.example.com with your domain name.

`gradle`

To publish a package by using Gradle:

Add the Gradle plugin maven-publish to the
plugins section:

In Groovy DSL:

plugins {
    id 'java'
    id 'maven-publish'
}

In Kotlin DSL:

plugins {
    java
    `maven-publish`
}

Add a publishing section:

In Groovy DSL:

publishing {
    publications {
        library(MavenPublication) {
            from components.java
        }
    }
    repositories {
        maven {
            url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven"
            credentials(HttpHeaderCredentials) {
                name = "REPLACE_WITH_TOKEN_NAME"
                value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
    }
}

In Kotlin DSL:

publishing {
    publications {
        create<MavenPublication>("library") {
            from(components["java"])
        }
    }
    repositories {
        maven {
            url = uri("https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven")
            credentials(HttpHeaderCredentials::class) {
                name = "REPLACE_WITH_TOKEN_NAME"
                value =
                    findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties
            }
            authentication {
                create("header", HttpHeaderAuthentication::class)
            }
        }
    }
}

发布软件包

使用 DeployAtEnd 选项可能导致上传被拒绝，出现
400 bad request {"message":"Validation failed: Name has already been taken"} 错误。更多详情，
请参阅 issue 424238。

在您设置好身份验证并选择发布端点后，将 Maven 软件包发布到您的项目。

`mvn`

使用 Maven 发布软件包：

如果在发布之前保护 Maven 软件包，则软件包将被拒绝并出现 403 Forbidden 错误和 Authorization failed 错误信息。确保在发布时
Maven
软件包未受保护。有关软件包保护规则的更多信息，请参阅如何保护软件包。

安装软件包

要从极狐GitLab软件包仓库中安装软件包，您必须配置远程并进行身份验证
。完成后，您可以从项目、群组或命名空间中安装软件包。

如果多个软件包具有相同的名称和版本，则在安装软件包时，检索最近发布的软件包。

如果没有足够的权限读取最近发布的软件包，则返回 403 Forbidden。

`mvn`

要通过使用 mvn install 安装软件包：

手动将依赖添加到项目的 pom.xml 文件中。要添加之前创建的示例，XML 内容如下：

<dependency>
  <groupId>com.mycompany.mydepartment</groupId>
  <artifactId>my-project</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>

在项目中运行以下命令：

mvn install

消息应显示软件包正在从软件包仓库下载：

Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

`gradle`

要通过使用 gradel 安装软件包：

在 build.gradle 的依赖部分中增加依赖内容：

在 Groovy DSL 中：

dependencies {
    implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT'
}

在 Kotlin DSL 中：

dependencies {
    implementation("com.mycompany.mydepartment:my-project:1.0-SNAPSHOT")
}

在你的项目中，运行如下命令：

gradle install

`sbt`

要通过使用 sbt 安装软件包：

在 build.sbt 中添加内联依赖：

libraryDependencies += "com.mycompany.mydepartment" % "my-project" % "8.4"

在你的项目中，运行如下命令：

sbt update

Maven 软件包的代理下载

Version history

引入于极狐GitLab 17.8。

极狐GitLab Maven 软件包仓库使用远程包含校验和。当您下载文件时，仓库代理文件并在单个请求中将文件及其相关校验和发送给 Maven
客户端。

使用最新的 Maven 客户端使用远程包含校验和：

减少客户端到极狐GitLab Maven 软件包仓库的网络请求数量。
减少极狐GitLab实例的负载。
改善客户端命令执行时间。

由于技术限制，当您使用对象存储时，Maven
软件包仓库会忽略对象存储配置中的代理下载设置。相反，Maven
软件包仓库下载始终启用代理下载。

如果您不使用对象存储，此行为对您的实例没有影响。

Maven 软件包的 CI/CD 集成

您可以使用 CI/CD 自动构建、测试和发布 Maven 软件包。本节中的示例涵盖以下场景：

多模块项目
版本发布
条件发布
与代码质量和安全扫描集成

您可以根据项目需要调整和组合这些示例。

请记得根据项目要求调整 Maven 版本、Java 版本以及其他细节。此外，请确保您已正确配置发布到极狐GitLab软件包仓库所需的凭证和设置。

基本 Maven 软件包构建和发布

此示例配置了构建和发布 Maven 软件包的流水线：

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

具有并行作业的多模块 Maven 项目

对于具有多个模块的大型项目，您可以使用并行作业来加快构建过程：

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  parallel:
    matrix:
      - MODULE: [module1, module2, module3]
  script:
    - mvn $MAVEN_CLI_OPTS test -pl $MODULE

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

使用标签的版本化发布

此示例在推送标签时创建版本化发布：

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish
  - release

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

release:
  stage: release
  script:
    - mvn versions:set -DnewVersion=${CI_COMMIT_TAG}
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_TAG

基于更改的条件发布

此示例仅在某些文件更改时发布软件包：

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - pom.xml
        - src/**/*

与代码质量和安全扫描集成

此示例将代码质量检查和安全扫描集成到流水线中：

default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Code-Quality.gitlab-ci.yml

stages:
  - build
  - test
  - quality
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

code_quality:
  stage: quality

sast:
  stage: quality

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

有用的提示

发布具有相同名称或版本的软件包

当您发布与现有软件包具有相同名称和版本的软件包时，新软件包文件会添加到现有软件包中。您仍然可以使用 UI 或 API
访问和查看现有软件包的旧资产。

要删除旧版软件包，请考虑使用软件包 API 或 UI。

不允许重复的 Maven 软件包

Version history

在极狐GitLab 15.0 中，所需角色从开发者更改为维护者。
在极狐GitLab 17.0 中，所需角色从维护者更改为所有者。

为了防止用户发布重复的 Maven
软件包，您可以使用 GraphQl API 或
UI。

在 UI 中：

在左侧边栏中，选择 搜索或转到 并找到您的群组。
选择 设置 > 软件包和仓库。
在 重复软件包 表的 Maven 行中，关闭 允许重复 切换。
可选。在例外文本框中，输入一个正则表达式以匹配要允许的软件包名称和版本。

如果 允许重复 被打开，您可以在例外文本框中指定不应有重复的软件包名称和版本。

您的更改会自动保存。

请求转发到 Maven Central

Version history

引入于极狐GitLab 15.4，使用名为 maven_central_request_forwarding
的功能标志。默认禁用。
在极狐GitLab 17.0 中，需要的角色从维护者更改为所有者。

此功能的可用性由功能标志控制。有关更多信息，请参阅历史记录。

当软件包仓库中找不到 Maven 软件包时，请求会被转发到 Maven Central。

启用功能标志时，管理员可以在持续集成设置中禁用此行为。

Maven 转发仅限于项目级和群组级端点。实例级端点有命名限制，无法用于不遵循该约定的软件包，并且还会引入供应链样式攻击的安全风险。

`mvn` 的附加配置

使用 mvn 时，有许多方法可以配置您的 Maven 项目，以便从极狐GitLab请求 Maven Central 中的软件包。Maven
仓库以特定顺序查询。默认情况下，Maven Central 通常通过 Super POM 首先检查，因此需要配置极狐GitLab以便在 maven-central 之前查询。

为了确保所有软件包请求都发送到极狐GitLab而不是 Maven Central，您可以通过在 settings.xml 中添加 <mirror> 部分来覆盖
Maven Central 作为中央仓库：

<settings>
  <servers>
    <server>
      <id>central-proxy</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Private-Token</name>
            <value><personal_access_token></value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
  <mirrors>
    <mirror>
      <id>central-proxy</id>
      <name>GitLab proxy of central repo</name>
      <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

使用极狐GitLab CI/CD 创建 Maven 软件包

在您已将存储库配置为使用 Maven 的软件包存储库后，您可以配置极狐GitLab CI/CD 自动构建新软件包。

`mvn`

您可以在默认分支更新时创建新软件包。

创建一个 ci_settings.xml 文件，作为 Maven 的 settings.xml 文件。
使用您在 pom.xml 文件中定义的相同 ID 添加 server 部分。例如，使用 gitlab-maven 作为 ID：

<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Job-Token</name>
            <value>${CI_JOB_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

确保您的 pom.xml 文件包括以下内容。您可以让 Maven
使用预定义的 CI/CD 变量，如本示例所示，或者可以硬编码服务器的主机名和项目的
ID。

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

在您的 .gitlab-ci.yml 文件中添加一个 deploy 作业：

deploy:
  image: maven:3.6-jdk-11
  script:
    - 'mvn deploy -s ci_settings.xml'
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

将这些文件推送到您的存储库。

下次 deploy 作业运行时，它会将 ci_settings.xml 复制到用户的主目录。在此示例中：

用户是 root，因为作业在 Docker 容器中运行。
Maven 使用配置的 CI/CD 变量。

`gradle`

您可以在默认分支更新时创建软件包。

使用 CI 作业令牌在 Gradle 中进行身份验证。
在您的 .gitlab-ci.yml 文件中添加一个 deploy 作业：

deploy:
  image: gradle:6.5-jdk11
  script:
    - 'gradle publish'
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

提交文件到您的存储库。

当流水线成功时，将创建 Maven 软件包。

版本验证

版本字符串使用以下正则表达式进行验证。

\A(?!.*\.\.)[\w+.-]+\z

您可以在这个正则表达式编辑器上试验正则表达式并尝试您的版本字符串。

对快照和发布部署使用不同的设置

要对快照和发布使用不同的 URL 或设置：

在 pom.xml 文件的 <distributionManagement> 部分中定义单独的 <repository> 和 <snapshotRepository> 元素。

有用的 Maven 命令行选项

在使用极狐GitLab CI/CD 执行任务时，您可以使用一些 Maven 命令行选项。

文件传输进度可能会使 CI 日志难以阅读。选项 -ntp,--no-transfer-progress 在 3.6.1 中添加。或者，查看 -B,--batch-mode
或较低级别的日志记录更改。
指定 pom.xml 文件的位置 (-f,--file)：

package:
  script:
    - 'mvn --no-transfer-progress -f helloworld/pom.xml package'

指定用户设置的位置 (-s,--settings) 而不是默认位置。还有一个 -gs,--global-settings 选项：

package:
  script:
    - 'mvn -s settings/ci.xml package'

支持的 CLI 命令

极狐GitLab Maven 仓库支持以下 CLI 命令：

`mvn`

mvn deploy: 将您的软件包发布到软件包仓库。
mvn install: 安装在您的 Maven 项目中指定的软件包。
mvn dependency:get: 安装特定的软件包。

`gradle`

gradle publish: 将您的软件包发布到软件包仓库。
gradle install: 安装在您的 Gradle 项目中指定的软件包。

故障排除

在极狐GitLab中使用 Maven 软件包时，您可能会遇到问题。要解决许多常见问题，请尝试以下步骤：

验证身份验证 - 确保您的身份验证令牌正确且未过期。
检查权限 - 确认您有发布或安装软件包的必要权限。
验证 Maven 设置 - 重新检查您的 settings.xml 文件的正确配置。
查看极狐GitLab CI/CD 日志 - 对于 CI/CD 问题，仔细检查作业日志中的错误消息。
确保正确的端点 URL - 确认您使用的是项目或群组的正确端点 URL。
使用 mvn 命令的 -s 选项 - 始终使用 -s 选项运行 Maven 命令，例如 mvn package -s settings.xml
。没有此选项，身份验证设置不会应用，Maven 可能无法找到软件包。

清除缓存

为了提高性能，客户端缓存与软件包相关的文件。如果遇到问题，请使用以下命令清除缓存：

`mvn`

rm -rf ~/.m2/repository

`gradle`

rm -rf ~/.gradle/caches # Or replace ~/.gradle with your custom GRADLE_USER_HOME

查看网络跟踪日志

如果您在使用 Maven 仓库时遇到问题，您可能需要查看网络跟踪日志。查看网络跟踪日志提供了更多详细的错误消息，而 Maven
客户端默认情况下不包含这些信息。

例如，尝试使用 PAT 令牌在本地运行 mvn deploy 并使用以下选项：

mvn deploy \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient=trace \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace

设置这些选项时，所有网络请求都被记录下来，并生成大量输出。

验证您的 Maven 设置

如果您在 CI/CD 中遇到与 settings.xml 文件相关的问题，请尝试添加一个附加脚本任务或作业以验证有效设置。

帮助插件还可以提供系统属性，包括环境变量：

mvn-settings:
  script:
    - 'mvn help:effective-settings'

package:
  script:
    - 'mvn help:system'
    - 'mvn package'

尝试发布软件包时的 “401 Unauthorized” 错误

这通常表示身份验证问题。检查以下内容：

您的身份验证令牌有效且未过期。
您使用的是正确的令牌类型（个人访问令牌、部署令牌或 CI 作业令牌）。

令牌具有必要的权限（api、read_api 或 read_repository）。
对于 Maven 项目，使用 -s 选项与 mvn 命令（例如，mvn deploy -s settings.xml）。如果没有这个选项，Maven 将不会应用
settings.xml 文件中的认证设置，从而导致未经授权的错误。

“400 Bad Request” 错误，消息为 “Validation failed: Version is invalid”

极狐GitLab 对版本字符串有特定要求。确保您的版本符合以下格式：

^(?!.*\.\.)(?!.*\.$)[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*(\+[0-9A-Za-z-]+)?$

例如，“1.0.0”、“1.0-SNAPSHOT” 和 “1.0.0-alpha” 是有效的，但 “1..0” 或 “1.0.” 是无效的。

`403 Forbidden` 错误，当尝试发布软件包时

403 Forbidden 错误，消息为 Authorization failed 通常表示认证或权限问题。检查以下内容：

您正在使用正确的令牌类型（个人访问令牌、部署令牌或 CI/CD
作业令牌）。有关更多信息，请参阅认证到软件包仓库。

令牌具有必要的权限。只有具有开发者角色或更高权限的用户才能发布软件包。有关更多信息，请参阅极狐GitLab 权限。
*
您正在发布的软件包没有被推送保护规则保护。有关软件包保护规则的更多信息，请参阅如何保护软件包。

发布时出现 “Artifact already exists” 错误

当您尝试发布已存在的软件包版本时，会出现此错误。解决方法：

在发布之前增加您的软件包版本。
如果您使用 SNAPSHOT 版本，请确保在配置中允许 SNAPSHOT 覆盖。

已发布的软件包未在 UI 中出现

如果您刚刚发布了一个软件包，可能需要几分钟才能出现。如果仍然不显示：

验证您是否具有查看软件包的必要权限。
通过查看 CI/CD 日志或 Maven 输出，检查软件包是否成功发布。
确保您正在查看正确的项目或群组。

Maven 仓库依赖冲突

依赖冲突可以通过以下方式解决：

在您的 pom.xml 中明确定义版本。
使用 Maven 的依赖管理部分来控制版本。
使用 <exclusions> 标签排除冲突的传递依赖。

“Unable to find valid certification path to requested target” 错误

这通常是 SSL 证书问题。解决方法：

确保您的 JDK 信任极狐GitLab 服务器的 SSL 证书。
如果使用自签名证书，将其添加到您的 JDK 信任库。
作为最后的手段，您可以在 Maven 设置中禁用 SSL 验证。不建议在生产环境中使用。

“No plugin found for prefix” 流水线错误

这通常意味着 Maven 找不到插件。解决方法：

确保插件在您的 pom.xml 中正确定义。
检查您的 CI/CD 配置是否使用正确的 Maven 设置文件。
验证您的流水线是否有访问所有必要仓库的权限。

软件包仓库中的 Maven 软件包

软件包仓库中的 Maven 软件包

发布到极狐GitLab软件包仓库

身份验证到软件包仓库

编辑客户端配置

自定义 HTTP 头

mvn

gradle

基本 HTTP 身份验证

mvn

gradle

sbt

命名约定

端点 URL

编辑发布的配置文件

mvn

gradle

发布软件包

mvn

安装软件包

mvn

gradle

sbt

Maven 软件包的代理下载

Version history

Maven 软件包的 CI/CD 集成

基本 Maven 软件包构建和发布

具有并行作业的多模块 Maven 项目

使用标签的版本化发布

基于更改的条件发布

与代码质量和安全扫描集成

有用的提示

发布具有相同名称或版本的软件包

不允许重复的 Maven 软件包

Version history

请求转发到 Maven Central

Version history

mvn 的附加配置

使用极狐GitLab CI/CD 创建 Maven 软件包

mvn

gradle

版本验证

对快照和发布部署使用不同的设置

有用的 Maven 命令行选项

支持的 CLI 命令

mvn

gradle

故障排除

清除缓存

mvn

gradle

查看网络跟踪日志

验证您的 Maven 设置

尝试发布软件包时的 “401 Unauthorized” 错误

“400 Bad Request” 错误，消息为 “Validation failed: Version is invalid”

403 Forbidden 错误，当尝试发布软件包时

发布时出现 “Artifact already exists” 错误

已发布的软件包未在 UI 中出现

Maven 仓库依赖冲突

“Unable to find valid certification path to requested target” 错误

“No plugin found for prefix” 流水线错误

`mvn`

`gradle`

`mvn`

`gradle`

`sbt`

`mvn`

`gradle`

`mvn`

`mvn`

`gradle`

`sbt`

`mvn` 的附加配置

`mvn`

`gradle`

`mvn`

`gradle`

`mvn`

`gradle`

`403 Forbidden` 错误，当尝试发布软件包时