Nginx 在 if 中设置 proxy_set_header 报 directive is not allowed here

想让 CSV 导出请求携带 Accept: text/csv，于是把 proxy_set_header 放进 location 内的 if。运行配置检查时，Nginx 直接拒绝加载：

nginx: [emerg] "proxy_set_header" directive is not allowed here in /etc/nginx/conf.d/reports.conf:12
nginx: configuration file /etc/nginx/nginx.conf test failed

把这一行移到 if 外面，语法错误消失，却又变成所有请求都发送同一个 Accept。要保留条件，需要让条件决定变量的值，再由位于合法上下文中的 proxy_set_header 使用这个变量。

本文针对 Nginx 的 HTTP 反向代理配置。适用前提是报错指令确实写在 if 中；若使用配置面板，需确认它最终生成的层级。示例使用 map 的正则匹配能力，要求 Nginx 0.9.6 或以上；这只是功能下限，不表示建议继续使用这些旧版本。

if 嵌在 location 中，也不是 location 上下文

下面是会触发错误的配置片段：

location /reports/ {
    if ($uri ~ [.]csv$) {
        proxy_set_header Accept text/csv;
    }
    proxy_pass http://127.0.0.1:9000;
}

proxy_set_header 允许出现在 http、server 和 location 中，允许的位置不包含 if。Nginx 解析配置时就会检查这个限制，不会等某个请求满足条件后才决定指令是否合法。调整条件表达式、改引号，或重启后端，都不能改变指令所在的层级。

它设置的是发往后端的请求头。换成 add_header 会改变方向，不能用来给后端补 Accept；浏览器收到的响应头也不能证明后端实际收到了什么。

先按报错路径查看对应文件，沿外层花括号确认这行究竟位于哪里。若文件被 include，还要看它从哪个块中加载。文件名叫 proxy.conf 或放在 conf.d，本身不代表它一定处于正确上下文。

用 map 计算 Accept，保留普通请求的原值

下面是一份展示层级的最小配置：以原始请求路径是否以小写 .csv 结尾决定 Accept，查询参数不参与后缀判断。127.0.0.1:9000 表示与 Nginx 在同一网络命名空间中的示例 HTTP 后端；换成自己的后端地址。它必须能处理 /reports/ 下的相应路径。

events {
    worker_connections 1024;
}

http {
    map $request_uri $reports_accept {
        default                     $http_accept;
        ~^[^?]*[.]csv(?:[?]|$)       text/csv;
    }

    server {
        listen 127.0.0.1:8080;
        server_name reports.example.test;

        location /reports/ {
            proxy_set_header Accept $reports_accept;
            proxy_pass http://127.0.0.1:9000;
        }
    }
}

将这个示例合入已有配置时，只增加 map 和对应的请求头设置，保留已有监听、TLS、认证、路由及其他代理设置，不要整份覆盖生产主配置。

map 放在 http 中，和 server 同级；proxy_set_header 则直接放在需要它的 location 中。若站点文件已经由 http 下的 include 加载，可以把 map 放在该文件的 server 外面，不要再包一层 http。只允许填写 location 内部内容的面板输入框无法容纳这个 map，需要使用能生成 HTTP 级配置的入口。

非 CSV 请求通过默认值继续使用客户端的 $http_accept，而非被统一改成 text/csv。客户端没有 Accept 时，这个变量为空；proxy_set_header 的值为空会让该请求头不发给后端。如果业务明确要求所有普通请求都使用一个固定值，再按接口约定改变 default。

匹配原始路径，避免重写改变判断

$request_uri 包含原始 URI 和查询参数；$uri 是当前规范化的 URI，处理内部重定向等流程时可能改变。上面的配置按客户端最初请求的地址决定格式，因此选用 $request_uri。

正则从开头匹配，[^?]* 不跨过查询参数起点，随后要求 .csv 紧接问号或 URI 结尾。因此 /reports/export.csv?year=2025 会得到 text/csv，而 /reports/export.json?filename=export.csv 不会仅因参数里的文件名就被当作 CSV。

这个规则区分大小写，也按原始 URI 写法匹配；.CSV、编码后的后缀以及带额外尾斜杠的路径都不自动等同于 .csv。如果接口支持这些形式，先明确它的合法路径，再修改映射并分别验证，不要直接扩大正则到所有请求。

map 在变量被使用时求值。已有配置含有 rewrite、其他正则捕获或多级内部跳转时，判断依据应是业务真正需要的原始地址或最终路由，不能只把 $uri 和 $request_uri 当成可互换的写法。

另外，Accept 只是请求头。后端必须实现相应的内容协商或导出功能，设置它不会替后端生成 CSV，也不会自动完成 URL 重写。

增加一条请求头时，检查原有代理头是否仍保留

proxy_set_header 的继承以配置层级为单位：当前层没有任何这类指令时，才继承上一层的设置。假如原先在 server 中统一设置了 Host 和转发协议，而 location 原来没有自己的请求头设置，新加一条 Accept 后，原先依赖继承的那些设置可能不再生效。

合并配置时应核对本 location 所需的完整请求头集合。已有公共代理头片段可以在这里继续复用；需要在本层明确列出的项目按原来的值保留。不要顺便把原来的固定 Host 改成客户端 Host，也不要为了修一个 Accept 错误丢掉应用依赖的转发信息。

最小示例没有额外定制 Host，采用代理模块的默认行为。它展示条件请求头的写法，不代表每个应用都适合这一组最小代理设置。

验收要看后端收到的请求

改动前备份涉及的配置文件，放到不会被 include 通配符加载的位置。如果当前文件已经无法通过检查，还应保留上一个已知可工作的版本作为回退基线。

使用实际运行实例对应的 Nginx 可执行文件和配置路径。以下以默认主机安装为例；服务若用了自定义 -c、-p 或容器，检查与加载也必须针对同一份配置：

sudo nginx -t

检查通过后，按原有服务管理方式重载。直接用 Nginx 管理的同一实例可以执行：

sudo nginx -s reload

-t 会检查配置语法并尝试打开引用文件，但不会验证后端是否真的按 Accept 返回 CSV。对于上述本机示例，可以用下面两种请求检查；路径应替换为后端已存在、可安全读取的接口：

curl --noproxy '*' -i \
  -H 'Host: reports.example.test' \
  -H 'Accept: application/json' \
  'http://127.0.0.1:8080/reports/export.csv?year=2025'

curl --noproxy '*' -i \
  -H 'Host: reports.example.test' \
  -H 'Accept: application/json' \
  'http://127.0.0.1:8080/reports/export.json?filename=export.csv'

在受控环境中查看后端请求日志或已有的请求头诊断接口：第一种请求应收到 Accept: text/csv，第二种应保留 Accept: application/json。同时检查响应内容、原有 Host 及应用依赖的转发头。无需把 Cookie、Authorization 等敏感请求头全部写进日志，更不要公开诊断接口。

只有配置成功加载、条件分支正确、普通请求保持预期，才能确认本次修复完成。若重载无法应用新配置，Nginx 会继续使用旧配置；若新配置能加载但请求行为异常，则恢复已知可工作的整组配置，通过检查后重新加载。不要把含有非法 if 指令的故障版本当作有效回退。