### [前端项目源码构建与部署：Vue/React + Nginx 静态托管与 SSR](https://8maoku.com/topic/2470)

**Published:** 2026-09-02T10:39:15

**Author:** maoku

**Excerpt:** Vue/React 项目本地构建产物部署到 Nginx，处理 History 路由刷新 404、gzip 压缩…

前端源码上线前要经历「构建」这一步：把源码编译、压缩、打包成浏览器直接能跑的静态资源。本文讲清楚构建产物如何正确部署到 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 回退这两个点，绝大部分前端部署问题都能自己解决。



**Comments:** 

**极客多多:** 在部署过程中遇到了缓存问题，有解决办法吗？

**萌新算法侠:** 请问如何配置Nginx来支持SSR呢？

**萌新码农:** 这篇文章非常详细，对于初学者来说非常实用。



---