企业官网建设流程全解析

人生进阶指南 VitePress 发布出现路径或索引故障时如何用提交 42e6faa 的 Docsify 快照回滚

【免费下载链接】upAn advanced guide which might benefit you a lot 🎉 . 韩先凯的人生进阶指南 人生进阶指南 离谱的人生 人生进阶 离谱的英语学习指南/英语学习教程/英语学习/学英语项目地址: https://gitcode.com/GitHub_Trending/en/up

《人生进阶指南》站点用 VitePress 构建后，如果发布后出现路径或索引故障——页面路径打不开、报错、内容入口缺失——需要用迁移前的 Docsify 版本把站点先恢复起来，同时保留故障证据以便修复后重新发布。仓库把迁移前的完整 Docsify 站点保留在 Git 历史提交42e6faa中，包括原docs/index.html、导航、内容和静态资源，可作为只读快照或紧急回滚源（见 MAINTENANCE.md 与 legacy/docsify-snapshot.md）。站点发布走 GitHub Actions 部署 GitHub Pages，发布后的入口校验写在 .github/workflows/deploy.yml 里。

先保留故障信息

MAINTENANCE.md 要求：回滚后应保留故障页面、URL、浏览器和时间信息，再修复 VitePress 构建并通过预览产物验证后重新发布。这一组信息是后续修复的输入，应在故障发生时随手记好。

文档给出的两条约束会影响你如何查看“旧版本”：

• Pages 发布启用了cancel-in-progress：快速连续提交时，旧的构建或部署会被取消，只允许最新提交继续发布。需要回看旧版本时，应从 Git 历史或 CI 构建产物查看，不要依赖线上页面暂时保留旧内容。
• 仓库的 Pages 发布源必须保持为GitHub Actions，不要切回master:/docs的 Legacy 模式。

首选动作：重跑上一次成功部署

MAINTENANCE.md 对“新站点发布后出现路径或索引故障”给出的第一选择是：在 GitHub Pages 的 Actions 运行记录中找到上一次成功部署，重新运行它。这条路径不碰 Git 分支，适用于上一次构建本身正常、故障只出在本次发布的情形。只有确认需要恢复旧站时，才执行下一节的 Docsify 快照回滚。

用提交 42e6faa 的 Docsify 快照回滚

Docsify 快照是只读快照和紧急回滚源，不是替代当前内容分支。操作路径如下：

1. 先查看旧入口内容，确认快照完整（只读操作，不修改工作区）：

git show 42e6faa:docs/index.html

2. 从提交42e6faa创建独立的临时回滚分支，并部署其docs/目录。文档对这一步列了三条明确限制：
   • 不覆盖当前内容分支（当前master）；
   • 不覆盖用户工作区中的未提交改动；
   • 仓库 Pages 发布源仍按 GitHub Actions 配置保持，不切回 Legacy 模式。

临时分支只服务于这次回滚，后续内容修改不要写进该分支。

重新发布前验证修复后的构建

回滚恢复站点只是止血，收尾动作是修复 VitePress 构建、本地验证后再发布。环境按 MAINTENANCE.md：Node.js 24，版本约束见.nvmrc、.node-version和package.json；package.json 中engines的实际约束是>=24 <25。按顺序执行：

npm ci npm run check npm run docs:build npm run docs:preview npm run test:smoke

• npm ci是首次安装方式，CI 中也用它安装依赖；
• npm run check是完整校验，依次执行导航与 README 的同步检查、内容校验（check:content）和 Markdown 格式检查（check:format）；
• npm run docs:build是 VitePress 生产构建，产物位于docs/.vitepress/dist；
• npm run docs:preview本地预览生产产物，对应文档中“通过预览产物验证后重新发布”的要求；
• npm run test:smoke运行 Playwright 端到端烟测，页面覆盖由导航 source 自动生成，包含中英文页面。

发布后如何确认成功

修复代码合并进master后，由 GitHub Pages Actions 工作流部署。发布后的验证有两层：

1. 人工检查项（MAINTENANCE.md 发布流程）：中文首页、英文首页、代表性章节、搜索、语言切换和旧 hash 跳转。
2. deploy.yml的自动校验：请求每个公开入口，同时核对期望标题与当前提交的build-revision；任何公开入口返回非成功状态、错误页面或旧构建标识都会使部署失败。当前工作流校验的四个入口与期望标题：

每个入口的页面源码中还有build-revisionmeta 标签，其内容必须等于当前提交 SHA，用于确认线上跑的是本次构建而不是旧产物。

限制

• Docsify 快照只存在于 Git 历史提交42e6faa，只作只读快照使用，不要向其写入改动。
• 回滚只能在独立的临时分支上部署，不能覆盖当前内容分支、master或工作区未提交改动。
• 由于cancel-in-progress生效，线上不会保留旧版本；回看旧版本去 Git 历史或 CI 构建产物，CI 的site-preview产物保留 14 天。
• 该路径只恢复旧站，不修复 VitePress 构建本身；完整流程必须以重新发布并通过上述验证结束。

【免费下载链接】upAn advanced guide which might benefit you a lot 🎉 . 韩先凯的人生进阶指南 人生进阶指南 离谱的人生 人生进阶 离谱的英语学习指南/英语学习教程/英语学习/学英语项目地址: https://gitcode.com/GitHub_Trending/en/up