Spring Boot 项目打包成 JAR 并部署运行（实战完整版）

最新推荐文章于 2026-06-20 11:38:02 发布

原创最新推荐文章于 2026-06-20 11:38:02 发布 · 1.1k 阅读

19 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#spring boot #jar #后端

Spring Boot 项目打包成 JAR 并部署运行（实战完整版）

在Spring Boot项目开发完成后（如前文实现的用户管理CRUD项目），下一步就是「打包部署」——将项目打包成可执行JAR包，部署到服务器（或本地）运行，脱离开发工具（IDEA）的依赖，实现项目独立运行。

本文基于前文实战项目（Spring Boot 2.7.x + MyBatis-Plus + 统一返回 + 全局异常 + Swagger），手把手讲解「打包配置→打包操作→本地部署→服务器部署」全流程，重点说明打包注意事项、常见报错排查，以及部署后的验证方法，贴合新手实战，避免踩坑。

核心说明：Spring Boot 内置了 Tomcat 容器（spring-boot-starter-web 依赖已包含），因此打包成 JAR 包后，无需额外部署 Tomcat，可直接通过命令启动运行，简化部署流程（这也是Spring Boot 部署便捷性的核心优势）。

一、打包前准备（关键，避免打包失败）

打包前需完成3项准备工作，确保打包后能正常运行，尤其适配前文包含Swagger、数据库连接、全局异常的项目，避免因配置缺失导致部署失败。

1. 核对项目配置（核心避坑）

重点核对 application.yml（或 application.properties）配置，避免因开发环境配置导致部署后无法运行：

server:
  port: 8081  # 部署后项目端口，确保服务器该端口未被占用
  servlet:
    context-path: /crud-demo  # 项目上下文路径，部署后访问路径需包含（无则省略）

# 数据库配置（部署到服务器时，需改为服务器数据库地址，本地部署可保持不变）
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/test_db?useUnicode=true&characterEncoding=utf-8&serverTimezone=GMT%2B8&useSSL=false
    username: root  # 数据库用户名（服务器部署需改为服务器数据库用户名）
    password: 123456  # 数据库密码（服务器部署需改为服务器数据库密码）
  # 404异常捕获配置（前文添加，保持不变）
  mvc:
    throw-exception-if-no-handler-found: true
  web:
    resources:
      add-mappings: false

# MyBatis-Plus 配置（保持不变）
mybatis-plus:
  mapper-locations: classpath:mapper/**/*.xml  # 若有XML映射文件，确保路径正确
  type-aliases-package: com.example.cruddemo.entity
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl  # 日志配置，部署后可关闭（减少日志冗余）

# Swagger 配置（可选，生产环境建议关闭，避免暴露接口）
knife4j:
  production: false  # true=关闭Swagger，false=开启（开发/测试环境开启，生产环境关闭）

关键提醒：

数据库配置：本地部署可保持 localhost，服务器部署需改为「服务器IP地址」（如 jdbc:mysql://192.168.1.100:3306/test_db），同时确保服务器数据库已创建对应数据库（test_db）、用户名密码正确，且数据库允许外部访问；
端口配置：确保部署环境（本地/服务器）的 8081 端口未被其他程序占用，若占用可修改 port 配置（如 8080、8888）；
Swagger 开关：生产环境部署时，将 knife4j.production 改为 true，关闭Swagger文档，提升系统安全性。

2. 核对 pom.xml 打包配置（必做）

Spring Boot 项目打包成 JAR 包，核心依赖是 spring-boot-maven-plugin，前文项目已引入（若未引入，需手动添加），确保配置正确，否则无法打包成可执行JAR。

<!-- pom.xml 核心配置，确保存在 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.10</version>  # 与前文项目版本一致，避免兼容性问题
    <relativePath/>
</parent>

<!-- 打包类型：JAR 包（默认就是jar，可省略，但建议显式指定） -->
<packaging>jar</packaging>

<!-- 可执行JAR打包插件（核心，必须添加） -->
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <version>2.7.10</version>  # 与Spring Boot版本一致
            <configuration>
                <mainClass>com.example.cruddemo.CrudDemoApplication</mainClass>  # 启动类全路径（关键！）
                <fork>true</fork>  # 允许独立运行，避免依赖开发环境
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal>  # 重打包，生成可执行JAR
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>

    <!-- 可选：指定打包后的JAR包名称（默认是 项目名-版本号.jar，如 crud-demo-0.0.1-SNAPSHOT.jar） -->
    <finalName>crud-demo</finalName>
