前端项目 dist 上传部署要点

前端工程构建出来的产物就是一个 dist 目录，部署本身不难，容易出问题的是 base 路径和缓存策略，这两点要在构建前就想好。 先定 base 再构建 base 决定资源引用的前缀。部署在域名根路径用默认的 /；部署在子目录（比如 https://site.com/app/）就要改：Vite 项目在 vite.config 里设 base: '/app/'，webpack 项目对应改 publicPath。路由的 base 要保持一致，例如 vue-router 用 createWebHistory('/app/')。两处 base 不一致的症状很典型：资源加载 404，或者路由跳转后丢了前缀，碰到其中一种就先回来查这两个配置。顺序必须是先定路径再构建，构建完再改 base 只能重新打包，这一步急不得，仓促上线返工更多。 上传与 Nginx 配置 rsync 增量上传最省事，比整包 scp 快得多，改动小的版本传输量缩得更明显： rsync -avz --delete dist/ root@server:/var/www/app/ Nginx 指向 dist 目录，顺手确认压缩已开： root /var/www/app; index index.html; gzip_types application/javascript text/css application/json; location / { try_files $uri $uri/ /index.html; } history 路由的项目必须配 try_files，否则内页刷新直接 404，这是 dist 部署最高频的翻车点。发布前把当次构建产物按日期归档一份（tar -czf dist-20260101.tar.gz dist/），和服务器上的版本一一对应，出问题才有得回滚，归档只留最近几版，老版本定期清掉。 缓存策略分两类 带 hash 的静态资源可以长缓存；index.html 不缓存，否则新版本发布后，用户拿到的还是旧 HTML、引用着已删除的旧资源，白屏往往从这里来，网络慢的用户感受最明显： location ~* /assets/ { expires 1y; add_header Cache-Control "public, immutable"; } location = /index.html { add_header Cache-Control "no-cache"; } 验证与回滚 部署完强刷打开页面，Console 无 404、无跨路径加载错误；用 curl -I 检查两类响应头各就各位：index.html 带 no-cache，assets 带 max-age=31536000。发布一个新版本再访问一次，确认拿到的是新资源而不是缓存。回滚就是换目录：每版部署到独立目录（如 /var/www/app-20260101/），根路径用软链接指过去，出问题把软链接指回上一版再 reload，几秒钟完成，比重传旧包快得多，步骤简单到值班同事都能处理。子目录部署的，重点看资源路径是否带上了正确前缀，再实测一条二级路由的直连，子目录加 history 路由是最容易出错的组合。