Vue 和 Vite 做前端项目很顺手，但真正部署到服务器以后，常见问题并不在“能不能打包”，而在构建产物放哪里、刷新页面是否 404、静态资源路径是否正确、SEO 和分享图有没有输出。
我整理 Vue/Vite 项目时，越来越觉得部署前要先分清两件事：这是一个普通 SPA，还是一个内容站/文档站。前者重点是路由回退和资源路径，后者还要额外考虑页面 meta、站点地图和 Open Graph 分享。
先确认构建产物和 public 目录
Vite 打包时，业务代码、CSS 和图片会经过构建处理，最终输出到 dist。但有些不需要构建处理的静态资源，会放在 public 目录，打包后原样复制到站点根路径。
所以部署前先确认：
npm run build是否正常完成。dist里是否有index.html和静态资源目录。public里的图片、图标、验证文件是否已经出现在dist。- 线上访问路径和项目里的
base配置是否一致。
如果项目部署在根路径，比如 https://example.com/，默认配置通常没问题。如果部署在子路径，比如 https://example.com/app/，就要检查 Vite 的 base，否则资源路径可能全部指向错位置。
SPA 刷新 404，通常是 Nginx 回退没配好
普通 Vue SPA 只有一个 index.html。用户在前端路由里访问：
/posts/123服务器上不一定真的存在 /posts/123 这个文件。如果 Nginx 直接按文件查找，就会返回 404。
常见配置是：
location / {
try_files $uri $uri/ /index.html;
}意思是：先找真实文件，再找目录，如果都没有，就交给 index.html，由前端路由接管。
这个配置适合普通 SPA，但不要机械套到所有静态站。比如 VitePress 或一些生成真实 HTML 的文档站，可能需要优先查找 $uri.html，否则页面状态会不对。
VitePress 和普通 Vue 应用不要混用回退规则
VitePress 这类文档站会生成一组静态页面。它不像普通 Vue SPA 那样所有路径都只靠一个 index.html。
如果启用了 clean URLs，Nginx 更适合按这个方向处理：
location / {
try_files $uri $uri/ $uri.html /index.html;
}这里多了一层 $uri.html，是为了让 /guide/start 这类路径能命中实际生成的 guide/start.html。如果直接回退到根 index.html，可能页面能打开，但状态、标题或内容不对。
所以部署前先判断项目类型：
- 普通 Vue SPA：找不到真实文件时回退
/index.html。 - VitePress 文档站：优先找
$uri.html，最后再兜底。 - SSR/SSG 框架：按框架产物和部署平台规则配置。
不要因为都是 Vue 生态，就用同一份 Nginx 模板。
去掉 console.log 之前先确认环境
Vite 项目上线前，经常会处理 console.log。这件事可以做，但不要只为了“看起来干净”就全局粗暴替换。
更稳的做法是：
- 开发环境保留必要日志。
- 生产构建通过压缩配置或插件去掉调试日志。
- 错误日志、埋点和用户行为分析不要误删。
- 关键异常要进入统一监控，而不是依赖浏览器控制台。
如果只是个人站点，优先保证构建稳定和页面可访问。日志优化可以放在上线检查里，但不要让它比路由、资源、SEO 更优先。
内容站要额外处理 SEO
纯后台项目不太需要搜索引擎收录，但博客、文档站、资源站和产品介绍页需要。
Vue/Vite 项目做 SEO 时，先看项目渲染方式：
- 普通 SPA：首屏 HTML 里 meta 信息有限，搜索和分享预览容易不稳定。
- 静态生成：每个页面能提前生成标题、描述和正文，适合内容站。
- SSR：服务端返回完整 HTML，适合更复杂的动态内容。
如果只是普通 Vue SPA，却承担博客或内容站职责，就要额外评估是否需要 Nuxt、VitePress、Astro 或其他静态生成方案。搜索引擎现在能处理一部分 JavaScript，但内容站长期依赖纯客户端渲染仍然不够稳。
Head 管理要区分页面标题和分享信息
Vue 项目里常见 Head 管理方案包括 Unhead、VueUse Head 或框架内置能力。无论用哪个，目标都差不多：
- 每个页面有独立
title。 - 每个页面有
meta description。 - 需要分享时输出 Open Graph 和 Twitter Card。
- canonical 指向主 URL。
分享图尤其容易漏。页面能打开，不代表发到社交软件时能生成卡片。至少要有：
<meta property="og:title" content="页面标题">
<meta property="og:description" content="页面摘要">
<meta property="og:image" content="分享图地址">
<meta name="twitter:card" content="summary_large_image">如果是长期内容站，最好让这些字段来自文章数据，而不是写死在全站模板里。
部署前检查清单
我会把 Vue/Vite 发布前检查压成这几项：
npm run build能通过。dist产物完整，静态资源路径正确。base配置符合线上部署路径。- Nginx 回退规则匹配项目类型。
- 刷新深层路由不会 404。
- 图片、字体、图标和 public 文件能访问。
- 页面标题、描述和 canonical 正确。
- 分享图、Open Graph 和 Twitter Card 正常。
- 移动端导航和主要页面可用。
- 生产环境没有明显调试输出和错误请求。
这份清单不复杂，但能挡住大部分“本地没问题，线上一刷新就坏”的情况。
小结
Vue/Vite 部署不要只看打包命令。普通 SPA、VitePress 文档站和内容站的服务器规则、SEO 诉求和分享信息都不一样。
先确认构建产物和资源路径，再配置合适的 Nginx 回退；如果项目需要搜索流量和社交分享，就把 title、description、canonical、og:image 一起纳入发布检查。这样前端项目上线后会少很多反复改配置的时间。
