压缩 · XB 现场笔记

gzip、HTTP/2 与 Brotli 需要分别验证

Fri, 28 Jan 2028 00:00:00 +0000

HTTP/2 改变 HTTP 传输分帧和多路复用方式；gzip 与 Brotli 编码的是表示数据。启用 HTTP/2 不会自动压缩响应正文，启用 gzip 也不能证明客户端协商出了 HTTP/2。HTTP/2 的头部压缩又是另一种机制。可靠检查应分别记录协商协议、响应 Content-Encoding、传输正文字节数，以及实际解码后得到的内容，不能用其中一项代替其他结果。

坏掉的样子

发送 Accept-Encoding: gzip, br，然后把结果保存成 .br，并不能证明使用了 Brotli。服务器可能选择 gzip，也可能发送仍被请求接受的原始表示。真实编码由响应头说明。根据请求列表或输出文件名猜测，会导致使用错误解码器，也可能让报告声称获得了实际上根本没有发生的压缩结果。文件名只是本地命名，不是协议证据。

Brotli 支持还属于部署能力，并不是安装 nginx 后自然具备的功能。Brotli 过滤和预压缩文件处理由独立模块提供，需要针对实际二进制与配置确认可用性、构建兼容性。添加不受支持的指令可能让配置验证失败，而客户端声明接受 Brotli 不会替服务器安装功能。检查模块时，应以当前程序行为为准，不能从另一台机器的配置推断。

客户端自动解码会制造另一种测量陷阱。curl --compressed 收到较小编码正文后，可以保存成较大的解码文件。把这个文件大小与原始压缩输出比较，实际比较的是不同对象。反过来，只使用 --http2 却不检查协商结果，也可能把允许的协议回落误当成 HTTP/2 已经成功验证。命令选项表达请求意图，结果字段才说明本次发生了什么。

快速验证

下文集成实验的结果保留自历史运行记录；本次修订没有重新执行该实验，不能将这些记录当成本次环境的新实测。

将脚本保存为 check-h2-coding.py，准备 Docker、Python、OpenSSL 和支持 HTTP/2 的 curl 后运行。记录客户端为带 nghttp2 的 curl 8.7.1，服务器为 Linux arm64 上的 nginx 1.28.0。脚本生成短期本地证书，并通过 --cacert 显式信任该证书，只发布宿主回环端口，不需要连接真实公网服务：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
import gzip,hashlib
payload=(b'{"message":"'+b'HTTP content coding and transport are separate. '*1000+b'"}\n')
with TemporaryDirectory(prefix='xbcatm-local-tls-') as directory:
 root=Path(directory);cert=root/'cert.pem';key=root/'key.pem'
 result=subprocess.run(['openssl','req','-x509','-newkey','ec','-pkeyopt','ec_paramgen_curve:prime256v1',
 '-nodes','-keyout',str(key),'-out',str(cert),'-days','1','-subj','/CN=localhost',
 '-addext','subjectAltName=DNS:localhost,IP:127.0.0.1'],capture_output=True,text=True)
 assert result.returncode==0,result.stderr
 configuration=config('location = /app.json {} location / { return 404; }',
 'gzip on; gzip_types application/json; gzip_vary on; types { application/json json; }')
 configuration=configuration.replace('listen 8080;', 'listen 8080 ssl; http2 on; ssl_certificate /srv/cert.pem; ssl_certificate_key /srv/key.pem;')
 files={'cert.pem':cert.read_bytes(),'key.pem':key.read_bytes(),'app.json':payload,
 'brotli.conf':'events {} http { brotli on; server { listen 8080; } }'}
 with lab(configuration,files) as (proxy,request):
 probe=docker('exec',proxy,'nginx','-t','-c','/srv/brotli.conf',check=False)
 assert probe.returncode!=0 and 'unknown directive "brotli"' in probe.stderr
 results={'brotli_directive_supported':False}
 for name,version,accept,decode in [
 ('h2_gzip','2','gzip, br',False),('h1_gzip','1.1','gzip',False),
 ('h2_br_only','2','br',False),('h2_identity','2','identity',False),
 ('h2_decoded','2','gzip',True)]:
 output=root/(name+'.body');header=root/(name+'.headers')
 args=['curl','--silent','--show-error','--fail','--noproxy','*','--cacert',str(cert),
 '--http2' if version=='2' else '--http1.1','--header','Accept-Encoding: '+accept,
 '--output',str(output),'--dump-header',str(header),'--write-out','%{http_version}\n%{size_download}\n',
 f'https://127.0.0.1:{request.port}/app.json']
 if decode:args.insert(1,'--compressed')
 run=subprocess.run(args,capture_output=True,text=True,timeout=15);assert run.returncode==0,run.stderr
 actual,download=run.stdout.strip().splitlines();assert actual==version,(name,run.stdout)
 headers={k.lower():v.strip() for line in header.read_text().splitlines() if ':' in line for k,v in [line.split(':',1)]}
 body=output.read_bytes();encoded='gzip' in accept
 assert headers.get('content-encoding')==('gzip' if encoded else None)
 assert (gzip.decompress(body) if encoded and not decode else body)==payload
 assert headers['vary']=='Accept-Encoding'
 results[name]={'protocol':actual,'content_encoding':headers.get('content-encoding','identity'),
 'download_body_bytes':int(download),'saved_file_bytes':len(body)}
 assert results['h2_gzip']['download_body_bytes']<len(payload)
 assert results['h2_decoded']['saved_file_bytes']==len(payload)
 rejected={}
 for path in ['/key.pem','/cert.pem','/brotli.conf']:
 run=subprocess.run(['curl','--silent','--show-error','--noproxy','*','--cacert',str(cert),
 '--http2','--output',str(root/'rejected.body'),'--write-out','%{http_code}',
 f'https://127.0.0.1:{request.port}'+path],capture_output=True,text=True,timeout=15)
 assert run.returncode==0 and run.stdout=='404',(path,run.stdout,run.stderr)
 rejected[path]=404
 results['non_asset_statuses']=rejected
 results['original_sha256']=hashlib.sha256(payload).hexdigest()
 print(json.dumps(results,sort_keys=True))

