React项目部署Caprover后刷新页面出现404错误求助

问题原因 #

React属于单页应用（SPA），页面路由由前端逻辑处理。刷新页面时，浏览器会直接向服务器请求当前路径的资源，而Caprover默认的Nginx配置不会将这类请求重定向到项目的index.html，因此返回404错误。你当前使用serve托管静态文件，虽然serve本身支持SPA路由，但Caprover的反向代理层未做适配，导致问题出现。

解决方案1：改用Nginx托管静态文件（推荐） #

修改Dockerfile，使用Nginx镜像托管build后的静态文件，并配置Nginx规则处理SPA路由：

# 构建阶段
FROM node:18-alpine as builder
WORKDIR /app
COPY . .
RUN yarn install
RUN yarn build

# 生产阶段
FROM nginx:alpine
# 复制构建产物到Nginx默认静态目录
COPY --from=builder /app/build /usr/share/nginx/html
# 替换默认Nginx配置，适配SPA路由
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

在项目根目录创建nginx.conf文件，内容如下：

server {
    listen 80;
    server_name localhost;
    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)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

重新构建镜像并部署后，Nginx会正确处理前端路由，刷新页面不再出现404。

解决方案2：修改Caprover的Nginx自定义配置 #

若不想改动Dockerfile，继续使用serve，可在Caprover后台配置自定义Nginx规则：

• 进入目标应用的「Settings」页面
• 找到「Nginx Configuration」区域，添加以下配置：

location / {
    try_files $uri $uri/ @rewrites;
}

location @rewrites {
    rewrite ^(.+)$ /index.html last;
}

保存配置后重启应用，Caprover的Nginx会将非静态资源的请求转发到index.html，解决刷新404问题。

内容的提问来源于stack exchange，提问作者Yunus Emre Acar