Linux怎么配置Nginx返回自定义Header Nginx响应头修改详解

在配置Nginx时，给响应加上自定义Header是再常见不过的操作了。无论是用于环境标识、链路追踪，还是传递一些业务信息，都离不开它。但就是这么个看似简单的指令，里面藏着不少容易踩坑的细节。今天，我们就来聊聊几个关键的配置要点，帮你把自定义Header这事儿安排得明明白白。

add_header 只在特定状态码下生效，不是所有响应都带

这里有个最容易被忽略的“默认行为”：add_header指令，默认只对200、201、204、206这些成功状态码，以及301、302、304、307、308这些重定向状态码生效。换句话说，如果你的接口返回了400、401、404甚至500错误，那么你精心配置的自定义Header，客户端是收不到的。

怎么解决？很简单，加上always参数就行：

add_header X-Env "staging" always;

这样一来，无论后端返回什么状态码，这个Header都会稳稳地出现在响应里。不过，需要提醒一点：对于一些安全敏感的Header，比如Set-Cookie，加上always参数可能会被浏览器拒绝，具体使用时还得结合业务场景来判断。

• 不加 always：适合那些只在业务正常响应时才需要透出的标识，比如X-Request-ID。
• 加 always：适合调试类Header（如X-Backend、X-Route）或需要全链路监控的埋点信息。
• 另外要注意继承规则：如果在location块里使用了add_header，它会覆盖server块中同名的Header；如果location块里没声明，则会继承上级的配置。

多个域名要差异化 Header，别硬写一堆 server 块

当你的服务有多个域名，比如api.example.com、admin.example.com、docs.example.com，并且需要为它们设置不同的服务标识Header时，最笨的办法就是在每个server块里重复写一遍add_header X-Service "xxx"。这不仅维护起来麻烦，还容易漏配或写错。

更优雅的解决方案是使用map指令，在http块里预定义变量：

map $host $x_service {
    api.example.com    "api";
    admin.example.com  "admin";
    docs.example.com   "docs";
    default            "unknown";
}

定义好之后，就可以在任意server或location中复用了：

add_header X-Service $x_service;

使用map时，有几个细节需要留意：

• map指令必须写在http块内，不能放在server或location里。
• 它的匹配是精确的字符串比对，不支持通配符。如果你想匹配*.example.com这样的模式，需要使用正则表达式，比如~^.*\.example\.com$。
• 如果变量值为空，那么对应的Header就不会被发送。所以，设置一个default兜底项是个好习惯。

想往请求头（Request Header）里加字段？proxy_set_header 才是正解

这是一个常见的误解：add_header是用来修改Nginx发给客户端的响应头的。如果你想在Nginx将请求转发给后端（如Node.js、Ja va应用）时，往请求头里添加一些字段，让后端的req.headers['x-domain']能拿到当前域名，那就必须用proxy_set_header。

典型的配置长这样：

location / {
    proxy_pass https://backend;
    proxy_set_header X-Domain $host;
    proxy_set_header X-Real-IP $remote_addr;
}

关于proxy_set_header，有几点需要明确：

• 它会覆盖原始的请求头。例如，你配置了proxy_set_header Host $host，那么后端服务看到的Host头就是Nginx接收请求时的$host，而不是客户端最初发来的那个。
• 如果你想保留客户端的原始User-Agent等信息，需要显式地传递：proxy_set_header User-Agent $http_user_agent。
• 对于包含下划线的非标准Header名（比如X-Tenant-ID），默认会被Nginx过滤掉。如果确实需要，得在http块里加上underscores_in_headers on;来允许下划线。

add_trailer 和 add_header 的区别不只是位置

从名字上看，add_trailer似乎只是把Header放在了响应体的末尾。但实际上，它的适用场景要狭窄得多。它主要用在分块传输编码（chunked encoding）且响应体较大的情况下，比如视频流、Server-Sent Events (SSE) 或者大文件下载时传递进度信息。对于普通的JSON API接口，几乎用不到它。

add_trailer有几个关键限制：

• 它不支持always参数（在Nginx 1.19+版本中才支持）。
• 它仅对200、201、206、301–303、307–308这些状态码生效，并且要求响应体没有被压缩（即gzip关闭或未触发压缩）。
• 在浏览器的开发者工具网络面板里，你是看不到Trailer Header的，需要使用curl -i或者专门的抓包工具才能查看到。

所以，除非你确实在处理流式传输或自定义协议透传这类特殊场景，否则，老老实实用add_header就对了。别仅仅因为“末尾”这个字眼，就强行去用add_trailer，那只会给自己增加不必要的复杂度。