指令速查

按使用频率排的，不是按字母序——字母序查起来太慢。

路由与响应

指令	作用	最小示例
reverse_proxy	反向代理	reverse_proxy localhost:3000
file_server	静态文件服务	file_server
respond	直接返回固定响应	respond "hi" 200
root	设置站点根目录	root * /var/www
try_files	存在性检查 + 回退	try_files {path} /index.html
redir	跳转	redir https://example.com{uri} 301
rewrite	改写路径	rewrite /old /new
uri	操作 URI	uri strip_prefix /api
route / handle	分支与排序	见下方

请求处理

指令	作用
encode gzip zstd br	响应压缩
request_body	限制请求体大小
method	限定 HTTP 方法
header	增删改响应头
request_header	操作请求头
basic_auth	HTTP Basic 认证
basicauth（旧名）	同上，不推荐
remote_ip	按来源 IP 放行/拦截

TLS

指令	作用
tls [email]	内联配置证书，如 tls admin@example.com
tls internal	用本地 CA 签证书（内网开发用）
tls dns cloudflare {...}	DNS-01 验证，支持通配符
tls { cert key }	指定自定义证书文件
auto_https	全局开关自动 HTTPS
acme_ca	换CA（Let’s Encrypt / ZeroSSL / Google）

网络与连接

指令	作用
bind	绑定特定内网 IP 或接口
servers	配置传输层：协议、版本
timeouts	设置读/写/空闲超时
max_header_size	请求头上限
trusted_proxies	信任上游代理传来的 X-Forwarded-*

调试

指令	作用
log	开启访问/错误日志
debug	输出路由匹配过程（排查必备）
metrics	暴露 Prometheus 指标端点

route 与 handle 的最小区别

# 分支互斥，谁先写谁先试
handle /api/* {
    reverse_proxy localhost:8080
}
handle {
    reverse_proxy localhost:3000
}

# 顺序执行，全部跑
route {
    reverse_proxy localhost:3000
    file_server
}

提示

排查路由为什么没命中，第一件事是开debug：

example.com {
    debug
    reverse_proxy localhost:3000
}

它会把每个请求的路由决策打到 stderr，比读配置猜要快得多。