Spring Boot 项目标准化部署打包实战

Spring Boot 项目标准化部署打包实战一、目标将 Spring Boot 项目打包为开箱即用的生产环境部署包。用户解压后只需修改配置文件运行启动脚本即可启动服务。最终目录结构your-app/ ├── bin/ │ ├── startup.sh # Linux 启动脚本 │ └── startup.cmd # Windows 启动脚本 ├── conf/ │ └── application.yml # 外部配置文件解耦方便运维修改 ├── lib/ │ ├── your-app.jar # 主程序 JAR │ └── *.jar # 依赖 JAR ├── logs/ # 日志目录自动创建 └── LICENSE设计理念配置与程序分离conf/application.yml独立于 JAR运维人员无需接触代码一键启动封装好 JVM 参数和 classpath 的启动脚本降低操作门槛热迭代后续升级只需替换lib/your-app.jar配置、依赖、脚本全不动二、环境要求组件版本要求JDK8Maven3.6Spring Boot2.x三、Maven 配置3.1 pom.xml 插件配置buildplugins!-- 1. 依赖拷贝插件将所有依赖 JAR 拷贝到 target/lib/ --plugingroupIdorg.apache.maven.plugins/groupIdartifactIdmaven-dependency-plugin/artifactIdexecutionsexecutionidcopy-dependencies/idphasepackage/phasegoalsgoalcopy-dependencies/goal/goalsconfigurationoutputDirectory${project.build.directory}/lib/outputDirectory/configuration/execution/executions/plugin!-- 2. Spring Boot 打包插件生成可执行 JAR --plugingroupIdorg.springframework.boot/groupIdartifactIdspring-boot-maven-plugin/artifactIdversion2.1.18.RELEASE/versionconfigurationmainClasscom.your.MainApplication/mainClass/configurationexecutionsexecutiongoalsgoalrepackage/goal/goals/execution/executions/plugin!-- 3. Assembly 打包插件按自定义结构打包为 tar.gz --plugingroupIdorg.apache.maven.plugins/groupIdartifactIdmaven-assembly-plugin/artifactIdconfigurationdescriptorsdescriptorsrc/assembly/package.xml/descriptor/descriptors/configurationexecutionsexecutionidmake-assembly/idphasepackage/phasegoalsgoalsingle/goal/goals/execution/executions/plugin/plugins/build重要提示如果使用JDK 8spring-boot-maven-plugin必须锁定版本为2.1.18.RELEASE否则会报class file version 61.0错误高版本插件编译的 class 与 JDK 8 不兼容。四、Assembly 打包配置创建src/assembly/package.xmlassemblyxmlnshttp://maven.apache.org/ASSEMBLY/2.0.0xmlns:xsihttp://www.w3.org/2001/XMLSchema-instancexsi:schemaLocationhttp://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsdidrelease/idformatsformattar.gz/format/formatsincludeBaseDirectorytrue/includeBaseDirectorybaseDirectoryyour-app/baseDirectoryfileSets!-- 启动脚本权限 755 --fileSetdirectorysrc/assembly/bin/directoryoutputDirectorybin/outputDirectoryfileMode0755/fileMode/fileSet!-- 配置文件 --fileSetdirectorysrc/main/resources/directoryoutputDirectoryconf/outputDirectory/fileSet/fileSets!-- 依赖 JAR 全部打入 lib/ --dependencySetsdependencySetoutputDirectorylib/outputDirectoryincludesinclude*:jar/include/includes/dependencySet/dependencySets/assembly各节点说明节点作用idrelease/id最终产物名后缀your-app-release.tar.gzformattar.gz/format打包格式跨平台通用baseDirectory解压后的根目录名fileMode0755/fileModeLinux 下脚本可执行权限五、启动脚本5.1 Windows 启动脚本src/assembly/bin/startup.cmdecho off set DIR%~dp0.. cd %DIR% if not exist %DIR%\logs mkdir %DIR%\logs set JAVA_OPTS-Xms256m -Xmx1024m -Dfile.encodingUTF-8 java %JAVA_OPTS% ^ -Dloader.path%DIR%\lib ^ -Dspring.config.locationfile:%DIR%\conf\application.yml ^ -jar %DIR%\lib\your-app.jar ^ %DIR%\logs\app.log 21 echo Started. pause说明%~dp0是批处理脚本自身所在目录%~dp0..回到项目根目录。^是 Windows 命令行续行符。5.2 Linux 启动脚本src/assembly/bin/startup.sh#!/bin/bash# 获取脚本所在目录的上级目录即项目根目录DIR$(cd $(dirname$0)/..pwd) cd $DIR # 创建日志目录 mkdir -p logs # JVM 参数 JAVA_OPTS-Xms256m-Xmx1024m-Dfile.encodingUTF-8 # 后台启动日志输出到 logs/app.log nohup java$JAVA_OPTS\ -Dloader.path$DIR/lib \ -Dspring.config.locationfile:$DIR/conf/application.yml \ -jar $DIR/lib/your-app.jar \ $DIR/logs/app.log 21 echo Started. PID:$!脚本解读配置项说明-Xms256m -Xmx1024m初始堆 256M最大堆 1G按实际调整-Dloader.path指定依赖 JAR 加载路径配合PropertiesLauncher使用-Dspring.config.location指定外部配置文件路径优先级高于 JAR 内的配置nohup ... 后台运行终端关闭不中断$!最后启动的后台进程 PID六、打包与部署6.1 打包mvn clean package执行后在target/目录下生成your-app-release.tar.gz。6.2 部署# 1. 解压tar-xzfyour-app-release.tar.gz# 2. 修改配置vimyour-app/conf/application.yml# 3. 启动cdyour-app/bin# Linuxshstartup.sh# Windowsstartup.cmd部署只需三步解压 → 改配置 → 启动。七、迭代更新后续升级只需替换一个 JAR 文件流程如下本地改完代码执行mvn clean package将新的your-app.jar上传到服务器替换lib/下的旧 JAR重启服务配置、依赖、启动脚本全部不用动真正实现热迭代。八、常见问题8.1 端口被占用# Windows查看端口占用netstat-ano|findstr :8080# Windows杀掉进程taskkill /pid 进程ID /f# Linux查看端口占用lsof-i:8080# Linux杀掉进程kill-9进程ID8.2 找不到主类检查pom.xml中spring-boot-maven-plugin的mainClass配置是否正确需指向带SpringBootApplication注解的主类。8.3 JAR 中没有主清单属性确保spring-boot-maven-plugin配置了goalrepackage/goal只有repackage才会生成MANIFEST.MF中的Main-Class。8.4class file version 61.0错误原因高版本 Spring Boot Maven Plugin3.x编译的 class 需要 JDK 17与 JDK 8 不兼容。解决JDK 8 环境下将spring-boot-maven-plugin版本降级到2.1.18.RELEASE。8.5 配置文件找不到启动参数中的路径建议使用绝对路径%DIR%/$DIR避免因工作目录不同导致相对路径解析失败。脚本中已通过DIR变量实现了此逻辑。8.6 日志文件不输出确认logs/目录有写入权限检查启动用户是否有当前目录的写权限nohup输出会先写入nohup.out确认重定向符号正确九、总结通过Maven Assembly 插件 外部配置文件 启动脚本的组合可以将 Spring Boot 项目打包为标准的生产环境部署包。维度收益部署成本解压 → 改配置 → 启动三步完成运维友好配置外置无需懂 Java 也能改配置、看日志迭代效率升级只换一个 JAR秒级完成跨平台Windows / Linux 均有对应启动脚本标准化统一的目录结构不同项目一致降低认知成本延伸思考在生产环境中可以进一步加入-XX:HeapDumpOnOutOfMemoryError、GC 日志、JMX 监控等 JVM 参数结合 SystemdLinux或 NSSMWindows实现服务托管和自动重启。