Nuxt项目内网服务器域名代理访问故障排查

一、文档概述

本文针对Nuxt项目在本地运行正常、打包无异常，但部署至内网服务器后出现接口访问异常、资源加载失败的问题，梳理故障背景、排查流程及解决方案，为技术人员解决同类内网环境下的代理配置故障提供参考。

二、故障背景与现象

项目环境
- 前端框架：Nuxt3
- 部署模式：node-server模式
- 部署环境：内网服务器
- 代理配置：项目nuxt.config.ts中通过routeRules配置接口代理，目标地址初始为真实域名aa.bb.com/api
故障现象
- 本地开发及本地打包后预览，页面渲染、接口请求均正常；
- 部署至内网服务器后，页面基础资源加载不全，接口请求出现超时、403/404等异常；
- 调整代理目标地址为127.0.0.1/api后，服务器上的接口请求与资源加载恢复正常。

三、故障核心原因分析

（一）内网环境的网络访问限制

域名解析层面

内网服务器的DNS服务无法正常解析公网/内网域名aa.bb.com，或解析后的IP无法穿透内网防火墙访问后端服务，导致代理请求因域名无法寻址而失败。而127.0.0.1为本地回环地址，请求无需经过外网解析，直接在服务器内部流转，无寻址障碍。
网络链路层面

后端服务仅监听服务器本地端口（如127.0.0.1:35200），未开放内网或公网IP监听权限。使用aa.bb.com域名发起代理请求时，请求会被判定为外部访问而被拦截；而127.0.0.1的请求属于本地访问，可直接命中后端服务端口。

（二）代理配置的环境适配缺失

请求头校验拦截

内网后端服务开启了Host请求头校验，Nuxt代理配置中未添加changeOrigin: true参数，导致请求的Host头为Nuxt服务地址而非aa.bb.com，被后端判定为非法请求；而使用127.0.0.1时，本地请求默认通过后端的权限校验，无拦截问题。
内外网代理链路不匹配

本地开发时，aa.bb.com可通过本地DNS或hosts配置指向测试服务，代理链路通畅；但内网服务器无对应配置，且无公网访问权限，直接沿用域名代理会导致链路中断。

四、故障排查流程

（一）基础环境连通性验证

服务器域名解析测试

登录内网服务器，执行以下命令验证域名aa.bb.com的解析情况：
bash 复制代码
```
# 测试域名解析
ping aa.bb.com
# 查看域名解析详情
nslookup aa.bb.com
```
若返回"无法解析域名"或解析IP非后端服务IP，判定为域名解析故障。
本地回环地址连通性测试

在服务器执行curl命令测试本地代理地址：
bash 复制代码
```
curl -v http://127.0.0.1/api
```
若请求正常返回数据，说明后端服务本地访问通畅，故障点为域名代理配置；若仍异常，需排查后端服务监听状态。

（二）后端服务监听状态校验

在服务器执行端口监听查询命令，确认后端服务的监听范围：

bash 复制代码

netstat -tulpn | grep 35200

若监听地址仅为127.0.0.1:35200，说明后端服务仅允许本地访问，无法通过域名aa.bb.com进行代理请求。

（三）Nuxt代理配置校验

检查nuxt.config.ts中的代理配置项，确认是否存在以下问题：

代理目标地址是否为外网/内网不可达的aa.bb.com/api；
是否缺失changeOrigin: true参数，导致请求头不合法；
是否未配置适配内网环境的超时时间和请求头。

五、解决方案

（一）调整代理目标地址

将nuxt.config.ts中routeRules的代理目标地址，从域名aa.bb.com/api修改为服务器本地回环地址127.0.0.1/api，适配内网服务器的网络环境，配置示例如下：

ts 复制代码

export default defineNuxtConfig({
  routeRules: {
    '/proxy/**': { 
      proxy: { 
        to: `${process.env.NUXT_PUBLIC_API_BASE || 'http://127.0.0.1/api'}/**`,
        changeOrigin: true, // 关键参数，适配后端Host头校验
        timeout: 15000 // 延长超时时间，适配内网网络延迟
      } 
    }
  },
  nitro: {
    devProxy: {
      // 本地开发仍可使用域名，区分开发与生产环境
      '/proxy': { 
        changeOrigin: true, 
        target: process.env.NUXT_PUBLIC_API_BASE || 'http://aa.bb.com/api'
      }
    }
  }
})

（二）补充内网域名解析配置（可选）

若需保留域名代理方式，可在服务器hosts文件中绑定域名与本地地址，强制域名解析至回环地址：

Linux/Mac系统
编辑/etc/hosts文件，添加映射关系：
复制代码
```
127.0.0.1 aa.bb.com
```
Windows服务器
编辑C:\Windows\System32\drivers\etc\hosts文件，添加上述映射规则，保存后刷新DNS缓存。

（三）调整后端服务监听范围

联系后端开发人员，将后端服务的监听地址从127.0.0.1:35200修改为0.0.0.0:35200，允许内网服务器通过域名或内网IP访问后端服务，同时配置服务器防火墙放行对应端口。

六、故障验证与复盘

（一）验证步骤

重新打包Nuxt项目并部署至内网服务器；
启动Nuxt服务与后端服务，访问项目页面；
查看浏览器Network面板及服务器日志，确认接口请求状态为200，页面资源加载完整。

（二）复盘要点

记录内网环境与本地环境的网络差异，完善项目部署文档；
针对代理配置，建立"开发环境用域名、生产内网环境用本地地址"的差异化配置规范；
定期巡检内网服务器的DNS与端口监听状态，预防同类故障复现。

七、注意事项

内网部署时，优先使用本地回环地址或内网IP配置代理，避免依赖外网域名解析；
区分开发与生产环境的代理配置，可通过环境变量实现动态切换；
若后端服务有严格的访问白名单，需将内网服务器IP或127.0.0.1加入白名单，保障请求合法性。