为什么Docker部署的Nginx容器无法正常渲染React Route组件？

问题成因 #

你遇到的DOM已挂载但内容不可见、静态资源实际可访问的现象，核心来自三类配置错误，按出现概率从高到低排序：

1. React应用构建的*公共路径（publicPath）*配置不匹配容器部署路径
   如果你在package.json中配置了homepage字段，或者在webpack/vite配置中设置了非根路径的publicPath，但部署时是放在Nginx根目录下，就会导致懒加载的CSS/JS资源路径错误，样式无法正常加载，出现元素存在但透明/父容器高度为0的情况，嵌套路由场景下该问题尤为高发。
2. react-router的路由前缀配置错误
   如果你使用BrowserRouter时设置了非空的basename参数，但实际部署在根路径下，会导致路由匹配异常，触发路由组件的样式或渲染逻辑异常。
3. Nginx配置的资源类型匹配异常
   你当前的Nginx配置没有明确指定静态资源的MIME类型映射和缓存规则，部分CSS/JS资源可能被错误识别为纯文本，导致样式无法生效。

对应解决方法 #

第一步：校验React应用的公共路径配置 #

• CRA创建的应用：检查package.json是否有homepage字段，根路径部署时要删除该字段，或者显式设为"homepage": "/"
• Vite创建的应用：检查vite.config.js中的base配置，根路径部署时要设为base: "/"
• 配置修改完成后重新执行构建命令生成新的build目录：npm run build

第二步：校验react-router配置 #

如果你使用的是react-router v6+版本，检查根路由的BrowserRouter配置，确保basename参数和部署路径匹配，根路径部署场景不需要加basename，正确示例：

// 正确（根路径部署）
<BrowserRouter>
  <Routes>
    {/* 你的路由定义 */}
  </Routes>
</BrowserRouter>

// 错误（多余的basename配置）
<BrowserRouter basename="/app">

第三步：优化Nginx配置 #

替换你的default.conf为以下配置，补充静态资源处理规则：

server {
  listen 80;
  server_name frontend;
  root /usr/share/nginx/html;
  index index.html index.htm;

  # 处理单页应用路由重定向
  location / {
    try_files $uri $uri/ /index.html;
  }

  # 静态资源缓存与类型匹配配置
  location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
}

第四步：重新构建镜像并运行 #

# 重新构建镜像
docker build -t your-react-app .
# 停止并删除旧容器，启动新容器
docker stop your-old-container && docker rm your-old-container
docker run -p 80:80 your-react-app

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