Docker部署React应用刷新非首页出现NGINX 404问题求助

问题现象 #

• 访问http://localhost:3000/可正常显示登录页，登录后页面跳转功能正常
• 刷新除首页外的任意页面（如/admin、/users），会出现404 Not Found错误

Docker日志错误信息 #

• 30#30: *1 open() "/usr/share/nginx/html/admin" failed (2: No such file or directory), client: 172.18.0.1, server: localhost, request: "GET /admin HTTP/1.1", host: "localhost:3000"
• 30#30: *1 open() "/usr/share/nginx/html/users" failed (2: No such file or directory), client: 172.18.0.1, server: localhost, request: "GET /users HTTP/1.1", host: "localhost:3000", referrer: "http://localhost:3000/users"

相关配置文件 #

nginx.conf 初始配置 #

upstream backend{
    server ${BACKEND}:8080       max_fails=3 fail_timeout=240s;
}

server {

    listen  3000;
    server_name  localhost;
    root /usr/share/nginx/html;

    location / {    
        index index.html;
        try_files $uri /index.html;
    }

}

App.tsx 路由配置 #

export default function App() {
  const AdminRoute = ProtectedRoute(Admin, ['ADMIN']);
  const UsersRoute = ProtectedRoute(Users, ['ADMIN']);
  const DevicesRoute = ProtectedRoute(Devices, ['ADMIN']);

  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/client" element={<Client />} />
        <Route path="/unauthorized" element={<Unauthorized />} />
        <Route path="/admin" element={<AdminRoute />} />
        <Route path="/users" element={<UsersRoute />} />
        <Route path="/devices" element={<DevicesRoute />} />
      </Routes>
    </BrowserRouter>
  );
}

Dockerfile 配置 #

FROM node:14 as BUILD_IMAGE

WORKDIR /app/react-app

COPY package.json .

RUN npm install

COPY . .

RUN npm run build

FROM nginx:alpine

WORKDIR /usr/share/nginx/html

COPY --from=BUILD_IMAGE /app/react-app/dist .

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

尝试过的无效配置 #

修改nginx配置为以下内容后，页面提示此页面无法正常工作，localhost未发送任何数据：

server {

    listen  3000;
    server_name  localhost;
    root /usr/share/nginx/html;

    location / {    
        index index.html;
        try_files $uri $uri/ /index.html?/$request_uri;
    }

}

解决方案 #

问题核心是React单页应用（SPA）的前端路由特性：刷新非首页时，浏览器会直接向Nginx请求对应路径的物理文件，但这些路径实际不存在（SPA只有一个index.html入口文件），需要Nginx将所有路由请求转发到index.html，由React路由逻辑处理。

正确的Nginx配置调整 #

1. 统一端口：Dockerfile中EXPOSE 80，需确保Nginx监听端口与之一致
2. 优化try_files规则，同时单独处理静态资源，避免缓存问题

修改后的nginx.conf：

upstream backend{
    server ${BACKEND}:8080       max_fails=3 fail_timeout=240s;
}

server {
    listen 80; # 与Dockerfile的EXPOSE端口匹配
    server_name localhost;
    root /usr/share/nginx/html;

    # 单独处理静态资源，设置缓存策略
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 所有路由请求转发到index.html，由React路由处理
    location / {
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}

操作步骤 #

1. 替换容器内的nginx配置文件
2. 重启Docker容器使配置生效：docker restart <容器名称或ID>

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