证书的主题备用名称包含回环 IP，因此本地 HTTPS 请求可以同时验证信任和请求身份。实验没有关闭证书校验。路由只允许提供 JSON 资源，请求密钥、证书和探测配置都必须返回 404。临时密钥只存在于可丢弃测试文件和镜像中，不输出密钥内容；结束时清理自己的容器、镜像标签、网络和临时文件。这些设置用于建立可验证的本地 TLS 条件，不代表替生产域名完成了证书部署。

合成 JSON 表示共有 48,015 字节。在实际协商出的 HTTP/2 上，请求同时声明 gzip 和 Brotli，收到 Content-Encoding: gzip，记录到正文为 381 字节。解码能逐字节还原原内容。显式使用 HTTP/1.1 时也得到 gzip。两组结果说明正文编码可以跨这两种已测传输使用，而不是只有选中 HTTP/2 才会发生压缩。

HTTP/2 的 identity 请求得到 48,015 字节未编码正文。只声明 br 的请求在此配置中也得到 identity，因为该请求头仍接受原始表示。实验另外用包含 brotli on 的配置执行检查，并要求 nginx 以未知指令拒绝它。这两个观察共同说明：本次被测配置没有交付 Brotli，不能把客户端声明和服务器实际能力混为一谈。

使用 --compressed 时，curl 仍报告下载正文为 381 字节，但保存文件包含原来的 48,015 字节解码内容。脚本同时核对两种计量和实际内容。下载正文数字不包含其他传输开销，它不是完整抓包，也不是该连接所有 TLS 与 HTTP/2 分帧字节的总量。比较压缩收益时，应让计量边界保持一致。

先确认能力，再比较性能

示例在 TLS 监听上显式开启 HTTP/2，并检查 curl 返回的真实协议值。它在本地提供静态内容，因此不对上游应用采用什么传输协议作结论。反向代理可以与客户端协商一种协议，又用另一种协议连接后端；如果这个区别影响容量或行为，应分别检查两条连接，不能把入口协议直接推广到整个调用链。

部署 Brotli 时，先建立实际模块或预压缩文件交付路径，再要求得到真实 br 响应并成功 Brotli 解码，之后才讨论节省量。这里提供的是负向能力检查，不是 Brotli 性能基准。安装模块或重新构建 nginx 属于另一项配置变更，需要针对兼容性和实际交付重新验证，而不是把未经执行的安装步骤写成已有结果。

