前端项目源码构建与部署：Vue/React + Nginx 静态托管与 SSR

前端源码上线前要经历「构建」这一步：把源码编译、压缩、打包成浏览器直接能跑的静态资源。本文讲清楚构建产物如何正确部署到 Nginx，以及容易踩的几个坑。

一、本地构建

Vue（Vite）项目：

npm install
npm run build

React（CRA / Vite）同理。产物默认在 dist/ 目录，把这些文件上传到服务器站点根目录即可。

二、Nginx 静态托管

server {
  listen 80;
  server_name example.com;
  root /www/wwwroot/example.com/dist;
  index index.html;

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

关键在 try_files ... /index.html：前端用了 History 路由时，直接刷新子路径会 404，这行把未匹配的请求回退到 index.html 交给前端路由处理。

三、开启 gzip/brotli 压缩

gzip on;
gzip_types text/css application/javascript application/json image/svg+xml;
gzip_min_length 1k;
gzip_comp_level 6;

压缩后 JS/CSS 体积通常能减少 60% 以上，首屏加载明显加快。

四、静态资源缓存策略

带 hash 的文件名（如 app.8f3a2c.js）内容不变，可以长缓存；index.html 必须短缓存或不缓存，否则发版后用户拿不到新入口：

location /assets/ {
  expires 1y;
  add_header Cache-Control "public, immutable";
}
location = /index.html {
  add_header Cache-Control "no-cache";
}

五、SSR 项目部署

Nuxt / Next.js 等服务端渲染项目，构建产物包含一个 Node 服务，不能只放静态文件。先构建，再用 PM2 跑 node .output/server/index.mjs，Nginx 反向代理到该端口，流程与 Node 项目一致。

六、常见问题

• 刷新 404：漏配 try_files 回退。
• 更新后页面没变：index.html 被缓存，按上文改成 no-cache。
• 接口跨域/404：检查构建时的环境变量里 API 地址是否为线上域名，生产环境代理需在 Nginx 层配置。

前端部署的核心就一句话：构建产物是「最终交付物」，Nginx 负责把入口和资源正确地吐给浏览器。理解 hash 缓存与 History 回退这两个点，绝大部分前端部署问题都能自己解决。