Apache JMeter 常用 CLI 命令与工具详解

Apache JMeter 5.6.3 常用 CLI 命令与工具详解，含非 GUI 压测、报告生成、分布式 agent、属性注入、结果解析与内置元件速查，均已实测。

Apache JMeterApache JMeter性能优化Apache基准测试运维2026/10/11

Apache JMeter 常用 CLI 命令与工具详解

目标：详解 Apache JMeter 5.6.3 的非 GUI CLI 命令、常用脚本工具与内置压测元件，覆盖压测运行、报表生成、分布式 agent、属性注入与结果处理。已在 Ubuntu 22.04.5 / JDK17 / JMeter 5.6.3 环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Apache JMeter：5.6.3（安装于 /opt/apache-jmeter）
  • 启动脚本：/opt/apache-jmeter/bin/jmeter
  • agent 脚本：/opt/apache-jmeter/bin/jmeter-server
  • agent 监听端口：1099（默认）
  • 压测目标：http://127.0.0.1:8080/（Python http.server）
  • 结果文件：/opt/apache-jmeter/bin/result.jtl
  • 测试账号：root / q1w2e3r4（如涉及）

二、工具概览

工具/命令用途位置
jmeter（jmeter.sh）主 CLI：版本、GUI、非 GUI 压测、报告生成bin/
jmeter-server分布式压测的 agent 启动脚本bin/
jpsJDK 自带，查看 Java 进程及 JVM 实际参数$JAVA_HOME/bin
jmeter -g从已有 JTL 生成 HTML 报告bin/
GUI 编辑器制作/编辑 .jmx 测试计划（需图形环境）bin/

💡 说明：无图形界面的服务器统一用 CLI（非 GUI）模式，实测主路径为 -n -t -l -e -o 组合。

三、前置条件

  • JMeter 5.6.3 已安装并配置 JAVA_HOME（见《Ubuntu 22.04 安装 Apache JMeter 5.6.3 指南》）。
  • 已准备 .jmx 测试计划，目标服务可达（本文用 127.0.0.1:8080）。

四、CLI 基础命令详解

4.1 查看帮助与用法（jmeter --help）

cd /opt/apache-jmeter/bin
./jmeter --help

回显（节选，格式对齐原作）：

    _    ____   _    ____ _   _ _____       _ __  __ _____ _____ _____ ____
   / \  |  _ \ / \  / ___| | | | ____|     | |  \/  | ____|_   _| ____|  _ \
  / _ \ | |_) / _ \| |   | |_| |  _|    _  | | |\/| |  _|   | | |  _| | |_) |
 / ___ \|  __/ ___ \ |___|  _  | |___  | |_| | |  | | |___  | | | |___|  _ <
/_/   \_\_| /_/   \_\____|_| |_|_____|  \___/|_|  |_|_____| |_| |_____|_| \_\ 5.6.3

Copyright (c) 1999-2024 The Apache Software Foundation

To run Apache JMeter in GUI mode, open a command prompt and type:
jmeter.bat(Windows)/jmeter.sh(Linux) [-p property-file]

To run Apache JMeter in NON_GUI mode:
jmeter.bat(Windows)/jmeter.sh(Linux) -n -t test-file [-p property-file] [-l results-file] [-j log-file]

To run Apache JMeter in NON_GUI mode and generate a report at end :
jmeter.bat(Windows)/jmeter.sh(Linux) -n -t test-file [-p property-file] [-l results-file] [-j log-file] -e -o [Path to output folder]

To generate a Report from existing CSV file:
jmeter.bat(Windows)/jmeter.sh(Linux) -g [csv results file] -o [path to output folder]

To tell Apache JMeter to use a proxy server:
jmeter.bat(Windows)/jmeter.sh(Linux) -H [your.proxy.server] -P [your proxy server port]

To run Apache JMeter in server mode:
jmeter-server.bat(Windows)/jmeter-server(Linux)

4.2 查看版本（jmeter -v）

./jmeter -v