</build>

关键提醒：

mainClass 配置：必须是项目启动类的全路径（如 com.example.cruddemo.CrudDemoApplication），否则打包后的JAR包无法启动（报错“找不到主类”）；
版本一致性：spring-boot-maven-plugin 的版本必须与 Spring Boot 父依赖版本一致，避免兼容性问题；
finalName 配置：可选，指定后打包后的JAR包名称为 crud-demo.jar（简洁易记），默认名称包含版本号，不影响使用。

3. 清理项目编译文件（可选，避免缓存影响）

若项目之前编译过，可能存在缓存文件，导致打包失败或打包后运行异常，可在IDEA中清理：

点击IDEA顶部「Build」→ 选择「Clean Project」，清理编译后的class文件；
点击「Build」→ 选择「Rebuild Project」，重新编译项目，确保无编译报错。

确认：项目无红色报错，启动类能正常启动（本地运行无问题），再进行打包操作。

二、两种打包方式（IDEA可视化 + Maven命令，任选其一）

Spring Boot 项目打包JAR有两种常用方式，适配不同场景：IDEA可视化操作适合新手（简单直观），Maven命令适合无IDEA环境（如服务器打包），两种方式最终效果一致。

方式1：IDEA可视化打包（新手首选）

步骤简单，无需记忆命令，全程鼠标操作，贴合前文项目的开发环境：

打开IDEA，找到右侧「Maven」工具栏（若未显示，点击顶部「View」→「Tool Windows」→「Maven」调出）；
在Maven工具栏中，展开项目「crud-demo」→「Lifecycle」；
先点击「clean」：清理之前的打包文件（若有），控制台显示「BUILD SUCCESS」即为清理成功；
再点击「package」：开始打包，控制台会打印打包日志，等待1-3分钟（根据项目大小）；
打包成功标志：控制台显示「BUILD SUCCESS」，同时项目根目录下会生成「target」文件夹；
找到JAR包：打开target文件夹，即可看到打包后的JAR包（如 crud-demo.jar，若未配置finalName，则为 crud-demo-0.0.1-SNAPSHOT.jar）。

补充：若点击package时报错，优先查看控制台报错信息（如“找不到主类”“依赖缺失”“编译报错”），对照前文准备工作排查（重点核对mainClass配置、项目无编译报错）。

方式2：Maven命令打包（通用，无IDEA也能使用）

适合无IDEA环境（如服务器部署时直接打包），或习惯使用命令行的开发者，步骤：

打开项目根目录（找到 pom.xml 文件所在的目录，前文项目根目录为 crud-demo）；
打开命令行（Windows：CMD/PowerShell；Mac/Linux：终端），切换到项目根目录（命令：cd 项目路径，如 cd D:\idea-projects\crud-demo）；
执行清理命令：mvn clean，等待执行完成（显示 BUILD SUCCESS）；
执行打包命令：mvn package，命令执行过程中会自动下载缺失的依赖（确保网络通畅）；
打包成功后，同样在 target 文件夹中找到JAR包，与方式1效果一致。

常用命令补充：

mvn clean package -DskipTests：打包时跳过单元测试（若项目有测试用例报错，可使用该命令，避免测试报错影响打包）；
mvn clean install：打包并将JAR包安装到本地Maven仓库（用于多模块项目依赖），前文单模块项目无需使用。

打包后验证（可选，提前规避部署失败）

打包完成后，可先在本地验证JAR包是否能正常启动，避免部署到服务器后才发现问题：

复制 target 文件夹中的 JAR 包（如 crud-demo.jar），粘贴到任意目录（如桌面，便于操作）；
打开命令行，切换到JAR包所在目录（如 cd C:\Users\XXX\Desktop）；
执行启动命令：java -jar crud-demo.jar；
验证启动成功：控制台打印Spring Boot启动日志，无报错，且显示「Started CrudDemoApplication in XX seconds」。

若本地启动成功，说明JAR包无问题，可放心部署到服务器；若启动失败，优先排查配置文件（如数据库连接、端口占用）。

三、部署运行（本地部署 + 服务器部署，实战落地）

