React单仓生产构建在Nginx反向代理下子路由刷新404问题

问题根源 #

React单页应用（SPA）的路由是前端路由，刷新子路由时，浏览器会直接向Nginx发起对应路径的请求，但Nginx默认会去寻找对应路径的静态文件——而这些文件实际上不存在，因此返回404。你需要配置Nginx，让所有/monorepo/下的非静态资源请求都转发到React应用的入口文件（index.html），同时保留代理规则。

修改Nginx的default.conf配置 #

替换或更新你的Nginx配置，确保包含以下规则：

server {
    listen 80;
    server_name localhost;

    # 处理/monorepo/路径的代理和SPA路由
    location /monorepo/ {
        # 先尝试匹配静态文件，找不到则转发到React入口文件
        try_files $uri $uri/ /monorepo/index.html;

        # 代理到React应用的容器地址
        proxy_pass http://172.16.22.100:3001/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 其他根路径请求处理（可根据需求调整）
    location / {
        return 404;
    }
}

关键配置说明 #

• try_files $uri $uri/ /monorepo/index.html;：Nginx优先尝试访问请求的文件或目录，若都不存在则返回/monorepo/index.html，让React前端路由接管请求，渲染对应子路由页面。
• 确保proxy_pass的路径末尾带有/，这样Nginx会把/monorepo/后的路径追加到代理地址后，比如请求/monorepo/user会被代理到http://172.16.22.100:3001/user。
• proxy_set_header系列配置：让React应用正确识别请求来源，避免路径、鉴权相关的异常问题。

验证步骤 #

1. 替换Nginx容器内的default.conf配置文件。
2. 重启Nginx容器：docker restart <nginx-container-name>。
3. 访问React子路由并刷新页面，确认404问题解决。

额外注意事项 #

• 确保React应用的package.json中配置了正确的homepage字段："homepage": "/monorepo/"，这会让React构建时生成正确的资源路径。
• 如果使用HashRouter而非BrowserRouter，刷新子路由不会出现此问题，但URL会带有#；若不需要这种格式，优先采用上述Nginx配置方案。

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