回显（节选）：

    _    ____   _    ____ _   _ _____       _ __  __ _____ _____ _____ ____
   / \  |  _ \ / \  / ___| | | | ____|     | |  \/  | ____|_   _| ____|  _ \
  / _ \ | |_) / _ \| |   | |_| |  _|    _  | | |\/| |  _|   | | |  _| | |_) |
 / ___ \|  __/ ___ \ |___|  _  | |___  | |_| | |  | | |___  | | | |___|  _ <
/_/   \_\_| /_/   \_\____|_| |_|_____|  \___/|_|  |_|_____| |_| |_____|_| \_\ 5.6.3

Copyright (c) 1999-2024 The Apache Software Foundation

4.3 非 GUI 压测并生成报告（jmeter -n -t -l -e -o）

核心命令：运行测试 -> 保存结果 JTL -> 生成 HTML 报告。

cd /opt/apache-jmeter/bin
./jmeter -n -t http_test.jmx -l result.jtl -e -o /opt/report 2>&1

回显（节选，格式化对齐原作）：

Creating summariser <summary>
Created the tree successfully using http_test.jmx
Starting standalone test @ 2026 Oct 11 11:10:40 GMT (1791717040317)
Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445
summary =     10 in 00:00:02 =    4.7/s Avg:    72 Min:     3 Max:   156 Err:     0 (0.00%)
Tidying up ...    @ 2026 Oct 11 11:10:43 GMT (1791717043124)
... end of run

💡 summary 字段含义：10 in 00:00:02（总请求数与用时）、4.7/s（吞吐）、Avg/Min/Max（响应时间均值/最小/最大）、Err: 0 (0.00%)（错误数与错误率）。

4.4 运行监控端口提示

非 GUI 运行时会提示 Waiting for possible Shutdown/StopTestNow/HeapDump/ThreadDump message on port 4445。可用向该端口发送指令控制运行中的测试（见端口工具段）。

4.5 参数速查（常用 CLI 选项）

选项全称含义实测样本
-n--nongui非 GUI 模式-n
-t--testfile测试计划文件-t http_test.jmx
-l--logfile结果 JTL 输出-l result.jtl
-j--jmeterlogfile日志输出-j /var/log/jmeter.log
-e--reportatendofloadtests结束后生成报告-e
-o--reportoutputfolder报告输出目录-o /opt/report
-g--reportonly仅从结果文件生成报告-g result.jtl -o /opt/report2
-H--proxyHostHTTP 代理主机-H proxy.example.com
-P--proxyPortHTTP 代理端口-P 8080
-J<名>=值-Jproperty设置 JMeter 属性-Jsummariser.interval=10
-R--remotestart远程分布式 agent 启动-R 192.168.1.10
-p--propfile指定额外 properties 文件-p user.properties
-s--server以 agent 服务器模式运行-s
-Z--remoteexit结束时关闭远程 agent-Z

五、报告生成工具详解

5.1 运行结束自动生成（-e -o）

-e 与 -o 必须与 -n 连用，在测试结束自动生成仪表盘报告到指定目录（目录需不存在或为空）。

5.2 从已有结果文件生成（jmeter -g）

已有 result.jtl 时，无需重跑测试即可生成 HTML 报告：

cd /opt/apache-jmeter/bin
./jmeter -g result.jtl -o /opt/report2 2>&1

生成结果：

ls /opt/report2

回显：

content    index.html    sbadmin2-1.0.7

报告目录包含 index.html（仪表盘入口）、content/（图表）、statistics.json（汇总 JSON）等。

⚠️ 注意：-g 不能与 -n 同时使用，否则报错 Error: Incompatible options --n/--nongui and -g/--reportonly found.（实测回显）。

5.3 报告统计 JSON 解析

报告目录中的 statistics.json 是机器可读的汇总结果，用 python3 快速查看关键指标：

python3 -c "import json;d=json.load(open('/opt/report/statistics.json'));print(d['Total'])"

输出（节选）：

{'transaction': 'Total', 'sampleCount': 10, 'errorCount': 0, 'errorPct': 0.0, 'meanResTime': 72.6, 'medianResTime': 46.0, 'minResTime': 3.0, 'maxResTime': 156.0, 'throughput': 8.85, 'receivedKBytesPerSec': 1.88}

