Nginx /api/路径代理转发配置：如何解决API返回链接路径不匹配问题

核心问题说明 #

你目前的代理转发链路本身已经符合基本要求：当proxy_pass配置带尾部斜杠时，Nginx会自动剥离location /api/匹配的前缀路径，把example.com/api/users这类请求里的/users路径正常转发到本地8080端口的API，不需要调整路径映射逻辑。
现在需要解决的核心矛盾是：本地部署的API不知道外部访问的根路径前缀是/api，生成返回链接时默认从域名根目录开始拼接，导致输出的链接都缺少这段前缀。

第一步：配置标准代理头传递访问上下文 #

这是最稳妥、无侵入的解决方案，通过传递标准化请求头，让API自动识别外部访问的根路径前缀，生成正确的链接：

location /api/ {
    # 保留原有基础代理配置
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    # 新增传递访问上下文的标准请求头
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /api;

    proxy_pass http://127.0.0.1:8080/;
}

目前主流的Web后端框架（如Spring Boot、Express、Django、FastAPI）的反向代理适配组件，都可以自动识别X-Forwarded-Prefix请求头，在生成接口返回链接、页面跳转路径、静态资源引用地址时，自动拼接/api前缀，不需要修改API本身的代码。

第二步：兼容无法识别前缀头的老旧API #

如果API框架不支持读取上述代理头，无法自动拼接路径，可以通过Nginx内置的响应内容替换能力做兜底适配，直接修改代理返回给客户端的文本内容，补上缺失的路径前缀：

location /api/ {
    # 保留原有基础代理配置
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://127.0.0.1:8080/;

    # 关闭压缩，保证文本替换能正常生效
    proxy_set_header Accept-Encoding "";
    # 指定需要做文本替换的响应内容类型
    sub_filter_types text/html text/css application/json application/javascript;
    # 对常见的硬编码路径做前缀补全
    sub_filter 'href="/' 'href="/api/';
    sub_filter 'src="/' 'src="/api/';
    sub_filter 'url="/' 'url="/api/';
    sub_filter ':"/' '":"/api/';
    # 每个响应内容仅做一次匹配替换，避免性能损耗
    sub_filter_once on;
}

注意：这种文本替换属于兜底方案，优先建议用第一步的传递请求头方式适配，文本替换容易出现特殊字符漏匹配、跨域响应内容被意外修改的问题，非必要不使用。

常见踩坑提示 #

• 不要把proxy_pass的尾部斜杠删掉，比如改成proxy_pass http://127.0.0.1:8080，这种配置会把example.com/api/users请求完整带上/api前缀转发给后端API，和本地8080上的API路径结构不匹配，会直接触发404错误。
• 配置生效后先清空浏览器缓存再测试，避免浏览器缓存的旧链接路径干扰验证结果。

内容的提问来源于stack exchange，提问作者sks7