在将前端项目(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>

问题在于路径最前面的那个斜杠 /。

  1. 浏览器的绝对路径逻辑:当资源路径以 / 开头时(如 /web/js/app.js),浏览器会认为这是一个基于域名根目录的绝对路径。它会忽略当前页面所在的子目录,直接去域名的根目录下寻找。
  2. 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) 不匹配惹的祸。
在项目立项之初,前后端和运维最好能提前约定好项目的部署路径(根目录部署还是子目录部署),并在打包配置中做好相应的设置,就可以避免这种不必要的折腾了。