Spring Boot打包的tar.gz文件名如何自定义？

Question

**常见技术问题：** 在Spring Boot项目中，使用`spring-boot-maven-plugin`默认打包为`tar.gz`（如`mvn clean package -DskipTests`配合`repackage`目标）时，生成的归档文件名由`-.tar.gz`自动决定，但实际部署常需按环境（如`prod`）、时间戳或Git提交号等动态定制名称（例如`myapp-prod-20240520-abc123.tar.gz`）。开发者尝试在`pom.xml`中配置``仅影响JAR/WAR，对tar.gz无效；直接修改``又会导致主构件冲突或启动脚本失效。此外，`build-image`或Gradle构建场景下命名逻辑更不透明。如何在不破坏Spring Boot内置启动脚本（`bin/myapp`）和分层JAR结构的前提下，安全、可复现地自定义tar.gz输出文件名？需兼顾Maven生命周期兼容性、CI/CD可移植性及运维规范要求。

Answer 1

```html

一、问题本质剖析：为何 spring-boot-maven-plugin 的 tar.gz 命名“不可控”？

Spring Boot 3.x 默认启用 layout=ZIP（即分层 JAR）并支持 repackage 生成可执行 JAR；而 tar.gz 归档是通过 repackage 后的 spring-boot-maven-plugin:build-image 或 repackage + executions 显式触发的“附加产物”。关键矛盾在于：<finalName> 仅作用于主构件（myapp.jar），而 tar.gz 是由插件内部 ArchiveBuilder 根据 project.artifactId、project.version 和 project.packaging 拼接生成，不读取 finalName，亦不响应 <classifier>（除非显式配置为非空）。

二、典型误操作与后果验证（实测案例）

• 错误方式1： 直接设置 <finalName>myapp-prod-20240520</finalName> → JAR 名变更，但 target/*.tar.gz 仍为 myapp-1.0.0.tar.gz
• 错误方式2： 修改 <artifactId> 或 <version> 动态化 → 破坏 Maven 坐标一致性，导致依赖解析失败、Nexus 上传冲突
• 错误方式3： 使用 maven-antrun-plugin 重命名输出文件 → CI/CD 中无法保证构建产物哈希一致性，违反不可变制品原则

三、安全可控的四大解决方案（按推荐强度排序）

方案	适用场景	是否破坏启动脚本	CI/CD 可移植性	实现复杂度
✅ 方案1：Maven 属性 + classifier + repackage execution	Maven 单体构建，需保留原始 JAR 并生成带环境标识的 tar.gz	否（脚本由插件原生生成）	高（仅依赖标准插件）	★☆☆
✅ 方案2：自定义 Assembly 插件 + Spring Boot 分层结构复用	需深度定制目录结构或注入额外资源（如 env.sh）	否（手动复制 bin/ 脚本并保留 shebang）	中（需维护 assembly descriptor）	★★☆

四、方案1 实战代码（Maven 属性驱动的可复现命名）

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>repackage-tar-gz</id>
      <goals><goal>repackage</goal></goals>
      <configuration>
        <classifier>${env}-$(git rev-parse --short HEAD)-${maven.build.timestamp}</classifier>
        <attach>true</attach>
        <layout>ZIP</layout>
      </configuration>
    </execution>
  </executions>
</plugin>

配合 Maven 属性声明：

<properties>
  <maven.build.timestamp.format>yyyyMMdd</maven.build.timestamp.format>
  <env>prod</env>
</properties>

执行：mvn clean package -Denv=staging -DskipTests → 输出：myapp-1.0.0-staging-abc123-20240520.tar.gz

五、Gradle 与 Buildpacks 场景适配说明

Gradle 用户应使用 bootDistZip（Spring Boot 3.2+）并配置：

tasks.named("bootDistZip") {
  archiveClassifier = project.findProperty("env") ?: "default"
  archiveBaseName = provider { "${project.name}-${archiveClassifier.get()}" }
}

对于 build-image，命名由 image-name 控制，但 tar.gz 不生成；若需导出镜像为 tar.gz，应使用 docker save + 自定义命名，而非依赖插件内置归档。

六、CI/CD 可靠性保障关键实践

1. 在流水线中统一注入 GIT_COMMIT、DEPLOY_ENV 等环境变量，避免本地 Maven 属性硬编码
2. 使用 sha256sum target/*.tar.gz 生成制品指纹，写入部署清单（如 manifest.json）
3. 禁止在 target/ 外重命名 —— 所有产物路径必须严格遵循 Maven 标准生命周期

七、完整流程图：安全命名构建链路

flowchart LR
  A[CI 触发] --> B[注入 ENV/GIT/TIMESTAMP]
  B --> C[Maven 构建：clean package]
  C --> D[spring-boot-maven-plugin:repackage]
  D --> E{classifier 非空？}
  E -->|Yes| F[生成 myapp-1.0.0-ENV-COMMIT-TS.tar.gz]
  E -->|No| G[仅生成 myapp-1.0.0.jar]
  F --> H[校验 bin/myapp 脚本完整性]
  H --> I[上传 Nexus/Artifactory]

八、运维规范对齐要点

• 命名格式必须满足：`{artifactId}-{env}-{timestamp}-{gitShortHash}.tar.gz`（符合 SemVer 衍生规范）
• 时间戳采用 UTC 时区，避免时区歧义（通过 <maven.build.timestamp.format> 统一）
• 所有 tar.gz 必须包含 META-INF/MANIFEST.MF 中的 Build-Environment 和 Git-Commit-Id 属性

九、避坑指南：五个高频失效场景

1. 未设 <attach>true</attach> → classifier 不生效，tar.gz 不生成
2. Git 命令在 CI Agent 中无权限执行 → 替换为 ${env.GIT_COMMIT} 环境变量注入
3. 使用 spring-boot-starter-parent 低于 3.1.0 → classifier 对 tar.gz 支持不完整，需升级
4. 多模块项目中未在 packaging=pom 的父 POM 关闭默认 repackage → 子模块重复打包
5. IDE 内置 Maven 执行未传递 -D 参数 → 推荐统一使用 CI 流水线构建，禁用本地打包发布

十、延伸思考：面向不可变基础设施的演进方向

未来可结合 Open Container Initiative（OCI）标准，将 tar.gz 替换为 OCI Image Bundle（.tar），通过 umoci pack 封装分层 JAR + 启动脚本，并利用 cosign 签名确保制品来源可信。此时命名逻辑上收至镜像 registry tag 策略（如 prod/v1.0.0@sha256:...</code>），彻底解耦构建命名与部署语义。

```