Nginx跨域配置修复外贸站点API请求报错

外贸站点前端调用第三方或自建API时，浏览器提示“No 'Access-Control-Allow-Origin' header is present”之类的跨域报错，原因是浏览器同源策略阻止了跨域请求。
解决方法是让Nginx在响应中添加CORS头。
本文围绕Nginx跨域配置修复外贸站点API请求报错，提供可直接落地的操作步骤，零基础用户也能照做。

外贸API跨域报错的典型场景

外贸网站经常需要从国外服务商（如支付、物流、汇率接口）获取数据，当前端JavaScript直接请求这些不同域名或端口的API时，浏览器会拦截响应。
即使后端服务器正常返回数据，浏览器也会阻止前端读取。
这种情况必须由服务器（或反向代理层）主动添加CORS响应头。
如果代理层使用的是Nginx，配置跨域是最常见的处理方式。

配置前确认两件事

在动手修改Nginx配置之前，建议先确认以下信息：

• Nginx配置文件路径：通常是/etc/nginx/nginx.conf或/etc/nginx/sites-enabled/下的虚拟主机配置文件。如果使用宝塔面板，可在“网站”设置中找到对应的Nginx配置片段。
• 当前站点是否已有location规则：你需要找到处理API请求的location块。一般外贸API请求的路径有固定前缀，例如/api/或/v1/。如果没有区分，可以直接在server块中添加全局CORS配置。

另外，如果你使用的是泽御云服务器，其预装的环境面板或手动安装的Nginx均可参照本文步骤配置，操作路径无差异。

具体配置步骤

以下配置针对Nginx作为反向代理或直接服务静态文件的情况。
假设你需要允许所有域名访问（外贸场景中如果API只供特定站点使用，建议指定域名）。

1. 添加CORS响应头

在你需要放开跨域的location块中，加入以下指令：

add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
add_header Access-Control-Max-Age 86400;

• Access-Control-Allow-Origin：允许的来源，*表示所有域名。生产环境建议替换为具体域名，如https://yourfrontend.com。
• Allow-Methods：允许的HTTP方法，一般外贸API至少包含GET和POST，加上OPTIONS用于预检请求。
• Allow-Headers：允许的自定义请求头，根据实际需要增减。
• Max-Age：预检请求结果缓存时间（秒），减少重复预检。

2. 处理预检请求（OPTIONS）

浏览器在发起复杂请求（如自定义头、POST JSON）前会先发一个OPTIONS请求。
Nginx需要对这个请求直接返回204状态码，避免把请求传向后端。
在同一个location前加上判断：

if ($request_method = 'OPTIONS') {
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
    add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
    add_header Content-Length 0;
    add_header Content-Type text/plain charset=UTF-8;
    return 204;
}

这段代码必须放在location块内且位于常规处理之前。
如果Nginx版本较新，也推荐使用map或geo模块更规范地处理，但对新手而言直接写if最直观。

3. 合并后的完整配置示例

location /api/ {
    if ($request_method = 'OPTIONS') {
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
        add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        add_header Content-Length 0;
        add_header Content-Type text/plain charset=UTF-8;
        return 204;
    }
    proxy_pass http://backend_api;  # 如果是反向代理
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
    add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
    # 如果需要后端处理其他方法，可省略其他add_header
}

修改完成后，执行nginx -t测试配置语法是否正确，然后systemctl reload nginx（或nginx -s reload）重载配置。

避坑指南与常见报错

避免重复添加头导致错误

如果后端应用（如PHP、Node.js）自己也输出了CORS头，Nginx又添加了一次，可能导致多个同名头（允许情况下浏览器会合并，但可能引发异常）。
建议在后端关闭CORS输出，统一由Nginx控制。

指定域名时注意端口和协议

Access-Control-Allow-Origin如果指定为https://mydomain.com，必须完全匹配请求头的Origin（包括端口）。
如果前端请求时带端口，也要在配置中明确。

预检请求缓存导致修改不生效

配置中的Access-Control-Max-Age设置了缓存时间，修改配置后如果浏览器仍使用旧缓存，建议清除缓存或临时设置Max-Age 0测试。

使用*时不要带其他值

Access-Control-Allow-Origin不能同时设置*和具体域名，浏览器会报错。
如果需要在不同请求中返回不同值，需使用$http_origin变量配合map。

验证配置是否生效

你可以用以下几种方式快速验证：

• 使用curl模拟请求：curl -H 'Origin: https://yourfrontend.com' -I https://api.yourdomain.com/api/xxx，查看响应头中是否有Access-Control-Allow-Origin。
• 在浏览器开发者工具的“Network”面板查看API请求的Response Headers。
• 使用在线工具如“CORS Test”输入API地址测试。

如果配置正确，前端不会再有跨域报错。

常见问题（FAQ）

Q1: 配置后依然报错“No 'Access-Control-Allow-Origin' header”，怎么回事？

检查配置是否添加到了正确的location块，以及Nginx是否重载成功。
也要确认响应是否经过了CDN或其他缓存层，它们可能过滤了头。

Q2: 是否允许所有域名安全吗？

外贸场景中如果API只被特定前端调用，建议限制具体域名。
如果使用*，则任何网站都可以向你的API发送请求，存在CSRF风险。
可通过配合Nginx的map模块实现动态判断。

Q3: OPTIONS请求返回405怎么办？

可能是Nginx没有匹配到处理OPTIONS的规则，
确认if ($request_method = 'OPTIONS')没有与其他rewrite冲突，
并且return 204正确执行。

Q4: 宝塔面板怎么配置跨域？

宝塔面板中，在网站设置 -> 配置文件，找到对应location块，按照本文示例添加代码，保存后重启Nginx即可。

如果你正在处理Nginx跨域配置修复外贸站点API请求报错，建议先按本文步骤完整执行，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分。