最后，要用有代表性的内容和一致计量比较效果。高度重复的测试正文证明编码与解码正确，不提供通用压缩比，也不证明页面一定加速多少。通过 Vary 表达的缓存选择、编码正文字节、解码正确性、CPU 使用和客户端延迟，应作为不同观察记录。协议版本或编码器名称本身，都不足以证明页面变快。

来源

nginx gzip module，响应内容编码及 Vary 配置，已核验 2026-10-15。
nginx HTTP/2 module，HTTP/2 启用与 TLS ALPN 要求，已核验 2026-10-15。
Google ngx_brotli module README，独立 Brotli filter、static 模块及构建要求，已核验 2026-10-15。
RFC 9110 HTTP Semantics，内容编码协商及 identity 的可接受性，已核验 2026-10-15。

显式启用 gzip，再验证协商与解码后的字节

Sun, 29 Aug 2027 00:00:00 +0000

gzip 是响应内容编码：nginx 可以发送压缩表示，由接受该编码的客户端解码。启用它需要 gzip on；gzip_types 扩展有资格压缩的 MIME 类型，却不会单独激活压缩。最终结果取决于响应、请求方能力和实际生效配置。只有压缩后仍能正确还原目标内容，较小正文才有价值，不能把“传输字节变少”与“功能已经正确”直接画等号。

坏掉的样子

在 gzip off 下列出 MIME 类型，不会让响应变成 gzip。另一个常见遗漏是 gzip_vary on。nginx 并不会仅因为发生压缩，就无条件添加 Vary: Accept-Encoding；该行为受对应指令控制。共享缓存需要知道哪些请求头维度影响表示选择，否则不同解码能力的客户端可能拿到不合适的已存响应。压缩成功和缓存选择正确是两个需要分别检查的结果。

最小长度设置的契约比名称暗示的更窄。gzip_min_length 根据响应 Content-Length 字段确定长度，不一定知道未指定长度响应的最终大小。因此，一个很短的动态流式响应仍可能被压缩，而同样短的静态文件会因为已知长度低于阈值而跳过压缩。不能从阈值配置推断所有小响应都不会进入压缩路径。

测量方法也可能误导。解压后输出文件的大小，不是压缩传输正文大小；压缩正文字节也不包含全部 HTTP 分帧、响应头和 TLS 流量。.gz 等文件扩展名本身不能证明实际编码。解释任何表面上的带宽节省之前，都应检查真实 Content-Encoding，并解码核对字节，否则可能只是把两种不同计量对象放在一起比较。

快速验证

下文集成实验的结果保留自历史运行记录；本次修订没有重新执行该实验，不能将这些记录当成本次环境的新实测。

将脚本保存为 check-gzip.py，准备 Python、Docker 和固定镜像后运行。记录环境为 Linux arm64 上的 nginx 1.28.0，以及一个小型 Python 后端。nginx 显式开启三级 gzip，在内置 HTML 资格之外允许 JSON，设置 1,024 字节下限，并显式启用 Vary。服务只发布到宿主回环，实验完成后清理自己的资源：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
import gzip,hashlib
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 self.send_response(200);self.send_header('Content-Type','application/json')
 self.send_header('Connection','close');self.end_headers();self.wfile.write(b'{"ok":true}\n');self.close_connection=True
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
payload=json.dumps({'message':'compressible nginx response '*1000}).encode()
locations='''
location = /disabled.json { gzip off; gzip_types application/json; }
location = /novary.json { gzip_vary off; }
location = /stream { proxy_pass http://backend:8081; }
'''
extra='''
types { application/json json; text/html html; application/octet-stream bin; }
gzip on; gzip_types application/json; gzip_vary on; gzip_min_length 1024; gzip_comp_level 3;
'''
files={name:payload for name in ['large.json','other.bin','page.html','disabled.json','novary.json']};files['tiny.json']=b'{"ok":true}\n'
with lab(config(locations,extra),files,backend) as (_,request):
 results={}
 for encoding in ['gzip','identity','gzip;q=0','br']:
 status,h,b=request('/large.json',headers={'Accept-Encoding':encoding});assert status==200
 if encoding=='gzip':assert h['content-encoding']=='gzip' and gzip.decompress(b)==payload and len(b)<len(payload)
 else:assert 'content-encoding' not in h and b==payload
 assert h['vary']=='Accept-Encoding'
 results[encoding]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b)}
 for path,encoded in [('/tiny.json',False),('/other.bin',False),('/page.html',True),('/disabled.json',False),('/novary.json',True),('/stream',True)]:
 status,h,b=request(path,headers={'Accept-Encoding':'gzip'});assert status==200
 assert (h.get('content-encoding')=='gzip')==encoded,(path,h)
 decoded=gzip.decompress(b) if encoded else b
 assert decoded==(files['tiny.json'] if path=='/stream' else files[path[1:]])
 if path=='/novary.json':assert 'vary' not in h
 results[path]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b),'vary':h.get('vary')}
 results['decoded_sha256']=hashlib.sha256(payload).hexdigest()
 print(json.dumps(results,sort_keys=True))