部署分为「本地部署」（用于测试JAR包）和「服务器部署」（正式运行），两者核心命令一致，重点讲解服务器部署的细节和避坑点，适配前文实战项目的接口访问。

场景1：本地部署（测试用，简单）

本地部署即直接运行打包后的JAR包，脱离IDEA，步骤与「打包后验证」一致，补充两个实用操作：

1. 普通启动（控制台关闭则项目停止）

命令：java -jar crud-demo.jar

适用场景：临时测试，启动后控制台不能关闭，关闭控制台则项目停止运行。

2. 后台启动（Windows，控制台关闭不影响）

Windows环境下，可通过命令让项目在后台运行，关闭控制台后项目继续运行：

:: 方式1：生成日志文件（推荐，便于排查问题）
java -jar crud-demo.jar > crud-demo.log 2>&1 &

:: 方式2：不生成日志文件
start javaw -jar crud-demo.jar

说明：

方式1：会在JAR包所在目录生成 crud-demo.log 文件，项目运行日志、报错信息都会写入该文件，便于排查问题；
停止项目：打开任务管理器，找到「javaw.exe」进程，结束进程即可。

3. 本地部署验证接口

项目启动成功后，通过浏览器/Swagger/Postman验证接口（与IDEA中一致）：

Swagger文档（开启状态）：http://localhost:8081/crud-demo/doc.html；
查询所有用户接口：http://localhost:8081/crud-demo/api/user/list；
若能正常访问接口、返回统一格式结果，说明本地部署成功。

场景2：服务器部署（正式运行，重点）

服务器部署是项目上线的核心操作，本文以「Linux服务器」为例（最常用），步骤清晰，贴合新手，同时适配前文项目的数据库、接口配置。

前置条件（服务器需准备）

服务器环境：Linux（CentOS 7/8 或 Ubuntu，本文以CentOS 7为例）；
安装JDK：Spring Boot 2.7.x 需 JDK 8 及以上版本（与开发环境JDK版本一致，避免兼容性问题）；
安装MySQL：服务器需安装MySQL（与前文项目数据库版本一致，如MySQL 8.0），并创建对应数据库（test_db）、导入表结构（前文user表）；
开放端口：服务器防火墙开放项目端口（8081）和数据库端口（3306），避免端口被拦截。

补充：JDK、MySQL安装步骤（简化）：

JDK安装：yum install java-1.8.0-openjdk-devel，安装完成后执行 java -version 验证；
MySQL安装：参考MySQL官方文档，安装后启动MySQL服务，创建test_db数据库，授权用户（允许外部访问）；
开放端口（CentOS 7）：
`# 开放8081端口
firewall-cmd --zone=public --add-port=8081/tcp --permanent

开放3306端口（数据库）

firewall-cmd --zone=public --add-port=3306/tcp --permanent

重新加载防火墙配置

firewall-cmd --reload`

服务器部署步骤（全程命令行）

上传JAR包到服务器：
- 方式1：使用Xshell + Xftp（推荐），连接服务器后，通过Xftp将本地的 crud-demo.jar 上传到服务器指定目录（如 /usr/local/springboot ，需提前创建目录：mkdir -p /usr/local/springboot）；
- 方式2：使用scp命令上传（Windows/Mac终端）：scp 本地JAR路径 root@服务器IP:/usr/local/springboot（如 scp C:\Users\XXX\Desktop\crud-demo.jar root@192.168.1.100:/usr/local/springboot）。
连接服务器，切换到JAR包所在目录：
ssh root@服务器IP # 连接服务器（输入密码） cd /usr/local/springboot # 切换到JAR包所在目录
修改JAR包权限（避免无法执行）：
chmod 755 crud-demo.jar # 赋予执行权限（755为通用权限，可执行、可读）
启动项目（Linux后台启动，推荐两种方式）：
方式1：简单后台启动（适合临时测试）nohup java -jar crud-demo.jar > crud-demo.log 2>&1 &
说明：方式2：编写启动脚本（适合正式部署，便于管理）创建启动脚本（start.sh），可快速启动、停止项目，步骤：`# 1. 创建启动脚本
vi start.sh

2. 写入以下内容（复制粘贴，修改JAR包名称和日志路径）

#!/bin/bash

项目JAR包名称

JAR_NAME=crud-demo.jar

日志文件名称

LOG_NAME=crud-demo.log

停止之前运行的项目（避免端口占用）

pid=$(ps -ef | grep $JAR_NAME | grep -v grep | awk '{print $KaTeX parse error: Expected 'EOF', got '}' at position 2: 2}̲') if [ -n "$ pid" ]; then
kill -9 $p i d ec h o " 已停止之前运行的项目， P I D ：$ pid"
fi

后台启动项目，输出日志到指定文件

nohup java -jar $JAR_NAME > $LOG_NAME 2>&1 &

输出启动信息

echo “项目启动中…”
sleep 3
pid=$(ps -ef | grep $JAR_NAME | grep -v grep | awk '{print $KaTeX parse error: Expected 'EOF', got '}' at position 2: 2}̲') if [ -n "$ pid" ]; then
echo “项目启动成功，PID： $p i d ，日志路径：$ (pwd)/ $LOG_NAME" else echo "项目启动失败，请查看日志：$ (pwd)/$LOG_NAME”
fi

3. 保存并退出vi编辑器（按Esc，输入:wq，回车）

4. 赋予脚本执行权限

chmod 755 start.sh

5. 启动项目

./start.sh`