六、分布式（远程 agent）工具详解

6.1 启动 agent（jmeter-server）

在参与压测的 agent 机器上启动：

cd /opt/apache-jmeter/bin
./jmeter-server

回显（节选）：

Created remote object: UnicastRemoteObject ...
Setting remote server listening on port: 1099
Starting remote server

💡 agent 默认监听 1099（对应 server_port=1099）。

6.2 master 发起远程压测（-R）

在 master 机器上指定 agent 地址发起分布式压测：

cd /opt/apache-jmeter/bin
./jmeter -n -t http_test.jmx -R 192.168.1.10 -l result.jtl -e -o /opt/report

多 agent 用逗号分隔：

./jmeter -n -t http_test.jmx -R 192.168.1.10,192.168.1.11 -l result.jtl

6.3 远程属性与 ad-hoc 结束

配合 -J 向 agent 注入属性，若在 jmeter.properties 中设置了 remote_hosts，用 -Jremote_hosts=... 覆盖。

七、运行中控制与端口工具详解

7.1 Shutdown / Stop 指令（端口 4445）

非 GUI 启动时 JMeter 在（默认）端口 4445 监听控制指令。测试运行中可发送：

shutdown.sh    # 优雅停止（等当前迭代完成）
stoptest.sh    # 立即停止

对应管理脚本位于 bin 下（实测脚本存在）：bin/shutdown.sh、bin/stoptest.sh。

💡 说明：这两个脚本向本机 JMeter 进程的 4445 控制端口发送指令；分布式场景需在 master 上执行。

7.2 JVM 进程查看工具（jps）

jps 是 JDK 自带工具，用于查看 Java 进程及其实际 JVM 参数：

. /etc/profile
jps -v

回显（节选）：

4668 ApacheJMeter.jar ... -Xms256m -Xmx256m -Xmn128m -XX:MaxMetaspaceSize=256m -XX:+UseG1GC ...
4716 Jps -Dapplication.home=/usr/lib/jvm/java-17-openjdk-amd64 -Xms8m ...

用途：确认 JMeter 进程存活、堆参数是否按配置生效（对应《配置参数详解》中 HEAP 修改的验证手段）。

八、常用 CLI 组合示例

8.1 标准压测 + 日志分离

./jmeter -n -t http_test.jmx -l /opt/results/result.jtl -j /var/log/jmeter.log -e -o /opt/results/report

8.2 命令行临时调参

./jmeter -n -t http_test.jmx -Jthreadgroup_num=20 -Jsummariser.interval=5 -l result.jtl

8.3 通过代理访问目标

./jmeter -n -t http_test.jmx -H 192.168.1.1 -P 8080 -l result.jtl

九、注意事项

  • -e/-o 输出目录必须不存在或为空，否则报告生成失败。
  • 非 GUI 模式必须以 -n 开头；-g 单独用于生成报告，勿与 -n 混用。
  • jps -v 是确认 JVM 参数生效的权威手段（ps -ef | grep [j]ava 亦可）。
  • 分布式 agent 的 1099 端口与 JMeter 控制端口（4445）需在防火墙放行。

十、常见问题

Q1：-g 报 Incompatible options --n/--nongui and -g

-g 只用于从已存在的 JTL 生成报告，不能与 -n（运行测试）同时出现；先 -n -t ... -l result.jtl 跑完，再单独 -g result.jtl -o 报告目录。

Q2：summary 上报错率非 0

检查目标服务是否返回非 2xx/3xx、超时或连接失败；结合 result.jtl 中 responseCode 列（如 500/404/000）定位。

Q3：分布式压测执行后 master 卡住无结果

确认 agent jmeter-server 已启动且 -R 地址端口（默认 1099）正确；检查 remote_hosts/防火墙；可加 -Jlog_level.jmeter=DEBUG 提升 agent 日志级别定位。

Q4：报告生成失败，提示输出目录已存在

-o 指定目录必须不存在或为空；先 rm -rf /opt/report 再重跑。

十一、参考链接