跨域API接口Nginx完整修复配置外贸站点

很多外贸站点在对接海外支付、物流追踪或第三方数据接口时，都会遇到浏览器报错：

Access to XMLHttpRequest at 'https://api.example.com' from origin 'https://your-site.com' has been blocked by CORS policy.

这个错误就是典型的跨域问题。
简单说，前端代码去请求不同域名下的API接口，浏览器出于安全限制会拦截响应。
本文教你通过修改Nginx配置，一次性解决这个跨域问题，让外贸站点的API调用畅通无阻。

前置准备

操作前请确认以下几点：

• 你拥有外贸站点的服务器管理权限（SSH或宝塔面板）。
• Nginx已正常运行，且你知道站点配置文件所在位置。常见路径：
• 宝塔面板：/www/server/nginx/conf/vhost/你的站点.conf
• 手动安装：/etc/nginx/conf.d/ 或 /etc/nginx/sites-available/
• 有可用的文本编辑器（如vim、nano，或宝塔在线编辑）。
• 建议先备份原配置：cp 你的站点.conf 你的站点.conf.bak

核心配置：添加CORS跨域头

跨域问题的本质是后端响应头缺少Access-Control-Allow-Origin等字段。
在Nginx中，我们只需要在要转发API请求的location块里加上这些头部即可。

1. 找到API接口对应的location块

假设你的外贸站点API通过 /api/ 路径转发到后端服务（比如Node.js或Java），配置类似：

location /api/ {
    proxy_pass http://localhost:3000/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

如果API是直接由静态文件或另一台服务器处理，也同理。

2. 添加CORS相关配置

在location /api/块内，添加以下内容：

# 允许所有来源访问（外贸场景常用，如需限制请替换为具体域名）
add_header Access-Control-Allow-Origin "*" always;
# 允许携带凭证（如Cookies）时不能使用 *，必须指定具体域名
# add_header Access-Control-Allow-Origin "https://your-site.com" always;  # 更安全

# 允许的HTTP方法
add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;

# 允许的请求头
add_header Access-Control-Allow-Headers "DNT, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Range, Authorization" always;

# 预检请求的有效期（秒），减少OPTIONS请求次数
add_header Access-Control-Max-Age 1728000 always;

3. 处理预检请求（OPTIONS）

浏览器在发送跨域请求前，会先发一个OPTIONS预检请求。
如果Nginx不处理，会直接返回405或404。
需要单独处理：

if ($request_method = 'OPTIONS') {
    add_header Access-Control-Allow-Origin "*" always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "DNT, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Range, Authorization" always;
    add_header Access-Control-Max-Age 1728000 always;
    add_header Content-Length 0;
    add_header Content-Type text/plain;
    return 204;
}

完整示例配置

location /api/ {
    proxy_pass http://localhost:3000/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    add_header Access-Control-Allow-Origin "*" always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "DNT, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Range, Authorization" always;
    add_header Access-Control-Max-Age 1728000 always;

    if ($request_method = 'OPTIONS') {
        add_header Access-Control-Allow-Origin "*" always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "DNT, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, Range, Authorization" always;
        add_header Access-Control-Max-Age 1728000 always;
        add_header Content-Length 0;
        add_header Content-Type text/plain;
        return 204;
    }
}

保存文件后，执行 nginx -t 测试配置语法是否正确。

nginx -t

如果返回 syntax is ok 和 test is successful，则执行 nginx -s reload 重载配置。

常见避坑指南

1. 注意 add_header 的继承与覆盖

Nginx中，add_header 在 当前block 设置，不会自动向下继承。
如果你在 server 块或 http 块定义了 add_header，又在 location 块内重新定义，子块会完全覆盖父块的配置。
所以建议直接在目标location块内完整写入CORS头部。

2. 使用 "*" 还是具体域名？

如果外贸站点API需要携带Cookie或使用认证信息，则不能使用 "*"，必须指定具体来源域名，如 https://your-site.com。
并且还要加上 add_header Access-Control-Allow-Credentials true;。

3. 预检请求OPTIONS返回405

如果配置后POST请求正常，但部分请求还是报错，检查是否遗漏了预检请求的处理。
很多新手只添加了普通响应头，忘记单独处理OPTIONS，导致浏览器预检失败。

4. 使用宝塔面板的用户

在宝塔中，进入“网站” -> 找到对应站点 -> “设置” -> “配置文件”，在server块内找到对应的location段，按上述步骤添加即可。
宝塔每次修改配置后建议先点击“保存”再“重启”。

效果验证

1. 命令行验证

在服务器本地用curl测试（模拟跨域请求）：

curl -H "Origin: https://your-site.com" -H "Access-Control-Request-Method: GET" -X OPTIONS -v https://你的API域名/api/your-endpoint

如果响应头中包含 Access-Control-Allow-Origin: * 或你的域名，并且返回204状态码，说明预检通过。

2. 浏览器验证

打开外贸站点的前端页面，按F12打开开发者工具 -> 网络（Network）选项卡，刷新页面看API请求。
点击对应请求，查看响应头（Response Headers）中是否有上述CORS字段。
如果没有，检查配置是否生效。

3. 编写测试页面

用浏览器的Console执行一段简单JS：

fetch('https://你的API域名/api/endpoint')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

若正常打印数据，说明跨域配置成功。

总结

外贸站点的跨域问题并不复杂，核心就是Nginx响应头配置。
记住三点：确认API location、添加CORS头部、单独处理OPTIONS预检。
如果你正在配置外贸站点API跨域，建议按本文步骤完整执行，再根据自己的业务域名和请求方式微调。
遇到异常时优先回看上方的避坑指南，尤其是add_header覆盖和OPTIONS处理，大部分问题都能解决。