大型合成 JSON 表示共有 28,015 字节。请求携带 Accept-Encoding: gzip 时，记录到的响应传输正文为 246 字节，Python gzip 解码器能逐字节还原原内容。这份负载刻意包含大量重复文本，用于验证压缩确实发生且内容完整；它的压缩比不能当成生产 JSON、JavaScript 或任意文本的收益预测，更不能直接换算成固定页面加速倍数。

接受 identity、设置 gzip;q=0，或只声明 br 的请求，都得到没有 Content-Encoding 的原始字节。质量值为零表示不接受 gzip；声明 Brotli 也不会在此 nginx 配置中自动安装 Brotli 压缩器，而该请求仍允许 identity。对于具备压缩资格的大响应，包括未压缩变体在内，都能看到 Vary: Accept-Encoding，使选择维度得到明确表达。

同一份合成数据按不具压缩资格的二进制类型提供时保持原样；按 HTML 类型提供时，即使没有在 gzip_types 列出 HTML，仍具备压缩资格。另一个 location 显式设置 gzip off，尽管列出了 JSON，也不会压缩。这些对照把类型资格与总开关区分开来，避免把每次没有 Content-Encoding 都误判为客户端协商失败。

12 字节的静态 JSON 响应因为已知长度低于下限而保持未压缩。后端返回相同的 12 字节，但不提供 Content-Length，而以关闭连接结束响应；nginx 将其压缩为 32 字节。因此，下限并不保证所有微小响应都跳过压缩，这份具体的小负载反而增长了。选择策略时需要考虑长度是否已知，不能只根据最终文件大小反推配置一定如何工作。

最后一个 location 保持 gzip 开启，却关闭 gzip_vary。正文仍以 gzip 到达，但没有 Vary 字段。这个对照让缺失缓存选择维度的问题可以直接观察，无需先让真实共享缓存错误交付一次内容。实验核对的是响应头策略；部署后的缓存是否按该维度正确选择，还应通过实际缓存路径验证。

用有代表性的响应调整策略

选择实际字节适合压缩的内容类型。已经压缩的媒体或归档通常很难从再次编码中获益，而重复文本可能显著缩小。这里的字节计数实验没有测量 CPU 成本。忙碌服务选择压缩等级前，应比较代表性大小、不同设置、服务器利用率和客户端延迟，不应把合成数据的高压缩率当成通用容量结论。

经过代理时，响应元数据也要保持准确。Content-Encoding 告诉接收方怎样解码表示，Vary 告诉缓存哪些请求字段影响选择。如果应用已经发送编码响应，应单独审阅那条路径，而不是给未编码字节补一个会误导客户端的头。最终有判定力的验证始终是：协商结果正确、响应头与正文一致，并且实际解码后逐字节匹配目标内容。

来源

nginx gzip module，启用 gzip、MIME 资格、Content-Length 阈值与 Vary，已核验 2026-10-15。
RFC 9110 HTTP Semantics，Accept-Encoding、Content-Encoding 与表示选择，已核验 2026-10-15。

压缩协商本质上仍是内容协商

Tue, 21 Jul 2026 00:00:00 +0000

HTTP 压缩选择的是施加了内容编码的表示，不是一种新的媒体类型。经过 gzip 的文本，解压后仍然是文本。因此有效验证需要回答三个问题：编码是否可接受、传输内容是否变小、解码后是否恢复了原本要提供的字节。配置里勾选了压缩，或者接口返回成功状态，都不能同时证明这三件事。

