Nginx跨域问题API中转解决：零基础配置教程

一、什么时候需要用 Nginx 做 API 中转？

当你本地的前端页面（比如 http://localhost:3000）调用后端接口（比如 http://api.example.com/data）时，浏览器会因为同源策略直接拦截请求，报错 No 'Access-Control-Allow-Origin'。
如果你无法修改后端代码来添加跨域头，或者后端服务不允许你手动设置响应头，那么用 Nginx 做一次反向代理中转就是最简单实用的方案。

本文直接从零开始，带你用 Nginx 配置一个跨域中转服务，整篇文章你只需要会复制粘贴和修改自己的域名。

二、准备工作：确认环境与文件路径

开始前先确认三件事：

• Nginx 已安装：在服务器终端执行 nginx -v，如果返回版本号说明已安装；如果报错 command not found，先安装。以 CentOS 为例：sudo yum install nginx。
• 知道配置文件位置：一般位于 /etc/nginx/nginx.conf 或 /etc/nginx/conf.d/ 目录下。推荐在 conf.d 下新建一个 .conf 文件，便于管理。
• 准备好你自己的 API 地址：比如原始接口是 http://api.example.com/data，你希望前端通过 http://yourdomain.com/api 来访问。

三、核心配置：Nginx 反向代理 + 跨域头

1. 进入 Nginx 配置目录（比如 /etc/nginx/conf.d/），新建文件 api-proxy.conf：

sudo vi /etc/nginx/conf.d/api-proxy.conf

1. 粘贴以下配置，并替换 proxy_pass 为你自己的后端 API 地址：

server {
    listen 80;
    server_name yourdomain.com;   # 替换成你的域名或IP

    location /api/ {
        proxy_pass http://api.example.com/;  # 替换成真实后端接口地址

        # 添加跨域响应头
        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,Authorization';
        add_header Access-Control-Expose-Headers 'Content-Length,Content-Range';

        # 处理预检请求（OPTIONS）
        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,Authorization';
            add_header Access-Control-Max-Age 1728000;
            add_header Content-Type 'text/plain; charset=utf-8';
            add_header Content-Length 0;
            return 204;
        }
    }
}

配置说明：

• proxy_pass 后面的 URL 末尾加斜杠 / 表示去掉匹配的前缀 /api/，直接转发剩余路径。
• 跨域响应头中的 Access-Control-Allow-Origin 如果设定为 *，允许所有域名访问；生产环境建议替换为具体的前端域名。
• OPTIONS 预检请求必须返回 204，否则浏览器会拒绝真实请求。

1. 检查配置文件语法：

sudo nginx -t

如果输出 syntax is ok 和 test is successful，说明配置正确。

1. 重载 Nginx 使配置生效：

sudo nginx -s reload

四、常见问题与避坑指南

问题1：配置后发现还是报跨域错误

原因：Nginx 添加的响应头可能被后端返回的响应头覆盖。
解决方法：在 add_header 前加上 always 参数，比如 add_header Access-Control-Allow-Origin '*' always;，确保跨域头始终被添加。

问题2：前端请求路径和后端实际路径不匹配

检查：假设前端请求 https://yourdomain.com/api/user，Nginx 会把该请求转发到 http://api.example.com/user。
如果后端实际接口是 /v1/user，则需要在 proxy_pass 中添加路径重写，或用 rewrite 指令。

问题3：HTTPS 场景怎么办？

处理：如果你的站点启用了 HTTPS（推荐），需要把 listen 80 改为 listen 443 ssl，并配置 ssl_certificate 和 ssl_certificate_key 文件路径。
跨域头配置保持不变。

五、验证效果与总结

1. 用浏览器开发者工具（F12）访问前端页面，发起一个 API 请求。
2. 在 Network 面板查看该请求的响应头，确认存在 Access-Control-Allow-Origin: *（或具体域名）。
3. 如果没有报跨域错误，说明配置成功。

总结一下：Nginx 跨域问题 API 中转解决的本质就是让 Nginx 作为桥梁，替前端转发请求并“代写”跨域头。
只要注意预检请求的处理和响应头的覆盖问题，零基础也能自己搞定。
遇到问题优先检查 Nginx 错误日志（sudo tail -f /var/log/nginx/error.log），往往能快速定位问题。

如果你正在处理 Nginx 跨域问题API中转解决，建议先按本文步骤完整执行，再根据自己的环境做微调；
遇到异常时优先回看避坑和高频问题部分。