作为一名长期与 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. 操作手册：命令构成与参数分类
基本语法
bash
java [JVM-options] -jar jar-file [program-arguments]参数分为三大部分，位置严格：
- JVM 选项 （
-jar之前）：内存、系统属性、GC 策略等。 -jar与 JAR 文件。- 程序参数 （
-jar之后）：传给我们自己的main(String[] args)或 Jar 包框架自定义的选项。
JVM 常用选项
bash
java -Xms512m -Xmx2g -Dspring.profiles.active=prod -Dfile.encoding=UTF-8 -jar app.jar-Xms/-Xmx：初始/最大堆内存。-Dproperty=value：设置系统属性，应用内可通过System.getProperty()获取。-verbose:gc等调试参数。
程序参数（跟在 JAR 后面）
bash
java -jar app.jar --server.port=8080 --spring.application.name=demo这些参数由框架（如 Spring Boot）或自定义代码解析，与 JVM 选项完全隔离。
4. 实战：Jenkins Agent 启动与参数配置
Jenkins 控制器与代理之间支持多种连接方式，其中 JNLP / 直接连接 方式需要代理机器执行一条 java -jar 命令。典型命令如下：
bash
java -jar /home/jenkins/agent.jar \
-url https://cloudci.example.com \
-secret abc123def456 \
-name linux-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：临时设置（单行命令）
bash
TERM=xterm LANG=en_US.UTF-8 java -jar /home/jenkins/agent.jar -url https://cloudci.example.com -workDir /home/jenkins/agent_workspace变量紧贴命令前，仅对当前进程生效。
方法 2：先导出，再执行
bash
export TERM=xterm
export LANG=en_US.UTF-8
java -jar /home/jenkins/agent.jar -url https://cloudci.example.com -workDir /home/jenkins/agent_workspace方法 3：使用 env 命令
bash
/usr/bin/env TERM=dumb LANG=en_US.UTF-8 java -jar /home/jenkins/agent.jar ...特别说明：-workDir 不是环境变量！
-workDir 是 Jenkins Agent 可执行 Jar 定义的一个命令行选项 ，等价于 java -jar agent.jar -workDir /path。如果你希望工作目录可配置，应该采用这种参数传递方式，而非设置环境变量 WORKDIR（虽然某些定制脚本可能会读取环境变量，但官方 agent.jar 使用的是 -workDir 参数）。
如果需要同时传递 JVM 属性和 Agent 参数：
bash
TERM=dumb \
java -Xmx512m -Djava.io.tmpdir=/home/jenkins/tmp \
-jar /home/jenkins/agent.jar \
-url https://cloudci.example.com \
-workDir /home/jenkins/agent_workspace \
-name linux-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 构建可能需要较大元空间：
bash
java -Xms512m -Xmx2g -XX:MaxMetaspaceSize=512m -jar agent.jar ...5.4 日志重定向与后台运行
生产环境中，我们通常将 agent 注册为系统服务（systemd）或使用 nohup 保证后台运行并保留日志：
bash
nohup java -jar /home/jenkins/agent.jar -url ... -workDir ... > agent.log 2>&1 &更好的方式是编写 systemd service 文件，实现开机自启与自动重启。
5.5 安全建议
-
Secret 保护 ：
-secret参数包含连接凭证，不应直接硬编码在脚本中。可通过环境变量传递：bashjava -jar agent.jar -url $JENKINS_URL -secret $JENKINS_SECRET然后通过 CI/CD 的密钥管理注入
JENKINS_SECRET。 -
TLS/SSL ：确保
-url指向 HTTPS 地址，避免中间人攻击。 -
防火墙：如果使用 JNLP 方式，注意控制器的指定端口（通常是随机端口或 50000）需要在网络策略中放行。
5.6 -jar 参数顺序易错点
再次强调：所有传递给 agent.jar 自身的选项（-url、-workDir、-name、-secret 等）必须放在 -jar agent.jar 后面；JVM 选项放在前面。错误示例：
bash
java -jar agent.jar -Xmx512m # 错误：-Xmx512m 会被当成 agent 参数正确：
bash
java -Xmx512m -jar agent.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 的全部参数，欢迎继续交流讨论。