nginx部署react项目需三步：精准绑定静态路径（root与homepage严格对齐）、启用try_files $uri $uri/ /index.html兜底前端路由、精细控制http头（cors、gzip、强缓存、禁etag），配合多阶段docker构建实现轻量高效。
直接用官方 Nginx 镜像跑 React 项目，往往只是“能用”，不是“好用”。要实现秒级响应、零卡顿、路径跳转不报 404、跨域不拦截、资源加载不乱序——关键不在堆硬件，而在镜像定制本身。核心就三点：静态路径精准绑定、HTML5 History 路由兜底、HTTP 头精细控制。
静态资源路径必须与 build 输出严格对齐
React 打包后默认生成的文件（index.html、static/ 目录等）必须被 Nginx 的 root 指向精确落位。不能只挂载整个 build 文件夹到 /usr/share/nginx/html，而要让它成为实际服务根路径。
- 若 React 项目部署在域名根路径（如
https://example.com/），Nginx 配置中root应设为/usr/share/nginx/html，且构建时确保homepage: "/" - 若部署在二级路径（如
https://example.com/app/），则需：
– 在package.json中设置"homepage": "/app"
– 构建后将整个build/内容复制进镜像的/usr/share/nginx/html/app/
– Nginx 中location /app/ { root /usr/share/nginx/html; }
必须启用 try_files + fallback 机制支持前端路由
React Router 使用 HTML5 History API，直接访问 /dashboard 这类路径时，Nginx 默认会找磁盘上对应文件，找不到就返回 404。解决方法不是改 Router，而是让 Nginx 把所有非资源请求都回退到 index.html。
- 配置写法必须是：
try_files $uri $uri/ /index.html;（注意结尾斜杠和/index.html的位置） - 不要写成
rewrite ^(.*)$ /index.html last;—— 它会丢失 query 参数，且性能略低 - 该指令必须放在
location /块内，且优先级高于其他location匹配
HTTP 响应头要按需精简，不加冗余也不漏关键项
默认 Nginx 不设 CORS、不压缩、不缓存静态资源，会导致 JS/CSS 加载慢、本地开发联调失败、重复请求浪费带宽。
- 允许跨域开发：
add_header 'Access-Control-Allow-Origin' '*';（上线时建议替换为具体域名） - 启用 gzip 压缩：
gzip on; gzip_types text/plain application/javascript text/css application/json; - 静态资源强缓存：
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control "public, immutable"; } - 禁用 ETag（减少校验开销）：
etag off;
用多阶段构建打造轻量纯净镜像
不建议直接修改官方镜像或用 docker cp 注入文件。推荐 Dockerfile 多阶段构建，把构建产物拷进最小化运行镜像：
- 第一阶段：基于
node:18-alpine安装依赖、执行npm run build - 第二阶段：基于
nginx:alpine-slim（比nginx:alpine更小），仅 COPY 构建产物 + 自定义nginx.conf - 最终镜像体积通常