区分缺失、排除与偏好

根据 RFC 9110，Accept-Encoding 缺失时，任何内容编码都被认为可接受；显式空值则表示不希望使用内容编码。identity 代表没有内容编码，通常默认可接受，除非被 identity;q=0 或适用的 *;q=0 排除。通配符还可以让没有逐个列出的编码成为可接受候选，因此“只能发送客户端单独点名的编码”并不是完整规则。

质量值为零表示不可接受，正数则用于表达可接受编码之间的偏好。但服务器还必须具有对应编码器，并判断内容是否适合压缩。客户端偏好 Brotli，不会替服务器安装 Brotli。如果 identity 仍然可接受，未编码响应可能就是合理结果。即使所有候选都被排除，也不能假定每个服务器都会实施严格的 406 策略，因为 RFC 9110 还允许忽略协商偏好。应用需要哪种行为，必须单独验证。

坏掉的样子

代理压缩正文却漏写 Content-Encoding，客户端就可能把压缩字节当成文本；反过来，代理解压后保留原字段，则可能诱发第二次解码。Content-Length 如果存在，描述的是编码后内容的字节数，不是原始长度。流式压缩不一定提前知道最终大小，可以不发送这个字段，而不是继续沿用旧长度。消息分帧与内容编码是不同层次，不能混为一谈。

当 Accept-Encoding 参与可复用变体的选择时，Vary 需要描述这个维度，未编码响应也不能漏掉。否则，缓存中的 gzip 副本可能送给明确排除了 gzip 的客户端。缓存新鲜度和存储资格仍是另外的问题。即使选择正确，也不保证压缩值得：很小的正文存在额外开销，已经压缩过的媒体通常收益有限。应测代表性内容和处理成本，而不是声称所有文本都有一个固定的压缩百分比。

快速验证

准备 Python 3.11 或更新版本、支持 gzip 的 curl，以及 PATH 中的 Caddy 2.11.4。从官方发布页取得适合系统的二进制，并核对公布的校验和后再运行。程序使用回环端口 18765；若该端口占用，应在代码里换成空闲端口。它关闭管理端点、自动 HTTPS 和配置持久化，只清理自己创建的临时文件与子进程，不接触正在运行的网站服务。

import gzip
import os
import shutil
import socket
import subprocess
import tempfile
import time
from http.client import HTTPConnection, HTTPException
from pathlib import Path

caddy = shutil.which("caddy")
if caddy is None:
 raise SystemExit("Put Caddy 2.11.4 on PATH first")
print(subprocess.check_output([caddy, "version"], text=True).split()[0])
port = 18765
with socket.socket() as probe:
 probe.bind(("127.0.0.1", port))


def get(name, accept):
 connection = HTTPConnection("127.0.0.1", port, timeout=2)
 try:
 connection.putrequest("GET", "/" + name, skip_accept_encoding=True)
 if accept is not None:
 connection.putheader("Accept-Encoding", accept)
 connection.endheaders()
 response = connection.getresponse()
 body = response.read()
 assert response.status == 200
 return response.headers, body
 finally:
 connection.close()


