部署Docusaurus至GitHub Pages后仅显示README而非网站

核心问题定位 #

你碰到的情况确实和peaceiris/actions-gh-pages的默认行为相关——这个Action默认会清空部署分支的所有内容，再推送新的构建产物。要是你的Workflow配置没正确指定Docusaurus的构建输出目录，就会导致部署分支只剩README（或者空目录，GitHub会自动把README渲染成HTML），同时因为没有新内容可推送，Action就会提示Everything up-to-date。

修复步骤 #

1. 修正Workflow配置 #

确保你的GitHub Action YAML文件正确配置以下关键项：

• 正确检出仓库代码（如果有子模块，也要一并检出）
• 安装依赖并执行Docusaurus的构建命令
• 把Docusaurus的构建输出目录（默认是build/）指定给peaceiris/actions-gh-pages

示例正确配置：

name: Deploy Docusaurus to GitHub Pages

on:
  push:
    branches: [main]  # 替换成你的源码分支，比如master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 必须配置，否则Docusaurus无法生成正确的版本信息

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20  # 匹配你的项目Node版本
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build Docusaurus site
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build  # 关键：指定Docusaurus的构建输出目录
          # 如果需要保留部署分支的特定文件（比如CNAME），可以添加下面的配置
          # keep_files: true

2. 手动清理部署分支（可选） #

如果之前的错误部署让gh-pages分支残留了异常内容，可以手动清理后重新部署：

# 本地检出gh-pages分支
git checkout gh-pages
# 删除所有文件（保留.git目录）
git rm -rf .
# 提交空目录
git commit -m "Clean up gh-pages branch"
# 推送到远程仓库
git push origin gh-pages
# 切回源码分支
git checkout main

之后重新触发GitHub Action，就能看到正确的Docusaurus站点被部署。

3. 验证GitHub Pages设置 #

进入仓库的Settings -> Pages页面，确认：

• 部署来源是gh-pages分支的/root目录（不是/docs或其他目录）
• 自定义域名（如果有）配置正确

内容的提问来源于stack exchange，提问作者jcubic