“线上压测发现一个空指针定位到某个工具类里的一行判空逻辑写错了。按常规流程走改代码、跑单测、Maven打包、上传镜像、滚动发布最短也要半小时往上赶上构建机排队那就没准了。但生产问题等不起这时候直接拿现成的 Jar 包做增量更新把出问题的 class 或配置文件替换掉再重新打回去成了很多团队临时救火的选择。增量更新不是个多高深的技术本质就是把 Jar 包当 zip 解压改完文件再按照 Jar 规范压回去。听起来简单实际操作里坑不少改完启动报ClassNotFoundException、Main-Class 丢失、签名校验失败、Spring Boot 项目改了BOOT-INF/classes下的文件却起不来……我前前后后处理过不少这类问题这篇就把整套办法和踩过的坑整理出来给做 Java 维护、需要快速发补丁的同学一个能直接抄作业的参考。”1. 为什么需要增量更新——先拆开 Jar 包看看1.1 Jar 包其实就是一个带清单的 ZIP很多人对 Jar 包有敬畏感觉得它是个“黑盒”其实剥开来看Jar 包就是一个标准的 ZIP 压缩文件只是在META-INF/MANIFEST.MF里多了一份清单文件用来声明入口类、版本号、Class-Path 等信息。JVM 通过这套规范来加载 Jar 包里的 class 文件和资源。所以增量更新的底层逻辑非常简单既然它是 ZIP那就用解压工具打开找到目标文件修改再压缩回去。只要压缩格式合规、目录结构不变、清单文件不损坏JVM 照样能正常加载。这也是为什么我说这活儿“门槛不高但细节多”。一个典型 Jar 包的内部结构大致是这样demo.jar ├── META-INF │ ├── MANIFEST.MF │ └── xxx.SF签名文件签名过的包才有 ├── com │ └── example │ └── Demo.class └── application.properties如果是 Spring Boot 的可执行 Jar结构会稍有不同多出BOOT-INF/classes和BOOT-INF/lib真正项目编译出来的 class 和资源都在BOOT-INF/classes下依赖的三方 Jar 在BOOT-INF/lib下清单里用Start-Class而不是Main-Class来指定启动类。1.2 什么场景适合增量更新我总结下来增量更新最适用的场景就三类。第一类是线上紧急修复。项目已经在生产环境跑着改动很小比如一行空指针判断、一个配置项的值、一个 SQL 语句全量重新打包发包反而风险更大。这时候增量替换单个文件影响面最小回滚也方便——只要备份原 Jar 包就行。第二类是第三方 Jar 包的定制化调整。有时候引用的开源库或者内部公共包有 bug等不到上游发新版本或者新版改动太大不敢升只能自己先改 Jar 包里的 class 或者配置文件来应急。比如修改某个开源组件的日志级别、调整默认超时时间直接在 Jar 包里改配置文件是最快的。第三类是构建环境不可用的情况。比如 CI 服务器挂了、本地网络不行拉不到依赖或者历史项目还在用老旧的构建方式重新构建整套工程成本很高。只要手上有发布出去的 Jar 包就能绕过构建流程直接做补丁。增量更新不适用的情况也有改动涉及大量文件、需要新增或删除依赖、类结构发生重大变更这种老老实实重新打包更稳。1.3 动手前必须确认的三件事我每次做增量更新前都会强迫自己确认三件事缺一不可。第一手头必须有一份原版的 Jar 包备份。别省这个步骤改坏了还能秒回滚。生产环境的 Jar 包路径要提前摸清楚别到时候找不到原包。第二确认要改的文件确实存在于 Jar 包中。用jar tf demo.jar | grep xxx搜一下目标路径确认大小写和路径完全一致。Java 对类名大小写敏感Linux 上文件名也大小写敏感路径写错一个字就会加载失败启动直接ClassNotFoundException。第三确认改动会不会影响其他文件。比如你改了 Spring Boot 的application.yml要考虑其他地方是否引用了被改动的配置项改了 class 文件要考虑它依赖的其他类是否还存在。增量更新只替换单个文件但类之间的依赖关系是全局的这点最容易忽略。2. 解压 Jar 包与定位目标文件2.1 解压工具怎么选解压 Jar 包的工具很多我在不同场景下会用不同的方案。如果是 Linux 服务器上操作优先用系统自带的jar命令和unzip命令。jar是 JDK 自带的工具绝不会出现兼容性问题unzip在绝大多数 Linux 发行版里都预装了没有就yum install unzip或apt install unzip装一下非常快。如果是 Windows 上操作很多维护机是 Windows可以用压缩软件直接打开 Jar 包。WinRAR、7-Zip 都能识别 Jar 格式操作习惯跟解压 zip 一样但有个坑我后面细说别用这些工具直接“原地修改” Jar 包最好先解压到一个临时目录改完再重新打包。因为图形工具修改 ZIP 时可能改变压缩方式或者文件时间戳某些场景下会触发奇怪的校验问题。如果是开发机上IDEA 里其实自带 Jar 包浏览功能直接双击打开 Jar 包就能看到内部结构也可以右键 Extract 解压。不过 IDEA 只能看和提取修改还是得靠外部工具。我个人最稳的标准操作流程是在临时目录下解压 - 修改文件 - 重新打 Jar 包全程用命令行可控性最强。2.2 快速定位目标文件解压之前先用一段小命令把目标文件找出来。假设要改的是com/example/UserService.classjar tf demo.jar | grep UserService如果命中了会输出类似这样的完整路径BOOT-INF/classes/com/example/UserService.class记住这个完整路径后面替换和打包都要用。如果 Jar 包特别大jar tf输出很长可以配合grep多做几次过滤。也可以用unzip -l demo.jar | grep 关键词效果一样。注意在 Windows 上用findstr代替grep。还有一种情况你只知道类名的一部分不完全清楚它在哪个包下。没关系先列出 Jar 包里的所有类再模糊匹配jar tf demo.jar | grep OrderService找到完整路径之后就可以解压了。解压到一个干净的临时目录比如/tmp/demo_updatemkdir -p /tmp/demo_update cd /tmp/demo_update jar xf /path/to/demo.jar这样会把 Jar 包内的所有文件按照原来的目录层级释放到当前目录下。执行完ls看一下META-INF、BOOT-INF、com这些目录应该都在。2.3 只改配置很简单改 class 才是重头戏解压之后分两种改法。第一种改配置文件。比如application.yml、logback.xml、banner.txt这类文本资源直接编辑保存就行。这里有个小提醒注意文件编码。application.yml默认 UTF-8但在一些老项目中可能是 GBK用vim打开后如果中文乱码先执行:set fileencodingutf-8再重新保存。Linux 下查看编码可以用file application.yml。第二种改 class 文件。class 文件是 Java 字节码文本编辑器打开全是乱码要用专门的手段。最常见的手段是反编译成 Java 源码修改后再重新编译成 class。反编译工具我常用两套一是 JD-GUI图形界面操作简单适合快速查看代码逻辑二是javapJDK 自带命令行使用适合查看类结构、方法签名但显示的是 JVM 汇编级别的指令不适合直接阅读逻辑。真要改逻辑我推荐 CFR 或 FernflowerIDEA 内置反编译器它们反编译出来的源码可读性高能直接重新编译。CFR 是独立 Jar 包用法如下java -jar cfr.jar BOOT-INF/classes/com/example/UserService.class --outputdir ./src这会输出一个UserService.java源码文件然后你改源码再用javac重新编译成 classjavac -encoding UTF-8 -cp demo.jar -d ./output ./src/UserService.java这里的-cp demo.jar是为了让编译器能找到类依赖如果你是修改 Spring Boot 项目里的类最好把原来的 Jar 包放进 classpath否则编译时可能报“找不到符号”错误。编译出来的 class 文件在./output/com/example/UserService.class注意目录结构和原来的包路径保持一致。然后把编译好的 class 覆盖回去cp ./output/com/example/UserService.class ./BOOT-INF/classes/com/example/UserService.class反过来如果你的需求只是查看类里某一个常量值不想改逻辑用javap -c直接反汇编看字节码就够了不必走整套反编译流程。3. 修改文件后重新打包的完整流程3.1 打包前先做好备份与清理重新打包之前有几项准备工作必须做顺序也不能乱。先说备份。在原 Jar 包旁边复制一份带时间戳的原包cp demo.jar backup_demo_$(date %Y%m%d_%H%M%S).jar别偷懒增量更新虽然快但一旦打包格式有问题线上服务起不来没有原包就只能干瞪眼。我见过不止一次有人改到一半发现原包已经被覆盖了只能从同事电脑上重新拷那种滋味非常难受。再说清理。解压出来的临时目录里可能残留一些“非标准”文件比如你反编译时生成的.java源文件、编译过程产生的.class文件特别是内部类如果这些文件也被打进 Jar 包轻则体积变大重则引起类冲突。怎么清理看 Jar 包的原始结构只保留原本就存在的目录和文件。比如原来 Jar 包里没有src目录那你修改完一定别把src目录带进去。打包前专门检查一下find . -name *.java -type f -delete rm -rf src output还要检查有没有隐藏文件比如.DS_StoreMac 解压容易产生、*.bak之类的备份文件这些都会被打进 Jar 包。Linux 下可以用find . -name .DS_Store -delete find . -name *.bak -delete另外如果 Jar 包里有签名文件META-INF/*.SF、*.RSA、*.DSA而你改了里面的 class 或资源旧的签名文件最好删掉否则 JVM 在严格模式下会提示签名校验失败。这个点我在第四章详细讲。3.2 jar 命令参数详解与打包步骤待一切清理完毕进入打 Jar 包环节。命令很简单核心就一行jar cfM0 demo_new.jar -C ./unzip_dir .拆开讲一下参数理解参数含义比死记命令重要得多。c表示创建新 Jar 包。f表示要生成的文件名紧跟 Jar 包名。M表示不生成 MANIFEST 清单文件这个参数很重要因为我们解压出来的目录里已经有META-INF/MANIFEST.MF了再让 jar 命令自动生成一个会覆盖掉原来的导致 Main-Class 或 Start-Class 丢失启动直接失败。0是数字零表示不压缩纯存储打包速度最快也方便以后再次修改。-C后面跟目录表示切换到这个目录下面再执行打包注意-C和目录、目录和最后的.之间都不能漏空格。最后那个.表示把当前目录下的所有内容打进去。写成jar cfM0 demo_new.jar -C ./unzip_dir .意思就是进入./unzip_dir把里面所有内容打包成demo_new.jar。如果你想保留 Jar 包源码级压缩可以把0去掉默认就是压缩的jar cfM demo_new.jar -C ./unzip_dir .但我个人偏好加0参数打包快是一方面更关键的是不压缩模式下下次增量更新时 diff 对比和替换文件都更方便。如果你不想用-C也可以先cd到解压目录里再直接执行cd /tmp/demo_update jar cfM0 demo_new.jar .效果一样。补充一种情况如果你要更新的是一个普通 Jar 包不是 Spring Boot 可执行包且原来希望保留清单文件那么前面这条命令已经能处理因为M参数配合明确存在的META-INF/MANIFEST.MF打包后会保留原有清单内容。如果你不小心用了jar cf demo_new.jar ...而没有M新生成的 MANIFEST 只有Manifest-Version和Created-By原来的Main-Class就没了这点必须时刻记住。3.3 打包后的验证流程打完包不能直接扔到线上先做几项验证。验证第一步看清单文件内容有没有丢。用unzip -p demo_new.jar META-INF/MANIFEST.MF查看清单内容unzip -p demo_new.jar META-INF/MANIFEST.MF如果是普通可执行 Jar确认里面有Main-Class如果是 Spring Boot Jar确认有Main-Class和Start-Class并且Main-Class通常是org.springframework.boot.loader.JarLauncher。验证第二步确认目标文件已经被替换。用jar tf demo_new.jar | grep UserService检查类文件存在再对比修改前后文件的内容unzip -p demo_new.jar BOOT-INF/classes/com/example/UserService.class | md5sum拿这个输出跟解压目录里修改后的 class 文件 md5 比对应该完全一致。验证第三步直接尝试启动一次。在本地或者测试环境跑一下java -jar demo_new.jar观察日志是否正常启动。如果是 Spring Boot 项目看到Started Application in x.x seconds基本就稳了。我通常还会再调用一次涉及的接口确认逻辑真的生效。这一步千万别省别指望线上环境给你当测试环境先本地验证能省掉很多尴尬。3.4 脚本化增量更新上面这些步骤手动操作次数多了容易出错我后来写了个小脚本把“解压、替换、验证、打包”串起来分享出来供参考。假设我的场景是原 Jar 包路径为/opt/app/demo.jar工作目录为/tmp/jar_update_ws要替换BOOT-INF/classes/com/example/UserService.class新 class 在当前目录下#!/bin/bash # jar 增量更新脚本 set -e JAR_PATH/opt/app/demo.jar WORK_DIR/tmp/jar_update_ws TARGET_FILEBOOT-INF/classes/com/example/UserService.class NEW_FILE./UserService.class # 备份原包 cp $JAR_PATH $JAR_PATH.bak.$(date %Y%m%d_%H%M%S) # 清理并解压 rm -rf $WORK_DIR mkdir -p $WORK_DIR cd $WORK_DIR jar xf $JAR_PATH # 替换目标文件 cp $NEW_FILE $TARGET_FILE # 重新打包 jar cfM0 demo_new.jar . # 验证清单 unzip -p demo_new.jar META-INF/MANIFEST.MF echo 打包完成请检查 demo_new.jar脚本的set -e很重要任何一步出错就立即退出避免把一个不完整的包发到线上。脚本里的TARGET_FILE和NEW_FILE每次按需改。4. 常见问题与排查技巧实录4.1 Main-Class 丢失或启动直接报 no main manifest attribute这个错误我见得太多了。报错信息长这样no main manifest attribute, in demo_new.jar原因很直接打包时 jar 命令自动生成了新的 MANIFEST.MF把原来带Main-Class的清单覆盖了。为什么会出现因为你打包时没加M参数或者加了M但你解压出来的目录里原本就没有META-INF/MANIFEST.MF比如解压时漏了隐藏目录。排查方法看解压目录里有没有META-INF/MANIFEST.MF这个文件。ls -la META-INF/如果没有说明解压不完整重新解压如果有就检查打包命令里有没有M参数。记住一句话原有的 MANIFEST.MF 是唯一入口信息必须原样保留或者手动指定。万一已经打出了一个坏的 Jar 包也有补救办法不用重新解压打包。用jar ufm命令单独更新清单文件。先写一个包含 Main-Class 的清单文件MANIFEST.MFManifest-Version: 1.0 Main-Class: com.example.Application然后执行jar ufm demo_new.jar MANIFEST.MF注意ufm的m参数是指定清单文件来源和前面cfM0里的M含义不同。执行完再验证一次就能恢复了。4.2 改完 class 文件后报 ClassNotFoundException / NoClassDefFoundError这种情况分两种。第一种是类本身的路径不对。最常见的错误是在 IDEA 里解压修改之后重新打包时目录层级变了。比如原本的类全限定名是com.example.UserService对应的目录结构应该是com/example/UserService.class但有人打包时把整个工程目录打进去了变成了src/main/java/com/example/UserService.class那么 JVM 按照com.example.UserService去加载自然找不到。排查方式用jar tf demo_new.jar搜一下目标类jar tf demo_new.jar | grep UserService看输出的路径是不是com/example/UserService.class。如果前面多了src/main/java/之类的路径就是目录层级错了。第二种是类依赖的其它类缺失。重新编译 class 时你用的 JDK 版本可能和线上环境不一致。比如项目用 JDK 8 编译你本地用 JDK 17 重新编译编译出来的字节码版本是 61对应 Java 17线上 JVM 是 JDK 8加载就直接报UnsupportedClassVersionError这个是另一个很常见的坑。解决方式编译时指定释放版本比如javac --release 8 -encoding UTF-8 -cp demo.jar -d ./output ./src/UserService.java这样生成的 class 字节码版本就是 Java 8 的能在 JDK 8 上跑。还有一个隐蔽问题反编译再编译不是百分百还原。CFR 这类反编译工具对某些语法比如匿名内部类、泛型、lambda可能还原出和原始源码不完全一样的结果重新编译后的类行为可能有细微差异。所以改完 class 之后一定要把相关功能都回归一遍别只验证一个启动流程就完事。4.3 签名 Jar 包的问题如果你的 Jar 包经过 JAR 签名比如某些商业组件、银行 SDK那么增量更新会踩一个大坑。签名是作用在 class 文件和资源文件上的你改了文件内容对应的签名值就对不上了JVM 在启用安全检查时就会报SecurityException: invalid signature file digest for ...。说白了签名包在发布时对每个文件都计算了一个哈希值存到META-INF/*.SF和*.RSA里。你改了文件哈希对不上整个包就会被 JVM 拒之门外。遇到这种包有两个处理办法。第一如果你有权访问签名密钥重新对包签名。但一般做增量更新的场景都是拿不到签名密钥的。第二直接删除META-INF下的签名文件*.SF、*.RSA、*.DSA这样 JVM 会把这个包当作未签名 Jar 包处理不强制校验签名。rm -f META-INF/*.SF META-INF/*.RSA META-INF/*.DSA然后重新打包。这种方式能让包跑起来但会有副作用包的完整性校验没了别人改动包内文件也不会被发现对于安全敏感的场景要慎重。顺带一提Spring Boot 的嵌套 Jar 结构下BOOT-INF/lib中的三方依赖也可能自带签名如果你只是替换BOOT-INF/classes下的文件一般不影响第三方依赖的加载。除非你改了BOOT-INF/lib里的依赖 Jar那就同样要处理签名问题。4.4 中文乱码和编码问题增量更新里最容易让人摔跟头的是配置文件的中文乱码。场景很具体Jar 包里的application.properties用 UTF-8 编码你拿到 Windows 上用记事本打开编辑保存后变成了 GBK 编码启动时读取配置的中文全部乱码。解决办法编辑前先确认原文件编码file application.properties输出如果是UTF-8 Unicode text那就统一用 UTF-8 编辑。Windows 上别用记事本用 Notepad 或 VS Code保存时右下角确认编码是 UTF-8。Linux 上用vim注意写入时也用 UTF-8。如果已经保存成 GBK 了用iconv转换回来iconv -f GBK -t UTF-8 application.properties application_utf8.properties mv application_utf8.properties application.properties另外一个编码相关的坑在日志文件改完重启日志里中文变成“????”多半是日志配置文件里的编码指定有问题优先检查logback.xml或log4j2.xml里的charset设置。4.5 其它零碎但高发的坑再列几个我实际遇到过的低概率但一踩一个准的问题。第一打包时用了通配符或者*把当前目录外的东西打进去了。比如jar cfM0 demo_new.jar *如果当前目录里除了解压内容还有别的临时文件这些文件全会被打进去。谨慎起见尽量用-C 目录 .的写法确保只打目录树下的内容。第二环境变量冲突。在 Linux 上如果你的PATH里同时有多个版本的 JDKjar命令和javac可能来自不同版本导致打的包和 class 字节码版本不一致。执行以下命令确认which jar java -version javac -version最好保证三者同源。如果发现jar来自 JDK 8 而java是 JDK 17那 package 出来的 Jar 可能和预期不符。第三修改了.class文件但忘了同步修改对应的.java源码。这样虽然能跑但给后续维护埋了大坑下一个接手的人反编译看到的逻辑和源码仓库完全对不上。我的习惯是每改一次增量补丁就在 Git 仓库里加一个patch-notes文档记录改了哪个类、为什么改、归档的 class 文件放在哪个目录免得三个月后自己都忘了当初改了啥。第四Windows 下解压出来的文件路径过长报错。老牌压缩工具对 Windows 的长路径支持不好Jar 包里的包名可能非常深解压时提示路径太长无法释放。解决办法是解压到根目录下的短路径比如C:\jar_update或者用 7-Zip 的“解压到...”功能它能自动处理长路径再不行就用“管理员模式”的压缩软件。写在最后增量更新这个操作本质上是个“拆包-改文件-回包”的流程工具门槛很低但坑基本都藏在细节里清单文件别丢、目录层级别乱、JDK 版本要匹配、编码要统一。我处理过好几次线上救火的补丁这套流程用熟了之后从定位到替换再到验证十几分钟就能搞定。最后分享一个小习惯我每次增量更新完都会把原始 Jar 和更新后的 Jar 放在同一个目录下用diff对比一下包内文件清单diff (jar tf original.jar | sort) (jar tf updated.jar | sort)这样一来能直观看到到底改了哪些文件防止多改、漏改。如果你刚接触这个操作不妨也照这个习惯来等实际操作过两三次你对 Jar 包结构的理解会比只看文档要深得多。