- nohup：表示后台启动，关闭终端（Xshell）后项目继续运行；

- crud-demo.log：日志文件，项目运行日志、报错信息都会写入，便于排查问题；

- 执行命令后，会返回一个进程ID（PID），如 [1] 12345，记录PID便于后续停止项目。

验证项目启动成功：
`# 方式1：查看进程（确认项目是否在运行）
ps -ef | grep crud-demo.jar

方式2：查看日志（确认无报错）

tail -f crud-demo.log # 实时查看日志，按Ctrl+C退出

方式3：访问接口（验证功能）

curl http://localhost:8081/crud-demo/api/user/list # 访问查询所有用户接口`启动成功标志：进程存在、日志无报错、curl命令能返回统一格式的JSON结果（即使无数据，返回{“code”:200,“msg”:“操作成功”,“data”:[]}也属于正常）。

外部访问验证（关键）：
在本地浏览器/Postman中，通过「服务器IP+端口+上下文路径」访问接口，如：http://192.168.1.100:8081/crud-demo/api/user/list若能正常访问，说明服务器部署成功；若无法访问，优先排查服务器防火墙端口是否开放、项目端口是否被占用、数据库连接是否正确。

服务器部署常用操作（必记）

停止项目：
`# 方式1：通过PID停止（已知PID）
kill -9 12345（12345为项目PID）

方式2：通过JAR包名称停止（通用）

pid=$(ps -ef | grep crud-demo.jar | grep -v grep | awk '{print $KaTeX parse error: Expected 'EOF', got '}' at position 2: 2}̲') if [ -n "$ pid" ]; then
kill -9 $pid
echo “项目已停止”
else
echo “项目未在运行”
fi`

重启项目：
`# 方式1：停止后重新启动
kill -9 12345
nohup java -jar crud-demo.jar > crud-demo.log 2>&1 &

方式2：使用启动脚本（推荐）

./start.sh # 脚本会自动停止之前的进程，再重启`

查看日志（排查问题）：
tail -f crud-demo.log # 实时查看日志（最新10行） cat crud-demo.log # 查看全部日志 grep "ERROR" crud-demo.log # 筛选报错信息（快速排查问题）

四、常见报错排查（新手必看，规避90%部署问题）

打包/部署过程中，新手容易遇到各种报错，以下整理高频报错及解决方案，结合前文项目场景，快速排查：

报错1：打包时报错「Could not find or load main class XXX」（找不到主类）

✅ 报错原因：pom.xml 中 spring-boot-maven-plugin 的 mainClass 配置错误（路径写错、启动类名称错误），或未配置mainClass。

✅ 解决方案：核对 mainClass 配置，确保是启动类的全路径（如 com.example.cruddemo.CrudDemoApplication），与项目启动类路径完全一致。

报错2：启动JAR包时报错「Port 8081 was already in use」（端口被占用）

✅ 报错原因：部署环境（本地/服务器）的 8081 端口已被其他程序占用。

✅ 解决方案：
方案1：关闭占用端口的程序（Linux：netstat -tulnp | grep 8081 查看占用进程，再 kill -9 PID 停止）；方案2：修改项目端口（修改 application.yml 的 server.port 配置，如改为 8080，重新打包部署）。

