作为一名长期与 Java 和 Jenkins 打交道的工程师，java -jar恐怕是每天执行频率最高的命令之一。它看起来简单，但背后涉及 JAR 规范、JVM 参数传递、程序参数解析以及与 CI/CD 工具的深度集成。本文将从背景知识到操作手册，再聚焦 Jenkins Agent 场景下的“加参数”与“设环境变量”等细节，整理成一篇可随时查阅的技术笔记。
1. 背景知识：java -jar 究竟做了什么？
JAR 文件的本质
JAR（Java Archive）本质上是 ZIP 格式的压缩包，里面打包了编译好的.class文件、资源文件以及一个可选的META-INF/MANIFEST.MF清单文件。要让java -jar直接启动应用，关键在于清单中定义了Main-Class属性：
Manifest-Version: 1.0 Main-Class: com.example.App当执行java -jar app.jar时，JVM 会：
- 读取 JAR 中的
MANIFEST.MF - 定位
Main-Class入口 - 将该 JAR 以及
Class-Path指定的依赖添加到类路径，然后调用main()方法
与 java -cp 的区别
| 方式 | 命令示例 | 特点 |
|---|---|---|
-cp | java -cp app.jar:lib/* com.example.App | 需明确指定主类，适合复杂类路径、多模块 |
-jar | java -jar app.jar | 主类由清单决定，适合独立可执行 JAR（fat jar） |
java -jar是“自包含”部署理念的体现，配合 Spring Boot、Maven Shade 等插件打包的 Fat JAR，成为微服务部署的事实标准。
2. 适用场景
- 本地开发快速启动：跳过 IDE，一条命令验证构建结果。
- 服务器部署微服务：直接
nohup java -jar app.jar &拉起进程。 - 容器化入口：Dockerfile 中的
ENTRYPOINT ["java","-jar","app.jar"]。 - CI/CD 流水线：构建后立即冒烟测试，或启动临时服务。
- Jenkins Agent 接入：从控制器下载
agent.jar，通过java -jar启动代理节点（本文重点）。
3. 操作手册：命令构成与参数分类
基本语法
java[JVM-options]-jarjar-file[program-arguments]参数分为三大部分，位置严格：
- JVM 选项（
-jar之前）：内存、系统属性、GC 策略等。 -jar与 JAR 文件。- 程序参数（
-jar之后）：传给我们自己的main(String[] args)或 Jar 包框架自定义的选项。
JVM 常用选项
java-Xms512m-Xmx2g-Dspring.profiles.active=prod-Dfile.encoding=UTF-8-jarapp.jar-Xms/-Xmx：初始/最大堆内存。-Dproperty=value：设置系统属性，应用内可通过System.getProperty()获取。-verbose:gc等调试参数。
程序参数（跟在 JAR 后面）
java-jarapp.jar--server.port=8080--spring.application.name=demo这些参数由框架（如 Spring Boot）或自定义代码解析，与 JVM 选项完全隔离。
4. 实战：Jenkins Agent 启动与参数配置
Jenkins 控制器与代理之间支持多种连接方式，其中JNLP / 直接连接方式需要代理机器执行一条java -jar命令。典型命令如下：
java-jar/home/jenkins/agent.jar\-urlhttps://cloudci.example.com\-secretabc123def456\-namelinux-agent-01\-workDir/home/jenkins/agent_workspace此时，-url、-secret、-workDir这些是agent.jar 自身的程序参数，必须放在-jar agent.jar之后。千万不要把它们放在-jar之前，否则会被 JVM 当成 JVM 参数而报错。
如何添加环境变量？
Jenkins Agent 运行时可能会依赖一些环境变量，比如终端类型TERM、语言LANG等。环境变量不属于 JVM 参数，也不能作为 Jar 程序参数，而是直接在 Shell 中设定。
方法 1：临时设置（单行命令）
TERM=xtermLANG=en_US.UTF-8java-jar/home/jenkins/agent.jar-urlhttps://cloudci.example.com-workDir/home/jenkins/agent_workspace变量紧贴命令前，仅对当前进程生效。
方法 2：先导出，再执行
exportTERM=xtermexportLANG=en_US.UTF-8java-jar/home/jenkins/agent.jar-urlhttps://cloudci.example.com-workDir/home/jenkins/agent_workspace方法 3：使用 env 命令
/usr/bin/envTERM=dumbLANG=en_US.UTF-8java-jar/home/jenkins/agent.jar...特别说明：-workDir不是环境变量！
-workDir是 Jenkins Agent 可执行 Jar 定义的一个命令行选项，等价于java -jar agent.jar -workDir /path。如果你希望工作目录可配置，应该采用这种参数传递方式，而非设置环境变量WORKDIR（虽然某些定制脚本可能会读取环境变量，但官方agent.jar使用的是-workDir参数）。
如果需要同时传递 JVM 属性和 Agent 参数：
TERM=dumb\java-Xmx512m-Djava.io.tmpdir=/home/jenkins/tmp\-jar/home/jenkins/agent.jar\-urlhttps://cloudci.example.com\-workDir/home/jenkins/agent_workspace\-namelinux-agent-01-Xmx512m、-Djava.io.tmpdir放在-jar之前，属于 JVM 配置。-workDir、-name放在-jar之后，属于 agent 程序参数。TERM设置在命令最前方，是系统环境变量。
5. 常见问题与注意事项
5.1 路径与权限
- 绝对路径至上：JAR 文件、
-workDir都建议使用绝对路径，避免因工作目录不同导致“找不到文件”。 - 运行用户：Jenkins Agent 通常以独立用户（如
jenkins）运行，务必将工作目录属主设置为该用户。 -workDir必须存在且可写，agent.jar 不会自动创建（部分版本会自动创建，但建议预先手动创建并赋权）。
5.2 Java 版本兼容性
控制器和代理要求 Java 版本一致或兼容。agent.jar需要 JRE 8 及以上，如果控制器升级到新版 Jenkins，可能需要更新代理端 Java。通过java -version确认版本。
5.3 内存与性能
Agent 除了运行自身的“代理逻辑”，更多内存消耗在执行构建任务上。根据构建需求预留足够堆内存，例如 Maven 构建可能需要较大元空间：
java-Xms512m-Xmx2g-XX:MaxMetaspaceSize=512m-jaragent.jar...5.4 日志重定向与后台运行
生产环境中，我们通常将 agent 注册为系统服务（systemd）或使用nohup保证后台运行并保留日志：
nohupjava-jar/home/jenkins/agent.jar-url...-workDir...>agent.log2>&1&更好的方式是编写 systemd service 文件，实现开机自启与自动重启。
5.5 安全建议
- Secret 保护：
-secret参数包含连接凭证，不应直接硬编码在脚本中。可通过环境变量传递：
然后通过 CI/CD 的密钥管理注入java-jaragent.jar-url$JENKINS_URL-secret$JENKINS_SECRETJENKINS_SECRET。 - TLS/SSL：确保
-url指向 HTTPS 地址，避免中间人攻击。 - 防火墙：如果使用 JNLP 方式，注意控制器的指定端口（通常是随机端口或 50000）需要在网络策略中放行。
5.6-jar参数顺序易错点
再次强调：所有传递给agent.jar自身的选项（-url、-workDir、-name、-secret等）必须放在-jar agent.jar后面；JVM 选项放在前面。错误示例：
java-jaragent.jar-Xmx512m# 错误：-Xmx512m 会被当成 agent 参数正确：
java-Xmx512m-jaragent.jar5.7-TERM到底是什么？
在实际排查中，有人可能会疑惑是否需要传递-TERM参数。经过验证，agent.jar没有-TERM这个程序参数。这很可能是对环境变量TERM的误写。如果要设置终端类型，请使用前文介绍的环境变量方式。同理，某些构建步骤可能需要PATH、JAVA_HOME等环境变量，也是在java命令前设置或通过/etc/environment、~/.bashrc统一配置。
6. 结语
java -jar是一条承载了 Java 生态“自包含”思想的命令，它让应用分发与启动变得极为简洁。在 Jenkins Agent 场景下，正确理解参数层次（JVM vs 程序）以及环境变量的设置方法，能避免大量部署故障。希望这篇总结能成为你手边的快速参考，不论是微服务部署还是维护庞大的 Jenkins 节点集群，都能游刃有余。
如果想进一步了解如何将 agent 命令封装成 systemd 服务、如何在 Kubernetes 中动态启动 Jenkins Agent，或深入解析agent.jar的全部参数，欢迎继续交流讨论。
