企业官网建设流程全解析

一、背景概述

线上多站点 Nginx 部署架构，同一台服务器同时运行：

• Vue 前端项目（匹配 location / 渲染首页）
• 后端 API 网关（提供 /api/** 接口服务）

问题现象：前端配置/api/转发规则后，接口请求不进 API 匹配规则，直接返回 Vue 前端首页，接口无法正常访问，排查耗时走大量弯路。

最终定位：同台 Nginx 内部，禁止使用公网域名做 proxy_pass 自环转发，会导致虚拟主机匹配错乱。

二、错误配置（踩坑现场）

nginx

# 错误写法：本机内部转发，使用公网域名自环 location /api/ { proxy_pass http://你的公网域名/; proxy_set_header Host $host; }

核心故障原理

1. 请求本机公网域名 → DNS 解析回本机 Nginx
2. 进入 Nginx 后，优先匹配 server_name，而非 location 规则
3. 流量直接落到前端项目的 server 块
4. 未命中 /api/ 规则，直接走location /返回 Vue 首页
5. 接口异常，现象隐蔽，极难快速定位

三、排查弯路

1. 调整 location 配置顺序、校验优先级
2. 排查域名冲突、server_name 配置异常
3. 重启 Nginx、清理缓存、刷新 DNS
4. 逐行比对 Nginx 配置字符、路径、alias 写法
5. 访问 http://127.0.0.1/api/xxx ，出现 “URL 拼写可能存在错误，请检查” 报错，误判为路径拼写问题

四、标准正确解法（线上通用范式）

第一步：定义 upstream 内网上游

nginx

# 顶部定义内网上游，不走公网、不回环、不解析域名 upstream api_servers { server 127.0.0.1:你的端口 max_fails=3 fail_timeout=30s; }

第二步：接口转发直接使用 upstream

nginx

location /api/ { proxy_pass http://api_servers/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }

第三步：校验配置 + 平滑重启

bash

运行

nginx -t systemctl reload nginx

配置生效后，接口立即恢复正常，返回标准 JSON。

五、铁律总结（永久记住）

🚫 严禁行为

同一台 Nginx 内部服务互相转发禁止使用：公网域名 + proxy_pass 自环

✅ 强制规范

1. 内部代理统一使用upstream
2. upstream 指向：127.0.0.1 / 内网 IP
3. 公网域名仅对外开放，内部绝不使用

📌 自环检测法（自查必备）

执行命令：curl -H "Host: 你的公网域名" http://127.0.0.1/api/xxx

• 若返回首页 HTML：说明请求被前端 server 块拦截，存在公网域名自环问题
• 若返回接口 JSON：说明内部转发正常，无自环异常
• 若提示 “URL 拼写可能存在错误，请检查”：优先排查自环转发，而非路径拼写

六、避坑一句话

Nginx 内部转发不走公网域名，只走内网 upstream，永不踩虚拟主机匹配错乱的坑。

七、本文价值

这是前后端分离部署中最常见、最隐蔽、最浪费时间的 Nginx 经典坑。本篇可作为所有前端 + API 部署的标准检查项，一次踩坑，终身避坑。

八、底稿收尾落款

本文是《技术底稿》系列第 32 篇，记录 Nginx 本机公网域名自环代理导致接口返回首页、匹配错乱的完整排障过程，给出可直接上线复用的标准 upstream 配置范式，全程实战落地，无空泛理论，可作为前后端分离部署 Nginx 避坑参考范本。