React构建包本地运行正常，部署至VPS后失效求解决方案

核心排查与修复步骤 #

• 修正文件权限
  VPS上的build文件夹及内部所有静态资源（js、css、media等）必须保证web服务器进程可读取。执行以下命令调整权限：

  chmod -R 755 /path/to/your/build/folder
  chown -R www-data:www-data /path/to/your/build/folder # 针对Apache/Nginx，可根据服务器运行用户调整
  

• 校准Web服务器配置
  React单页应用（SPA）的路由需要服务器特殊配置，这是部署失败的高频原因：

  • Nginx配置示例：
    在server块中添加正确的根目录与路由 fallback 规则：

    server {
        listen 80;
        server_name your-domain.com; # 替换为你的域名或VPS公网IP
    
        root /path/to/your/build;
        index index.html;
    
        # 静态资源缓存配置
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    
        # 核心：所有请求指向index.html，支持React路由
        location / {
            try_files $uri $uri/ /index.html;
        }
    }
    

    配置后验证语法并重启服务：

    sudo nginx -t
    sudo systemctl restart nginx
    

  • Apache配置示例：
    先启用mod_rewrite模块，再在build文件夹下创建.htaccess文件：

    Options -MultiViews
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.html [QSA,L]
    

    同时在虚拟主机配置中设置根目录并允许.htaccess生效：

    <VirtualHost *:80>
        ServerName your-domain.com
        DocumentRoot /path/to/your/build
    
        <Directory /path/to/your/build>
            AllowOverride All
            Require all granted
        </Directory>
    </VirtualHost>
    

    重启Apache服务：

    sudo systemctl restart apache2
    

• 检查防火墙与端口状态
  确保HTTP（80）或HTTPS（443）端口已开放：

  # 针对UFW防火墙
  sudo ufw allow 80/tcp
  sudo ufw allow 443/tcp
  sudo ufw reload
  

  验证端口是否被监听：

  sudo netstat -tulpn | grep :80
  

• 浏览器端错误排查
  打开浏览器开发者工具（F12）查看：

  • Console标签：如果有404错误，说明静态资源引用路径错误，可检查build文件夹下index.html中的js/css链接是否为绝对路径导致无法访问；如果是空白页无报错，大概率是路由模式不兼容服务器配置。
  • Network标签：确认所有静态资源是否成功加载，排查加载失败的资源原因。

• 静态服务部署规范
  使用serve等工具部署时，需指定build文件夹并确保端口可用：

  npm install -g serve
  sudo serve -s build -l 80 # 用80端口需sudo权限，避免端口占用问题
  

  检查端口占用情况：

  sudo lsof -i :80
  

额外验证步骤 #

直接在VPS本地用curl测试，确认服务器能否正常返回index.html内容：

curl http://localhost/index.html

如果返回完整HTML代码，说明服务器配置正常，问题可能出在网络或域名解析；如果返回403/404，需重新检查文件权限或路径配置。

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