React项目上线服务器配置完整指南（零基础也能照做）

1. 上线前需要准备什么

在动手配置之前，先把这几样东西准备好：

• 一台 Linux 服务器（推荐 Ubuntu 20.04 或 CentOS 7+，本文以 Ubuntu 为例）。
• 一个已打包的 React 项目（在本地运行 npm run build，生成的 build 目录就是我们要上传的）。
• SSH 客户端（Windows 用 Xshell 或 Putty，Mac/Linux 直接用终端）。
• 域名（可选，但建议用域名访问，方便 HTTPS 配置）。

如果你用宝塔面板，步骤可以简化，但本教程专注于命令行方式，零基础用户可以照着敲。

2. 服务器环境搭建与项目上传

登录服务器后，先安装 Nginx（用来托管静态文件）：

sudo apt update
sudo apt install nginx -y

安装后检查 Nginx 是否运行：

sudo systemctl status nginx

如果看到 active (running) 就对了。
接着用 scp 或 rsync 将本地 build 目录上传到服务器，比如：

scp -r /本地路径/build ubuntu@你的服务器IP:/home/ubuntu/

然后把文件移动到 Nginx 默认站点目录（/var/www/html）下：

sudo mv /home/ubuntu/build /var/www/html/react-app

（你也可以建一个新目录，比如 /var/www/react-app，但需要自己配置 Nginx 根目录。
）

3. 配置 Nginx 实现静态文件访问

现在需要让 Nginx 指向 React 打包文件，并处理前端路由问题（比如刷新后 404）。
编辑默认的 Nginx 配置文件：

sudo nano /etc/nginx/sites-available/default

将 server 块改成下面这样（域名部分按实际修改）：

server {
    listen 80;
    server_name example.com;  # 改成你的域名或服务器IP

    root /var/www/html/react-app;
    index index.html index.htm;

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

关键就是 try_files $uri $uri/ /index.html; 这一行——它解决了 React 单页应用在刷新或直接访问子路径时出现的 404 问题。

保存后检查配置语法：

sudo nginx -t

如果看到 syntax is ok，重启 Nginx：

sudo systemctl restart nginx

4. 常见报错与避坑说明

问题1：访问显示 403 Forbidden

• 原因：Nginx 没有读取目录的权限。执行 sudo chmod -R 755 /var/www/html/react-app。

问题2：刷新页面变成 404

• 原因：没有配置 try_files。请确认第 3 步的配置已包含 try_files $uri $uri/ /index.html;。

问题3：服务器防火墙挡住了 80 端口

• Ubuntu 默认启用 ufw，执行 sudo ufw allow 80 开放端口；云服务器还需在控制台安全组放行 80。

问题4：上传文件后页面内容未更新

• 可能缓存了旧的 index.html。Nginx 默认不缓存 .html，但如果你有 CDN 或浏览器缓存，可以强制清除或给静态资源加版本号。

5. 如何验证部署成功

在浏览器地址栏输入你的服务器 IP 或域名：

http://你的服务器IP

如果看到 React 应用首页，说明上线成功。
接着手动刷新页面、点击内部链接跳转再刷新，确认不会出现 404。
还可以打开开发者工具（F12）的 Network 面板，检查静态资源（JS、CSS）是否正常加载（状态码 200）。

如果你绑定了域名并想用 HTTPS，下一步可以考虑申请 Let's Encrypt 免费证书并配置 Nginx SSL 反向代理。

以上就是 React 项目上线服务器的完整基本流程。
遇到报错时别慌，按避坑清单逐条排查，大部分问题都能解决。
如果你的项目还需要后端接口（比如 Node.js 或 Java），可以用 Nginx 反向代理到后端端口，这部分我之后会单独写一篇教程。