前端部署白屏自救指南：路由、Nginx、代理全排查

前端build成功，容器运行正常，但打开页面就是白屏。React Router + Nginx + 后端代理，三个环节任何一个出问题都可能导致白屏。这篇帮你快速定位。

坑1：React Router history模式刷新404

部署后首页能打开，但刷新页面或直接访问子路由（/smart-summary）时报404。

原因： history模式需要服务端把所有路由指向index.html。Nginx默认找不到/smart-summary这个文件，就返回404了。

解决方案：Nginx配置try_files

nginx

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

    # 核心：所有路由指向index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源长期缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

坑2：接口404，Nginx代理没配好

页面能打开，但调后端API时返回404，控制台报错。

原因： Nginx没有把/api路径代理到后端服务，或者代理端口写错了。

解决方案：检查proxy_pass配置

nginx

server {
    listen 80;
    root /usr/share/nginx/html;

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

    # API代理到后端容器
    location /api/ {
        proxy_pass http://backend:8000/api/;
        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;
    }
}

快速排查清单：

bash

# 1. 确认后端容器在运行
docker ps | grep backend

# 2. 确认容器网络互通
docker exec -it frontend sh -c "wget -q -O- http://backend:8000/api/health"

# 3. 查看nginx错误日志
docker logs -f nginx

# 4. 查看浏览器控制台报错
# F12 → Console → 看是404还是500

踩坑总结：

• 白屏排查顺序：控制台报错（404/500）→ 路由配置 → 代理配置 → 容器日志。

• history模式需要Nginx try_files或error_page 404 /index.html。

• proxy_pass的端口要和容器实际端口一致，不是宿主机端口。

博客四：《React Router + Nginx 部署白屏终极解决方案》

适合发在： 掘金、知乎
核心受众： 前端开发者、全栈开发者

部署React SPA项目到ECS，刷新页面就白屏。网上搜了一圈，各种配置试了一遍，最后发现是try_files和error_page的细微差别决定的。

坑：history模式下，刷新路由白屏

这是React Router部署中最经典的坑。本地npm run dev没问题，但部署到服务器后，访问/about刷新就白屏。

根本原因：

React Router的history模式使用浏览器History API。本地开发时Vite/Webpack Dev Server做了fallback处理，但Nginx默认不会。

当用户访问/about时，Nginx会在/usr/share/nginx/html目录下找about文件，找不到就返回404。浏览器拿到404，React Router还没启动就已经报错了。

最终解决方案：

nginx

server {
    listen 80;
    server_name your-domain.com;
    root /usr/share/nginx/html;
    index index.html;

    # 方案一：try_files（推荐）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 方案二：error_page 404
    error_page 404 /index.html;
    location / {
        try_files $uri $uri/ =404;
    }
}

方案一 vs 方案二的区别：

 

方案	适用场景	说明
try_files	SPA通用	资源不存在时直接返回index.html，最常用
error_page 404	需要保留原始状态码	先返回404，再重定向到index.html

如果用了CRA（Create React App）：

默认已经做了SPA配置，部署后检查Nginx配置是否有额外拦截规则。

如果用了Vite：

bash

# vite.config.js
export default defineConfig({
  base: '/',  // 部署到根路径
  // 部署到子路径时设置base: '/子路径/'
})

排查工具组合：

bash

# 1. 查看Nginx容器内的文件结构
docker exec -it nginx ls -la /usr/share/nginx/html

# 2. 查看Nginx访问日志
docker exec -it nginx cat /var/log/nginx/access.log

# 3. 直接curl测试
curl -v http://your-domain.com/smart-summary

踩坑总结：

• Nginx的try_files是SPA部署的关键，缺少这一行就会白屏。

• 如果用了error_page 404方案，注意是否和其他规则冲突。

• 部署前先在本地用serve -s build测试SPA路由是否正常。