nghttp 命令完全指南:nghttp2 项目自带 HTTP/2 客户端实战手册

原创2026-10-12 12:34:161,365 阅读
文章标签:网络通信后端

nghttp 命令完全指南:nghttp2 项目自带 HTTP/2 客户端实战手册

nghttp 是 nghttp2 项目(HTTP/2 C Library and tools)自带的命令行 HTTP/2 客户端。它支持通过 prior knowledge(直连)、HTTP Upgrade 与 ALPN 三种方式建立 HTTP/2 连接,既能作为日常调试工具打印帧级收发细节,也能承担批量请求、资源下载、HAR 性能导出等测试任务。阅读本文后,你将完整掌握 nghttp 的 30 余个命令行选项的语义与用法,并能结合源码理解其底层实现逻辑。

概述:一个可观测的 HTTP/2 客户端

nghttp 与同一工具套件中的 nghttpd(HTTP/2 静态服务器)、nghttpx(HTTP/3/HTTP/2/HTTP/1.1 反向代理)、h2load(负载测试工具)共同构成 nghttp2 的命令行生态。它的独特价值在于帧级可视化:开启 verbose 模式后,屏幕上会逐帧打印 SETTINGS、PRIORITY、HEADERS、DATA、PUSH_PROMISE、GOAWAY 等帧的收发过程,这对于理解 HTTP/2 协议行为、排查服务器实现问题极为有效。

命令行为定义在 doc/nghttp.1.rst,其帮助文本由 help2rst.py 从 src/nghttp.cc 中的 print_help() 自动生成(文件头部注明 "GENERATED by help2rst.py. DO NOT EDIT DIRECTLY"),因此 man page 与程序 --help 输出保持严格一致。整个命令行解析逻辑位于 src/nghttp.cc 的 main() 中,使用 getopt_long() 处理长短选项。

安装与获取

nghttp 随 nghttp2 源码树一起构建。根据 README.rst 的说明,构建 libnghttp2 库只需 C99 编译器;若要编译 nghttp、nghttpd、nghttpx、h2load 等应用,则需要额外的开发包(如 libev、OpenSSL 等)。部分功能有可选依赖:

  • -a, --get-assets 需要 libxml2;
  • -r, --har=<PATH> 需要 libjansson。

