spa-subpath-deploy
把"前端 SPA 部署到域名子路径（非根）"的高频流程与坑固化为可复用方法。适配 Vue / React + Vite / Webpack 等任意构建工具，与具体业务无关——可用于营销活动页、帮助中心、移动版门户等任意子路径应用。
何时用
- 要把一个 SPA 发布到
https://host/<subpath>/而不是根 - 部署后白屏 / 资源 404 / 刷新 404
- 想让"构建前备份 + 预览验证 + 缓存策略"变成可检查清单
核心原则
- base 路径必须对齐：构建产物的 publicPath / base 必须等于部署子路径，否则 JS/CSS 相对根加载导致白屏。
- 路由模式二选一：子路径下用 hash 路由最稳（零服务端依赖）；若用 history 路由，服务器必须配 fallback 到 index.html，否则刷新 404。
- 构建前先备份：发布前把当前 dist 整体复制带时间戳备份，回滚有门。
- 缓存要有策略：静态资源加内容哈希或版本查询串，避免浏览器 / CDN 命中旧版。
- 预览 URL 带子路径验证：必须用
https://host/<subpath>/全路径访问验证，不能只看本地根路径。
分步流程
- 确认子路径（如
/mobile/），写进构建配置（Vite:base；Webpack:publicPath）。 - 选路由模式：优先 hash（零服务端依赖）；要 history 则同步改服务器 rewrite 规则。
- 构建前备份当前线上 dist。
- 构建产物，确认 index.html 内资源引用带 base 前缀或相对路径。
- 上传到子路径目录。
- 用完整子路径 URL 预览：检查控制台无 404、页面渲染、刷新不丢。
- 有异常 → 从备份回滚。
坑（来自真实事故）
- base 配错：构建配置里 base 写成
/或漏配 → 生产资源全 404 → 白屏。 - history 路由刷新 404：子路径下用 history 但服务器没配 fallback → 用户刷新子页直接 404。
- 内联构建配置不生效：部分构建工具内联的 postcss / 代理配置被忽略 → 必须抽成独立配置文件（如
postcss.config.cjs）。 - 没备份就发：构建产物覆盖后无法回滚，只能重发旧包。
- 缓存旧版：浏览器 / CDN 命中旧 index.html → 看到旧功能，误以为没发成功。
骨架脚本
scripts/deploy_checklist.py：参数化发布前自检（base 配置、路由模式、资源前缀、备份、预览清单），生成报告。改配置即可用，无业务耦合。
验收清单
见 references/acceptance-checklist.md（7 条，上架 / 改版前必跑）。
触发词
前端子路径发布、SPA 部署、子路径白屏、base 路径、deploy SPA subpath。
