子路径部署与 conflict 方案
本文档说明 FlowVisionWeb 如何部署在 GitHub Pages 的
/FlowVisionWeb/子路径下，以及它与本项目（tiramission.github.io根站点 VitePress）共同托管于同一个 Pages 时的冲突问题与解决方案。
背景：两个 Pages 站点的关系
tiramission.github.io 账户下有两个仓库都在使用 GitHub Pages，最终发布到同一个线上域名 https://tiramission.github.io/，只是路径不同：
| 仓库 | Pages 类型 | 线上路径 | 部署内容 |
|---|---|---|---|
tiramission/tiramission.github.io | 用户 / 组织 Pages | https://tiramission.github.io/ | 根路径 VitePress 文档站 |
tiramission/FlowVisionWeb | 项目 Pages | https://tiramission.github.io/FlowVisionWeb/ | FlowVision Web（SPA/PWA） |
GitHub Pages 支持这种「根站点 + 子路径站点」的自然共存：根站点只认自己仓库里生成的静态文件，子路径则由 FlowVisionWeb 仓库自己的 Pages 构建产物提供。
核心冲突点与硬约束
1. 根站点仓库中绝不能存在 /FlowVisionWeb 目录
GitHub Pages 的解析优先级是「仓库内文件 > 同名项目 Pages」。也就是说，如果 tiramission.github.io 仓库的构建产物里恰好出现了一个 FlowVisionWeb/ 目录，那么访问 https://tiramission.github.io/FlowVisionWeb/ 时会命中根仓库里的这个目录，而不是 FlowVisionWeb 项目 Pages 的内容。
解决方案（硬约束，必须长期保持）：
- 本项目
tiramission.github.io的 VitePress 产物体内，不得生成任何名为FlowVisionWeb的路径/目录。 - 本文档站采用
docs/flow-vision-web/（带连字符的完整写法）作为该项目的文档目录，产物路径为/flow-vision-web/，与线上子路径/FlowVisionWeb/在词形上就不同，从源头避免任何大小写或同名歧义。 - 若还用
FlowVisionWeb/flowvisionweb等与子路径仅差大小写的目录，在 GitHub Pages（文件名大小写不敏感的发布环境中）存在被误判为同级路径的风险——因此一律不要使用。 - 若已经存在冲突目录，访问
/FlowVisionWeb/会错误地回落到根站点，导致 FlowVision Web 不可用，需立即删除并改名。
2. 根站点必须设置好 .nojekyll
GitHub Pages 默认用 Jekyll 处理，会忽略以下划线 _ 开头的目录。本项目 VitePress 输出在 docs/.vitepress/dist，deploy 工作流已通过 touch .nojekyll 关闭 Jekyll 处理，保证资源都按原样发布，不会误伤子路径站点。
FlowVision Web 侧如何支持子路径
FlowVision Web 的部署（见其 .github/workflows/release.yml 的 deploy-pages job）专门做了子路径适配：
构建期：注入 base
vite.config.ts 通过环境变量注入 base，CI 在 Pages 构建时显式设置：
// vite.config.ts —— 本地 dev 不设置（根路径），Pages 用 DEPLOY_BASE
const base = process.env.DEPLOY_BASE ?? '/'
export default defineConfig({ base, /* ... */ })# .github/workflows/release.yml（deploy-pages job）
- name: Build（子路径 base）
run: npm run build
env:
DEPLOY_BASE: /FlowVisionWeb/这样构建产物的资源引用（JS/CSS/图标等）都会带 /FlowVisionWeb/ 前缀。
运行期：PWA 相对作用域
PWA manifest 使用相对作用域，保证根部署与子路径部署都正确：
manifest: {
name: 'FlowVision Web',
// 相对作用域：子路径部署（/FlowVisionWeb/）与根部署都正确
start_url: './',
scope: './',
/* ... */
},start_url: './' 与 scope: './' 表示 PWA 的作用域跟随页面当前所在的目录，因此不用硬编码子路径，同一份构建在 / 或 /FlowVisionWeb/ 下都能正常工作。
如何在本文档站中引用 FlowVision Web
由于两个站点同域名、不同路径，本文档站中引用 FlowVision Web 应使用它的完整线上 URL，而不是相对路径：
- 应用入口：
https://tiramission.github.io/FlowVisionWeb/ - 仓库：https://github.com/tiramission/FlowVisionWeb
不要在本文档站写 /FlowVisionWeb/ 这样的相对链接——它会解析到本文档自己的域名根下（https://tiramission.github.io/FlowVisionWeb/），效果虽然一致，但含义不清晰，也可能被未来重构破坏。用「线上完整 URL」或「仓库链接」最稳妥。
冲突排查速查表
| 症状 | 可能原因 | 处理 |
|---|---|---|
访问 /FlowVisionWeb/ 显示 VitePress 404 或根站点内容 | 根仓库构建产物里出现 FlowVisionWeb 目录/docs/flowvisionweb | 删除根仓库对应目录，touch docs/.vitepress/dist/.nojekyll |
| FlowVision Web 资源 404、样式丢失 | 合并 / 二次构建时丢了 DEPLOY_BASE | 确认该仓库 CI 的 deploy-pages job 设置 DEPLOY_BASE: /FlowVisionWeb/ |
| PWA 安装后作用域错乱、离线失效 | start_url / scope 写死为根 / | 改为相对 ./ 并重新发布 |