构建与部署

这一课你将能做到

1. 运行 vite build 产出静态资源，并用 vite preview 本地验收
2. 说明 history 路由在静态托管上需要回退配置
3. 对照 Next.js：Vue+Vite 默认是 CSR 静态资源；本站 platform 是 Next 应用

为什么要学

开发服务器不是上线形态。用户访问的是构建后的 index.html + hashed JS/CSS。
搞不清构建与托管，就会出现「本地好好的，线上白屏/刷新 404」。

先建立图像

npm run build
  → dist/index.html
  → dist/assets/*.js Css（带 hash）
静态托管 / Nginx /对象存储
  → 浏览器下载执行，再请求 /api

项	Vite Vue SPA	本站 Next
默认渲染	客户端	混合 RSC/SSR 等
产出	静态目录	Node 或适配平台
路由	前端 Router	文件系统 + 服务器

跟着做

步骤 1：生产构建

在 Vue 练习项目根目录：

npm run build

应生成 dist/。打开看是否有 index.html 与 assets/。

步骤 2：本地预览

npm run preview

用预览 URL 点一遍路由与刷新。预览比 dev 更接近静态托管行为。

步骤 3：检查环境变量

# .env.production 示例
VITE_API_BASE=https://api.example.com

代码里用 import.meta.env.VITE_API_BASE。注意：只有 VITE_ 前缀会打进客户端包——不要塞密钥。

步骤 4：理解 publicPath / base

若站点挂在 https://example.com/app/ 子路径，需配置 Vite base: '/app/'，否则资源 404。
本站若把练习挂到子路径，这是高频坑。

步骤 5：history 回退

使用 createWebHistory 时，刷新 /tracks/vue-essentials 需要服务器返回 index.html。
Nginx 示例直觉：try_files $uri /index.html;
对象存储静态站常有「SPA 模式」开关。

步骤 6：对照部署本站

platform 走 Next 构建与 Node/托管约定，不是简单把 dist 丢 CDN 就结束。
Vue 练习可以上 Vercel/Netlify/Nginx 静态；不要假设与 Next 部署命令相同。

讲清楚要点

1. hash 文件名利于缓存：内容变则文件名变。
2. preview 先于真上线：减少「我以为 build 过了」。
3. API 地址分环境：dev 代理 vs prod 完整域名。
4. Source map 是否上传按安全策略；公网慎曝源码。
5. 包体积：路由懒加载、分析插件进阶再做。
6. CI：锁 Node 版本，与本地一致，免「我机器可以」。

你可能会懵的地方

• build 过但页面空白？
  看控制台资源路径、base、JS 报错；先 preview 复现。

• 为什么要区分 devDependency？
  构建工具不进浏览器运行时；依赖分类清爽即可。

• SSR/SSG？
  要用 Nuxt 等。纯 Vite Vue 默认 CSR。

• 和 Docker？
  可把 dist 丢进 Nginx 镜像；编排是运维课延伸。

• HTTPS？
  生产必须；本地另说。

错法对照

错法	问题	正解
只测 dev 就上线	漏 base/环境问题	build + preview
密钥进 VITE_ 变量	泄露到浏览器	仅公开配置
无 SPA 回退	刷新 404	服务器配 try_files
子路径未设 base	资源全红	配置 base
把 Next 部署流程套 Vue	命令对不上	按 Vite 静态流程
忽略浏览器控制台	白屏干瞪眼	先看失败资源与异常

自测三问

1. vite build 的主要产物是什么？
2. 为何 history 路由刷新可能 404？
3. 为什么 API 密钥不能放进 VITE_ 环境变量？

小结一句话

Vite 把 Vue SPA 打成静态资源；用 preview 验收，配好 base 与 history 回退，并分清与 Next 部署的差异。

动手加深

步骤 7：对比 dist 与源码体积直觉

构建后看 dist/assets 里 JS 文件大小。若异常巨大：是否误打包了不该进浏览器的库、是否关掉了压缩、是否一次同步 import 了所有路由页。
入门不必做完整 bundle 分析，但要建立「构建产物需要被看见」的习惯。

步骤 8：写一份迷你上线检查单

复制到笔记并逐项打勾：

1. npm run build 成功
2. npm run preview 下首页与动态路由都能进
3. 硬刷新动态路由不 404（或已记录托管回退配置）
4. 网络面板里 API 指向生产/预发正确地址
5. 控制台无未处理异常
6. 未在客户端包中搜索到秘密口令字符串

步骤 9：和 Next 部署各写三句

• Vue+Vite：产出静态文件，托管简单，路由靠回退，数据靠 /api
• Next：按框架约定 build/start，可能有服务端渲染与约定路由
• 本站：学员端走 Next；本课练习走 Vite 静态——两套命令不要混用

把三句贴进结业笔记，综合练习验收时对照。

你可能会懵的地方（补）

• preview 正常、挂到子路径挂了？
  回到 base 配置；资源 URL 前缀必须与挂载路径一致。

• CI 绿、人工访问红？
  缓存 CDN 旧 index.html 指到已删 hash 文件——强刷或清缓存后再查。

错法对照（补）

错法	问题	正解
不看 dist 直接上传 src	线上无法运行	上传 build 产物
用文件协议打开 index.html	模块路径全挂	用静态服务器 / preview
生产开一堆 console 调试残留	噪音与信息泄露	构建前清掉

步骤 10：资源哈希眼看

打开 dist/index.html，看 script 的 src 是否带 hash 文件名。
改一行源码再 build，hash 应变——这就是缓存刷新机制。若 hash 不变，确认是否真的改到会进包的文件。
上线前再确认：验收用的是 preview 端口，而不是误连着旧的 dev 服务。

官方延伸

• Vite 构建生产版本
• 下一课：综合练习