在将前端项目(Vue / React)通过 Nginx 部署到服务器的子目录时,经常会遇到一个令人头疼的问题:页面 HTML 能正常加载,但页面内引用的 app.js、chunk-libs.js 等静态资源却全部报 404 Not Found 错误。
今天就来复盘一下这个经典踩坑案例,并提供彻底的解决方案。
1. 问题场景复现
业务需求是通过 Nginx 进行反向代理,将特定的前缀路径转发到内网的后端服务。
我的 Nginx 配置如下:
location /hcn-web/opms/web {
proxy_pass http://10.8.4.12:8090/web;
proxy_set_header Host $host:$server_port;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# ... 其他配置
}
浏览器报错现象:
当我访问 http://10.8.4.11/hcn-web/opms/web/index.html 时,打开 Chrome 开发者工具的 Network 面板,发现 app.js 标红,状态码为 404。
仔细看 Request URL,浏览器实际请求的地址变成了:http://10.8.4.11/web/js/app.js。
2. 原因排查
既然 Nginx 报 404,说明请求根本没有打到正确的后端目录。我们来检查一下前端请求的源头——index.html 的源码。
打开 index.html 后,发现了根因:
<link href="/web/js/app.js" rel="preload" as="script">
<script type="text/javascript" src="/web/js/app.js"></script>
问题在于路径最前面的那个斜杠 /。
- 浏览器的绝对路径逻辑:当资源路径以
/开头时(如/web/js/app.js),浏览器会认为这是一个基于域名根目录的绝对路径。它会忽略当前页面所在的子目录,直接去域名的根目录下寻找。 - Nginx 拦截失败:浏览器发出的请求是
/web/js/...,而我的 Nginx 配置文件里只写了拦截/hcn-web/opms/web/。因此,Nginx 认为这个请求不归自己管,尝试在服务器的默认根目录找静态文件,自然就找不到了(404)。
3. 解决方案
针对这个问题,有前端改法和运维改法两种途径。
方案一:修改前端打包配置(推荐,治本之法)
如果是 Vue-CLI 或 Webpack/Vite 构建的项目,出现这个问题通常是因为打包时 publicPath (或 base) 设置不当。
解决办法:将绝对路径改为相对路径。
以 Vue 项目为例,找到 vue.config.js(或 vite.config.js),修改 publicPath:
module.exports = {
// 错误写法:publicPath: '/web/'
// 正确写法:改为相对路径
publicPath: './',
// 或者匹配 Nginx 的绝对路径:publicPath: '/hcn-web/opms/web/'
}
重新打包后,index.html 中的引用就会变成相对路径:
<script type="text/javascript" src="js/app.js"></script>
这样浏览器就会顺着当前页面的路径往下找,完美匹配 Nginx 的 location 规则。
方案二:修改 Nginx 配置(运维急救法)
如果你没有前端代码的修改权限,或者着急在生产环境恢复服务,可以直接在 Nginx 层“擦屁股”,把跑偏的请求强行拽回来。
既然前端硬要请求 /web/...,那我们就增加一个 location 块来专门拦截处理这些静态资源:
# 原有业务接口/页面转发保持不变
location /hcn-web/opms/web {
proxy_pass http://10.8.4.12:8090/web;
# ... header 设置
}
# 新增:专门打捞迷失的静态资源请求
location /web {
proxy_pass http://10.8.4.12:8090/web;
proxy_set_header Host $host:$server_port;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
重启 Nginx (nginx -s reload) 后,刷新页面,资源成功加载,404 消失!
4. 总结
Nginx 代理前端项目时的 404 问题,十有八九都是 打包路径 (publicPath) 和 Nginx 代理路径 (location) 不匹配惹的祸。
在项目立项之初,前后端和运维最好能提前约定好项目的部署路径(根目录部署还是子目录部署),并在打包配置中做好相应的设置,就可以避免这种不必要的折腾了。