前端子路径部署 / SPA Subpath Deploy

技能文档

---
name: spa-subpath-deploy
display_name: 前端子路径部署 / SPA Subpath Deploy
description: 把前端 SPA（Vue/React + Vite/Webpack）安全部署到域名子路径（非根）：覆盖 base 路径、hash vs history 路由、构建前备份、缓存与预览验证。Safely deploy a single-page application (Vue or React built with Vite or Webpack) under a non-root sub-path of a domain, covering base-path config, hash versus history routing, pre-deploy backup, cache-busting, and preview verification. 触发词：前端子路径发布、SPA 部署、子路径白屏、base 路径、deploy SPA subpath。
summary_zh: 把前端 SPA 安全部署到域名子路径（非根），覆盖 base 路径、hash 路由、构建前备份与预览验证。
summary_en: Safely deploy a frontend SPA under a domain sub-path (not root), covering base path, hash routing, pre-deploy backup and preview verification.
version: 1.0.0
category: automation
tags: [frontend, spa, deploy, vite, vue, subpath]
---

# spa-subpath-deploy

把"前端 SPA 部署到域名子路径（非根）"的高频流程与坑固化为可复用方法。适配 Vue / React + Vite / Webpack 等任意构建工具，与具体业务无关——可用于营销活动页、帮助中心、移动版门户等任意子路径应用。

## 简介 / Introduction

**中文**：固化"前端 SPA 部署到域名子路径"的流程与坑：适配 Vue/React + Vite/Webpack，覆盖 base 路径对齐、hash vs history 路由、构建前备份、缓存策略、完整子路径预览。与业务无关。

**English**: A reusable playbook for deploying a frontend SPA to a domain sub-path (not root): base-path alignment, hash vs history routing, pre-deploy backup, cache-busting, and full sub-path preview. Works with Vue/React + Vite/Webpack, business-agnostic.

## 何时用

- 要把一个 SPA 发布到 `https://host/<subpath>/` 而不是根
- 部署后白屏 / 资源 404 / 刷新 404
- 想让"构建前备份 + 预览验证 + 缓存策略"变成可检查清单

## 核心原则

1. **base 路径必须对齐**：构建产物的 publicPath / base 必须等于部署子路径，否则 JS/CSS 相对根加载导致白屏。
2. **路由模式二选一**：子路径下用 hash 路由最稳（零服务端依赖）；若用 history 路由，服务器必须配 fallback 到 index.html，否则刷新 404。
3. **构建前先备份**：发布前把当前 dist 整体复制带时间戳备份，回滚有门。
4. **缓存要有策略**：静态资源加内容哈希或版本查询串，避免浏览器 / CDN 命中旧版。
5. **预览 URL 带子路径验证**：必须用 `https://host/<subpath>/` 全路径访问验证，不能只看本地根路径。

## 分步流程

1. 确认子路径（如 `/mobile/`），写进构建配置（Vite: `base`；Webpack: `publicPath`）。
2. 选路由模式：优先 hash（零服务端依赖）；要 history 则同步改服务器 rewrite 规则。
3. 构建前备份当前线上 dist。
4. 构建产物，确认 index.html 内资源引用带 base 前缀或相对路径。
5. 上传到子路径目录。
6. 用完整子路径 URL 预览：检查控制台无 404、页面渲染、刷新不丢。
7. 有异常 → 从备份回滚。

## 坑（来自真实事故）

- **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。

使用说明

## 解决什么问题

把前端 SPA 安全部署到域名子路径（非根路径），覆盖 base 路径对齐、hash 路由、构建前备份、缓存策略、子路径预览验证。

## 核心保障

- **base 必须等于部署子路径**：Vue/React 项目里 `base` 与部署 URL 不一致时静态资源 404 → 白屏；技能提供环境变量化的 base 设置 + 构建后校验。
- **子路径优先 hash 路由**：避开服务端 history fallback 配置复杂度，零服务器依赖即可上线子路径。
- **构建前整体备份**：现役 dist 自动备份到 `dist_bak_<时间戳>/`，回滚一条命令。
- **静态资源内容哈希**：避免 CDN/浏览器命中旧版导致新功能不可见。
- **完整子路径预览**：构建后用本地静态服务器挂上 `base` 真实路径验证一次再发布。

## 使用方式

1. 在 `src/router` 或构建配置里设 `BASE_URL=/your-subpath/`（或等价的 vite base）。
2. 跑 `npm run build` → 自动备份旧 dist → 输出新 dist。
3. 跑自检脚本 `deploy_checklist.py`，校验 `index.html` 内静态资源引用是否带 `BASE_URL` 前缀。
4. rsync dist 到目标目录。

## 适用场景

Vite/Vue3/Webpack/React/Vue2 全兼容；单应用多子路径；HTTPS 反代路径前缀。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。