with tempfile.TemporaryDirectory(prefix="compression-lab-") as temporary:
 directory = Path(temporary)
 site = directory / "site"
 site.mkdir()
 plain = b"HTTP content coding changes bytes, not the media type.\n" * 200
 (site / "large.txt").write_bytes(plain)
 (site / "tiny.txt").write_bytes(b"small\n")
 config = directory / "Caddyfile"
 config.write_text(
 "{\n admin off\n auto_https off\n persist_config off\n}\n"
 f"http://127.0.0.1:{port} {{\n root * {site}\n encode gzip\n file_server\n}}\n"
 )
 environment = dict(os.environ, XDG_DATA_HOME=str(directory / "data"),
 XDG_CONFIG_HOME=str(directory / "config"))
 with (directory / "server.log").open("w+") as log:
 process = subprocess.Popen(
 [caddy, "run", "--config", str(config), "--adapter", "caddyfile"],
 stdout=log, stderr=log, env=environment,
 )
 try:
 deadline = time.monotonic() + 5
 while True:
 if process.poll() is not None or time.monotonic() > deadline:
 log.seek(0)
 raise RuntimeError(log.read() or "Caddy startup timed out")
 try:
 _, body = get("large.txt", "identity")
 assert body == plain
 break
 except (OSError, HTTPException):
 time.sleep(0.05)
 cases = [(None, None), ("", None), ("gzip", "gzip"),
 ("gzip;q=0", None), ("br", None),
 ("identity;q=0, gzip;q=1", "gzip"), ("*;q=0", None)]
 for accept, expected in cases:
 headers, body = get("large.txt", accept)
 coding = headers.get("Content-Encoding")
 assert coding == expected
 assert headers.get_content_type() == "text/plain"
 assert headers["Vary"] == "Accept-Encoding"
 decoded = gzip.decompress(body) if coding == "gzip" else body
 assert decoded == plain
 if coding == "gzip":
 assert len(body) < len(plain)
 if headers.get("Content-Length") is not None:
 assert int(headers["Content-Length"]) == len(body)
 print(repr(accept), coding, len(body), headers.get("Vary"))
 headers, body = get("tiny.txt", "gzip")
 assert body == b"small\n" and headers.get("Content-Encoding") is None
 print("tiny", len(body), headers.get("Vary"))
 decoded = subprocess.check_output([
 "curl", "-q", "--noproxy", "*", "-fsS", "--max-time", "3",
 "--compressed", "-H", "Accept-Encoding: gzip",
 f"http://127.0.0.1:{port}/large.txt",
 ])
 assert decoded == plain
 print("curl decoded:", len(decoded))
 finally:
 process.terminate()
 try:
 process.wait(timeout=5)
 except subprocess.TimeoutExpired:
 process.kill()
 process.wait(timeout=5)

重复构造的样本共有一万一千字节。在本次验证中，gzip 内容为一百二十二字节，解压后完整恢复原始正文。比较不包括 HTTP 头与传输分帧，因此不是带宽或延迟基准。skip_accept_encoding=True 很关键：Python 否则会自动添加 identity 偏好，把本来想验证的“字段缺失”变成了另一个请求条件，造成实验输入与口头描述不一致。

本配置对字段缺失、空值、排除 gzip 和不受支持的 Brotli 请求都返回未编码正文。缺失允许压缩，但不强制服务器必须压缩。两个接受 gzip 的案例则收到 gzip 表示。六字节小文件即使接受 gzip 也不压缩，因为它低于 Caddy 默认的五百一十二字节门槛。大文件测试同时检查 Vary、媒体类型和解码后的字节完全相同，不是只确认某个头里出现了 gzip。

*;q=0 在这份经过验证的 Caddy 配置里仍得到 200 与未编码正文，尽管 identity 已经被排除。这说明不能从“启用了压缩”推导出严格拒绝契约。程序断言是在记录实现行为，并不是认定客户端的排除条件已被满足。若应用要求没有可接受表示就拒绝，应在负责该契约的端点验证或实现相应策略，不要依赖一个未经测试的配置想象。

最后，curl 的 --compressed 返回已经解码的一万一千字节。单独保存的响应头仍可能包含 Content-Encoding，不能因此再把输出解压一次。实验显式绕过 curl 配置文件和代理，避免本机设置影响回环请求。生产验收仍需沿真实代理或 CDN 重复选择与字节检查，因为中间层可能新增、移除或重复施加压缩。局部压缩率正常，不代表公网收到的表示也正确。

来源

RFC 9110：主动协商，无法满足偏好时可以返回 406 或忽略该协商字段，已核验 2026-10-15。
RFC 9110：Accept-Encoding，字段缺失、identity、排除条件与内容编码，已核验 2026-09-07。
Caddy encode 指令，编码选择与默认大小门槛，已核验 2026-09-07。
Caddy 2.11.4 发布，实际验证的二进制与公布的校验和，已核验 2026-09-07。
curl 压缩模式，自动解压及保存响应头不变的行为，已核验 2026-09-07。

压缩 · XB 现场笔记

gzip、HTTP/2 与 Brotli 需要分别验证

坏掉的样子

快速验证

先确认能力，再比较性能

延伸阅读

来源

显式启用 gzip，再验证协商与解码后的字节

坏掉的样子

快速验证

用有代表性的响应调整策略

延伸阅读

来源

压缩协商本质上仍是内容协商

区分缺失、排除与偏好

坏掉的样子

快速验证

延伸阅读

来源