GitHub Pages 部署指南#

自动部署#

本项目使用 GitHub Actions 自动部署文档到 GitHub Pages。每当代码推送到 main 分支时，会自动触发部署流程。

重要：在首次部署前，需要手动启用 GitHub Pages：

完成设置后，推送到 main 或手动运行工作流即可部署。首次启用需要仓库管理员操作；工作流默认的 GITHUB_TOKEN 只能部署已启用的站点，不能通过 enablement: true 完成首次启用。

触发条件：
- 推送到 main 分支（不限于 docs/ 目录的修改）
- 手动触发（在 Actions 页面选择 main）
构建步骤：
- 设置 Node.js 24 LTS 环境
- 安装 pnpm 包管理器
- 按锁文件安装项目依赖（pnpm install --frozen-lockfile）
- 构建 RSPress 文档
- 验证 /fs-router/ 路径、本地页面/锚点与静态资源，上传 doc_build
发布步骤：
- 独立 deploy job 使用 github-pages 环境，仅此 job 持有 pages: write 和 id-token: write
- 发布 job 不检出代码、不安装依赖，仅部署同一次 main 工作流的构建产物
- fork PR 只触发只读 CI；部署还校验仓库名及 refs/heads/main

所有直接使用的 Actions 固定到官方仓库完整 commit SHA，版本由 Dependabot 跟踪。

问题：依赖安装失败或构建过程出错

解决方案：

问题：GitHub Pages 部署时权限不足

解决方案：

如果部署报站点未启用或 Not Found，先由仓库管理员完成上述首次设置，再重新运行工作流。无需将个人访问令牌添加到部署工作流。

问题：部署成功但页面显示 404 或资源加载失败

解决方案：

问题：更新后页面内容未刷新

解决方案：

如果自动部署失败，可以手动触发部署：

在推送前可以本地测试文档构建：

1# 安装依赖
2pnpm install --frozen-lockfile
3
4# 构建文档
5pnpm docs:build
6pnpm docs:check
7
8# 预览构建结果
9pnpm docs:preview

关键配置项（docs/.rspress/config.ts）：

1export default defineConfig({
2  base: '/fs-router/', // GitHub Pages 路径
3  // 其他配置...
4})

如果遇到无法解决的部署问题，请：

页面导航