若二进制未包含这些依赖,运行时对应选项会被忽略并打印 <a href="https://link.gitcode.com/i/371a2fca82dc3e364598e3ec21390da2" target="_blank">WARNING] 提示(见 [src/nghttp.cc 与 src/nghttp.cc)。

命令语法

nghttp [OPTIONS]... <URI>...
  • <URI>:指定要访问的 URI,可以一次给出多个;
  • 不带任何选项时,nghttp 直接对每个 URI 发起 GET 请求并把响应体写到标准输出。

最简单的用法:

$ nghttp https://nghttp2.org/

三种 HTTP/2 连接方式

从 README.rst 的说明和 src/nghttp.cc 的 need_upgrade() 实现可见,nghttp 支持三种建连方式:

  1. ALPN(TLS):https:// 协议下通过 TLS ALPN 扩展协商 h2,这是默认路径;
  2. HTTP Upgrade(h2c):http:// 协议配合 -u, --upgrade 选项,先发送带 Upgrade: h2c 与 HTTP2-Settings 头的 HTTP/1.1 请求,服务器返回 101 Switching Protocols 后切换为 HTTP/2;
  3. Prior Knowledge(直连):对 http:// 且未指定 -u 时,直接以 HTTP/2 帧发送请求。

-u 在 URI 为 https scheme 时被忽略。若同时使用 -d,Upgrade 请求会改用 OPTIONS 方法发送(见 doc/nghttp.1.rst 中 -u 的说明)。

实战示例:从 verbose 到性能统计

以下示例均取自 README.rst 的 nghttp 章节。

帧级调试输出(-nv)

$ nghttp -nv https://nghttp2.org
[  0.190] Connected
The negotiated protocol: h2
[  0.212] recv SETTINGS frame <length=12, flags=0x00, stream_id=0>
	  (niv=2)
	  [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100]
	  [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535]
[  0.212] send SETTINGS frame <length=12, flags=0x00, stream_id=0>
	  (niv=2)
[  0.212] send HEADERS frame <length=39, flags=0x25, stream_id=13>
	  ; END_STREAM | END_HEADERS | PRIORITY
	  (padlen=0, dep_stream_id=11, weight=16, exclusive=0)
	  ; Open new stream
	  :method: GET
	  :path: /
	  :scheme: https
	  :authority: nghttp2.org
	  accept: */*
	  accept-encoding: gzip, deflate
	  user-agent: nghttp2/1.0.1-DEV
...

可以看到 -n(丢弃下载数据)与 -v(verbose)组合的效果:客户端不向终端输出响应体,只展示帧收发、header 名值对,以及 PUSH_PROMISE、DATA、GOAWAY 等帧的完整细节。-v 可以多次指定以提升输出冗长度(config.verbose 是计数器,见 src/nghttp.cc)。

HTTP Upgrade 流程(-nvu)

$ nghttp -nvu http://nghttp2.org
[  0.011] Connected
[  0.011] HTTP Upgrade request
GET / HTTP/1.1
Host: nghttp2.org
Connection: Upgrade, HTTP2-Settings
Upgrade: h2c
HTTP2-Settings: AAMAAABkAAQAAP__
Accept: */*
User-Agent: nghttp2/1.0.1-DEV

[  0.018] HTTP Upgrade response
HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: h2c

[  0.018] HTTP Upgrade success
...

HTTP2-Settings 头的内容由 populate_settings() 打包 SETTINGS 项后经 base64 编码生成,客户端侧解析 Upgrade 响应使用的是 llhttp(htp_hooks,见 src/nghttp.cc)。

统计信息(-s)与资源抓取(-a)组合

$ nghttp -nas https://nghttp2.org/
***** Statistics *****

Request timing:
  responseEnd: the  time  when  last  byte of  response  was  received
               relative to connectEnd
 requestStart: the time  just before  first byte  of request  was sent
               relative  to connectEnd.   If  '*' is  shown, this  was
               pushed by server.
      process: responseEnd - requestStart
         code: HTTP status code
         size: number  of  bytes  received as  response  body  without
               inflation.
          URI: request URI

sorted by 'complete'

id  responseEnd requestStart  process code size request path
 13    +37.19ms       +280us  36.91ms  200   2K /
  2    +72.65ms *   +36.38ms  36.26ms  200   8K /stylesheets/screen.css
 17    +77.43ms     +38.67ms  38.75ms  200   3K /javascripts/octopress.js
 15    +78.12ms     +38.66ms  39.46ms  200   3K /javascripts/modernizr-2.0.js
  • -a, --get-assets:解析下载页面中的 stylesheet、图片、脚本链接并一并下载,仅下载与链接资源同源的资源;并使用 HTTP/2 依赖优先级对资源排序,优先级从高到低为:html 本身、css、javascript、图片。实现上,客户端用 HtmlParser 解析响应体(Request::init_html_parser()),并通过 resolve_pri()(src/nghttp.cc)将资源类型映射为 RFC 9218 优先级(css/js 为 urgency 0,阻塞型 js 为 urgency 1,图片为 urgency 3 + incremental)。
  • -s, --stat:按完成时间排序打印每个请求的时序(对应 Resource Timing 模型的 responseEnd / requestStart / process),见 print_stats()。* 标记表示该资源是服务器推送(pushed)的,通过 stream_id % 2 == 0 判断。

HAR 导出(-r)

-r, --har=<PATH> 把 HTTP 事务以 HAR 1.2 格式写入指定文件,- 表示输出到 stdout。HAR 记录包含 DNS、连接、等待、接收各阶段耗时以及完整的请求/响应头,由 HttpClient::output_har() 用 libjansson 生成。配合 -a 抓取子资源时,可得到一份完整的页面加载瀑布图数据,便于导入 Chrome DevTools 等工具分析。

选项详解

下面按功能分组逐一讲解全部选项,语义以 doc/nghttp.1.rst 为准,并补充源码层面的实现细节。

输出与调试

选项 说明
-v, --verbose 打印帧收发与 name/value 对的调试信息,可多次指定提升详细程度
-n, --null-out 丢弃下载的数据(响应体不写 stdout)
-O, --remote-name 将下载数据保存到当前目录,文件名从 URI 推导;URI 以 */* 结尾时使用 index.html。文档注明 Not implemented yet
-s, --stat 打印请求统计与时序信息
--color 强制彩色日志输出。默认在 stdout 为 TTY 时自动启用(set_color_output(color || isatty(fileno(stdout))),见 src/nghttp.cc)
--hexdump 以 Canonical hex+ASCII 形式显示入站流量;使用 TLS 时显示解密后的数据(见 on_read())
--version 打印版本信息并退出,输出形如 nghttp nghttp2/<version>(print_version())
-h, --help 打印帮助并退出

连接、超时与窗口控制

选项 说明
-t, --timeout=<DURATION> 每个请求的超时时间,0 表示禁用。默认无超时(config.timeout 初始为 0,见 src/nghttp.h)。超时由 libev 的读写定时器驱动(timeoutcb,见 src/nghttp.cc)
-w, --window-bits=<N> 将流级初始窗口大小设为 2**N-1。默认使用 NGHTTP2_INITIAL_WINDOW_SIZE(65535),通过 SETTINGS_INITIAL_WINDOW_SIZE 发送(populate_settings())。N 取值范围 0, 30](校验见 [src/nghttp.cc)
-W, --connection-window-bits=<N> 将连接级初始窗口大小设为 2**N-1,通过 nghttp2_session_set_local_window_size() 在本地直接调整(src/nghttp.cc)
-M, --peer-max-concurrent-streams=<N> 把远端 SETTINGS_MAX_CONCURRENT_STREAMS 当作已在 SETTINGS 帧中收到该值,默认 100。通过 nghttp2_option_set_peer_max_concurrent_streams() 注入(src/nghttp.cc)
-c, --header-table-size=<SIZE> 指定解码器(客户端)header 表大小。可多次指定:若除最后一次外的取值中存在严格小于最后一个值的最小值,会先在 SETTINGS 帧中发送该最小值、再发送最后一个值,用于模拟多次 header table 大小变更(对应 populate_settings() 的双 SETTINGS_HEADER_TABLE_SIZE 发送)
--encoder-header-table-size=<SIZE> 指定编码器 header 表大小。实际协商值 = min(本选项值, 服务器通过 SETTINGS 声明的上限),通过 nghttp2_option_set_max_deflate_dynamic_table_size() 设置(src/nghttp.cc)
-b, --padding=<N> 每个帧 payload 最多附加 N 字节 padding,0 禁用。实现为 select_padding_callback,实际 padding 为 min(max_payload, frame->hd.length + config.padding)(src/nghttp.cc)

请求定制

选项 说明
-H, --header=<HEADER> 向请求追加一个 header,例如 -H ':method: PUT'。头部名会被转小写;若值为空则报错退出。若追加的是 :scheme 或 :authority/host,会覆盖 URI 中的对应字段(scheme_override / host_override / port_override,见 src/nghttp.cc)
--trailer=<HEADER> 追加 trailer header,例如 --trailer 'foo: bar'。名称不能以 : 开头(伪头禁止用于 trailer);要真正发送 trailer,必须配合 -d 发送请求体。客户端会把 trailer 名汇总进 trailer 头(src/nghttp.cc)
-d, --data=<PATH> 向服务器 POST 指定文件,- 表示从 stdin 读取。此时请求方法自动变为 POST(submit_request()),并默认携带 content-length
-m, --multiply=<N> 每个 URI 请求 N 次。默认同一 URI 不会重复请求,该选项同时解除此限制
-u, --upgrade 对 http URI 执行 HTTP Upgrade 到 HTTP/2;配合 -d 时用 OPTIONS 方法发起
--extpri=<PRI> 设置某 URI 的 RFC 9218 优先级,<PRI> 为 priority 头字段的 wire 格式,如 u=3,i。可多次使用,第 N 个 --extpri 对应命令行第 N 个 URI;若数量少于 URI 数,最后一个值重复填充;未指定时默认 urgency=3、incremental=false(src/nghttp.cc)。解析使用 nghttp2_extpri_parse_priority(),并通过 http2::encode_extpri() 编码进请求的 priority 头(src/nghttp.cc)
--no-content-length 不发送 content-length 头字段(对带 -d 的 POST 请求生效,见 src/nghttp.cc)
--expect-continue 执行 Expect/Continue 握手:先只发头,等待服务器 100 Continue 临时响应后才发送 DATA(最多等待短暂超时)。忽略 -d 之外的组合。实现上先调用 nghttp2_submit_headers() 提交请求头,再启动 ContinueTimer(1 秒定时器,见 src/nghttp.cc 与 src/nghttp.cc)

TLS 与安全性

选项 说明
--cert=<CERT> 指定 PEM 格式的客户端证书文件,通过 SSL_CTX_use_certificate_chain_file() 加载(src/nghttp.cc)
--key=<KEY> 指定 PEM 格式的客户端私钥文件,通过 SSL_CTX_use_PrivateKey_file() 加载(src/nghttp.cc)
-y, --no-verify-peer 抑制服务器证书校验失败的警告。默认客户端会进行对端校验(config.verify_peer 初始为 true,见 src/nghttp.h),连接时通过 SSL_set_verify(ssl, SSL_VERIFY_PEER, verify_cb) 与 X509_VERIFY_PARAM_set1_host() 做主机名校验(src/nghttp.cc)
--ktls 启用 kernel TLS(SSL_OP_ENABLE_KTLS,见 src/nghttp.cc),需 OpenSSL 支持

HTTP/2 特性控制

选项 说明
--continuation 发送超大 header 以测试 CONTINUATION 帧:客户端会追加 6 个各 4KB 的 continuation-test-N 头,强制 HEADERS 帧被拆分为多个 CONTINUATION(src/nghttp.cc)
--no-push 禁用服务器推送:SETTINGS 帧携带 SETTINGS_ENABLE_PUSH=0(populate_settings())
--max-concurrent-streams=<N> 本客户端接受的并发推送流数量,默认 100,通过 SETTINGS_MAX_CONCURRENT_STREAMS 通告给对端(populate_settings())

此外,源码选项表中还保留了几个已废弃的选项:-p, --weight、--no-dep、--no-rfc7540-pri,运行时仅打印 <a href="https://link.gitcode.com/i/dbe677951b1674eaabeec9ee4e7cee9e" target="_blank">WARNING] ... deprecated 提示(见 [src/nghttp.cc、src/nghttp.cc、src/nghttp.cc),不建议再使用。

参数格式约定

  • <SIZE> 参数:整数 + 可选单位(如 10K = 10 × 1024),单位支持 K、M、G(均为 1024 进制)。适用于 -c、--encoder-header-table-size 等。
  • <DURATION> 参数:整数 + 可选单位(如 1s、500ms),单位支持 h、m、s、ms(分别对应小时、分钟、秒、毫秒);省略单位时按秒计。适用于 -t。该解析由 util::parse_duration_with_unit() 完成(见 src/nghttp.cc)。

源码视角:请求如何被构造与发送

理解 nghttp 的关键代码路径位于 submit_request():

  1. 组装伪头与常规头::method(有 data_prd 时为 POST,否则 GET)、:path、:scheme、:authority,以及 priority(extpri 编码)、accept、accept-encoding、user-agent: nghttp2/<version>;
  2. 若启用 --continuation 追加测试大 header;若带 -d 追加 content-length(除非 --no-content-length)与可选的 expect: 100-continue;
  3. 用 stable_partition 把 : 开头的伪头排到最前;
  4. 通过 nghttp2_submit_request2()(普通请求)或 nghttp2_submit_headers()(Expect/Continue 场景)提交给 nghttp2 会话,返回的 stream_id 记录在 Request 中;
  5. 数据经 nghttp2_session_send() 序列化后由底层 socket 写出。

事件循环基于 libev(HttpClient 持有 ev_io 读写观察器与 ev_timer 定时器,见 src/nghttp.h),TLS 握手、普通明文读写、HTTP Upgrade 读写分别由不同的回调函数处理。

相关文档

登录后查看全文
nghttp2