在用 OpenResty 搭建 API 网关时，CORS 配置看似简单，却很容易踩坑——尤其是当你的 location 块由外部配置文件统一管理时。本文记录我在实际项目中遇到的两堵墙，以及最终用 Lua 阶段钩子彻底解决问题的过程。

---

问题背景

服务器运行 OpenResty，对外暴露 API 接口，需要允许以下前端域名跨域访问：

  • `tools.ropean.org`
  • `tools.aceapp.dev`

要求所有请求头均可通过，并支持携带凭据（Cookie / Authorization）。

---

第一堵墙：`add_header` 不能放在 `server` 块顶层

最直觉的写法是把 CORS 头直接加在 server 块里：

server {
    set $cors_origin "";
    if ($http_origin ~* "^https?://(tools\.ropean\.org|tools\.aceapp\.dev)$") {
        set $cors_origin $http_origin;
    }

add_header Access-Control-Allow-Origin $cors_origin always; # ❌ } `

启动时直接报错：

[emerg] "add_header" directive is not allowed here

nginx / OpenResty 的 add_header 只在 http、location、if（位于 location 内）等特定上下文中有效，裸放在 server 块顶层是不被允许的。

---

第二堵墙：`location /` 冲突，add_header 也不跨 location 继承

既然不能放顶层，那就新建一个 location / 来包裹 CORS 逻辑：

location / {
    add_header Access-Control-Allow-Origin $cors_origin always;
    ...
}

但项目里已经通过 include 引入了外部配置文件：

include /www/sites/blog-api.ropean.workers.dev/proxy/*.conf;

而 proxy/root.conf 里已经存在 location /，于是启动时报：

[emerg] duplicate location "/" in /www/sites/.../proxy/root.conf:1

即使没有冲突，nginx 的 add_header 也不会跨 location 继承——父级 location 的 header 对子级或兄弟级 location 完全无效。这意味着就算能新建 location /，它也覆盖不了 proxy/*.conf 里的其他 location。

---

解决方案：OpenResty Lua 阶段钩子

OpenResty 内置 lua-nginx-module，提供了请求生命周期中各个阶段的钩子指令。其中两个可以放在 server 级别，天然覆盖所有 location，完美绕开继承问题。

1. 拦截 OPTIONS 预检请求 — `rewrite_by_lua_block`

浏览器在发送跨域非简单请求前，会先发一个 OPTIONS 预检请求。如果让它流入代理 location，后端通常不处理 OPTIONS，会返回 404 或 405，导致 CORS 失败。

rewrite_by_lua_block 运行在路由阶段之前，可以在请求被分配到任何 location 之前将其拦截：

rewrite_by_lua_block {
    if ngx.req.get_method() == "OPTIONS" then
        local origin = ngx.req.get_headers()["Origin"] or ""
        if origin:match("^https?://tools%.ropean%.org$")
        or origin:match("^https?://tools%.aceapp%.dev$") then
            ngx.header["Access-Control-Allow-Origin"]      = origin
            ngx.header["Access-Control-Allow-Methods"]     = "GET, POST, PUT, PATCH, DELETE, OPTIONS"
            ngx.header["Access-Control-Allow-Headers"]     = "*"
            ngx.header["Access-Control-Allow-Credentials"] = "true"
            ngx.header["Access-Control-Max-Age"]           = "86400"
            ngx.status = 204
            ngx.exit(204)  -- 立即终止，不再往下走
        end
    end
}

ngx.exit(204) 会立即终止请求处理，响应直接返回给客户端，不会触及任何代理 location。

2. 为所有响应注入 CORS 头 — `header_filter_by_lua_block`

对于正常的 GET / POST 等请求，需要在上游响应返回后、发送给客户端之前注入 CORS 头。header_filter_by_lua_block 运行在响应头过滤阶段，同样是 server 级别，覆盖所有 location：

header_filter_by_lua_block {
    local origin = ngx.req.get_headers()["Origin"] or ""
    if origin:match("^https?://tools%.ropean%.org$")
    or origin:match("^https?://tools%.aceapp%.dev$") then
        ngx.header["Access-Control-Allow-Origin"]      = origin
        ngx.header["Access-Control-Allow-Methods"]     = "GET, POST, PUT, PATCH, DELETE, OPTIONS"
        ngx.header["Access-Control-Allow-Headers"]     = "*"
        ngx.header["Access-Control-Allow-Credentials"] = "true"
    end
}

无论请求被 proxy/root.conf 还是其他 conf 文件里的哪个 location 处理，这段代码都会执行。

---

为什么不用 `Access-Control-Allow-Origin: *`？

两个原因：

  1. `*` 无法与 `Access-Control-Allow-Credentials: true` 同时使用，浏览器会直接拒绝。
  2. 动态回填经过校验的 `Origin` 值，才是白名单模式的正确做法，安全性更高，且维护只需改一处。

---

最终配置结构

server {
    listen 80;
    server_name blog-api.ropean.workers.dev api.aceapp.dev;

# 代理通用头 proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Host $server_name; proxy_set_header X-Real-IP $remote_addr; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $http_connection;

access_log /www/sites/blog-api.ropean.workers.dev/log/access.log main; error_log /www/sites/blog-api.ropean.workers.dev/log/error.log;

# ✅ 拦截 OPTIONS 预检，server 级别，路由前执行 rewrite_by_lua_block { if ngx.req.get_method() == "OPTIONS" then local origin = ngx.req.get_headers()["Origin"] or "" if origin:match("^https?://tools%.ropean%.org$") or origin:match("^https?://tools%.aceapp%.dev$") then ngx.header["Access-Control-Allow-Origin"] = origin ngx.header["Access-Control-Allow-Methods"] = "GET, POST, PUT, PATCH, DELETE, OPTIONS" ngx.header["Access-Control-Allow-Headers"] = "*" ngx.header["Access-Control-Allow-Credentials"] = "true" ngx.header["Access-Control-Max-Age"] = "86400" ngx.status = 204 ngx.exit(204) end end }

# ✅ 注入 CORS 响应头，server 级别，覆盖所有 location header_filter_by_lua_block { local origin = ngx.req.get_headers()["Origin"] or "" if origin:match("^https?://tools%.ropean%.org$") or origin:match("^https?://tools%.aceapp%.dev$") then ngx.header["Access-Control-Allow-Origin"] = origin ngx.header["Access-Control-Allow-Methods"] = "GET, POST, PUT, PATCH, DELETE, OPTIONS" ngx.header["Access-Control-Allow-Headers"] = "*" ngx.header["Access-Control-Allow-Credentials"] = "true" end }

# SSL 证书续签验证 location ^~ /.well-known/acme-challenge { allow all; root /usr/share/nginx/html; }

# 原有代理配置，完全不动 include /www/sites/blog-api.ropean.workers.dev/proxy/*.conf; } `

---

三种方案对比

方案是否可行原因
`add_header` 放 `server` 块顶层❌该上下文不允许此指令
新建 `location /` + `add_header`❌与已有 `location /` 冲突
父级 location `add_header`❌子/兄弟 location 不继承
`header_filter_by_lua_block`✅server 级，阶段执行，不受 location 限制
`rewrite_by_lua_block` 拦截 OPTIONS✅路由前执行，直接返回，不进代理

---

总结

nginx 的 add_header 是 location 级别的指令，跨 location 场景下天然无力。当你的 location 由外部文件管理、无法随意修改时，OpenResty 的 Lua 阶段钩子是最干净的解法——不改动任何现有 location，通过生命周期阶段实现横切关注点，这正是 OpenResty 相比纯 nginx 最大的优势所在。