报错3：启动后访问接口，报错「数据库连接失败」（Access denied for user ‘root’@‘localhost’）

✅ 报错原因：application.yml 中数据库配置错误（用户名/密码错误、数据库地址错误、数据库未创建），或服务器数据库不允许外部访问。

✅ 解决方案：
核对数据库用户名、密码，确保正确；服务器部署：将数据库 url 改为服务器IP（如 jdbc:mysql://192.168.1.100:3306/test_db）；确认服务器数据库已创建 test_db 数据库，且 user 表已导入；授权数据库用户：grant all privileges on test_db.* to 'root'@'%' identified by '123456';（允许root用户从任意IP访问test_db数据库）。

报错4：服务器部署后，本地无法访问接口（curl服务器本地能访问，外部不行）

✅ 报错原因：服务器防火墙未开放项目端口（8081），或服务器开启了安全组（如阿里云、腾讯云服务器），未开放对应端口。

✅ 解决方案：
CentOS 7 开放端口：firewall-cmd --zone=public --add-port=8081/tcp --permanent，再 firewall-cmd --reload；云服务器（阿里云/腾讯云）：登录控制台，找到「安全组」，添加 inbound 规则，开放 8081 端口（允许所有IP访问，或指定本地IP）。

报错5：启动JAR包时报错「No qualifying bean of type ‘XXXMapper’ available」（Mapper注入失败）

✅ 报错原因：打包时未将 Mapper 接口扫描到，或启动类未添加 @MapperScan 注解（前文项目已添加，可能打包时缓存导致）。

✅ 解决方案：
确认启动类添加了 @MapperScan(“com.example.cruddemo.mapper”) 注解；重新执行 mvn clean package 打包（清理缓存），再重新部署。

报错6：启动后访问Swagger文档，报404（本地能访问，服务器不能访问）

✅ 报错原因：1. 服务器部署时，Swagger 被关闭（knife4j.production=true）；2. 上下文路径配置错误，访问路径写错。

✅ 解决方案：
测试环境：将 knife4j.production 改为 false，重新打包部署；确认访问路径：http://服务器IP:8081/crud-demo/doc.html（包含上下文路径 /crud-demo）。

五、部署优化建议（贴合企业实战）

日志管理：正式部署时，不要将日志写入JAR包所在目录，建议配置日志输出到专门的日志目录（如 /var/log/springboot），并定期清理日志（避免日志文件过大）；
配置文件分离：将 application.yml 配置文件从JAR包中分离出来，单独放在服务器目录（如 /usr/local/springboot/config），修改配置时无需重新打包，直接修改配置文件并重启项目即可（需修改启动命令：java -jar crud-demo.jar --spring.config.location=/usr/local/springboot/config/application.yml）；
开机自启：正式部署时，配置项目开机自启（避免服务器重启后项目停止），可通过编写systemd服务实现；
生产环境优化：关闭Swagger、关闭SQL日志（log-impl配置注释），减少系统资源占用；使用JDK优化参数启动（如 nohup java -Xms512m -Xmx1024m -jar crud-demo.jar > crud-demo.log 2>&1 &，设置JVM内存）；
备份策略：定期备份JAR包、配置文件和数据库，避免项目故障导致数据丢失。

六、总结

本文基于前文实战项目（Spring Boot + MyBatis-Plus + 统一返回 + 全局异常 + Swagger），完整实现了「打包配置→打包操作→本地部署→服务器部署」全流程，核心要点总结：

打包核心：确保 pom.xml 中 spring-boot-maven-plugin 配置正确（重点是 mainClass），项目无编译报错，配置文件（数据库、端口）适配部署环境；
打包方式：IDEA可视化操作适合新手，Maven命令适合无IDEA环境，两种方式均可，打包后优先本地验证JAR包；
部署核心：本地部署适合测试，服务器部署重点关注JDK、MySQL、防火墙配置，后台启动项目并验证外部访问；
避坑关键：遇到报错优先查看日志，重点排查主类配置、端口占用、数据库连接、防火墙端口开放，结合前文项目场景快速定位问题。

通过本文的步骤，你可以将前文开发的用户管理CRUD项目，成功打包成JAR包并部署到服务器独立运行，完成从「开发」到「部署」的全流程落地。后续可根据项目需求，扩展部署优化（如配置分离、开机自启、集群部署），贴合企业实际开发规范。