Run actions/configure-pages@v4 Error: Get Pages site failed.

遇到的错误：

Error: Get Pages site failed. Please verify that the repository has Pages enabled and configured to build using GitHub Actions, or consider exploring the `enablement` parameter for this action.

是在使用 GitHub Actions 中的 actions/configure-pages@v4 时出现的。这个错误的核心原因是：你的 GitHub 仓库尚未启用 GitHub Pages，或未正确配置为“通过 GitHub Actions 部署”。

---

✅ 解决方案

步骤 1：在 GitHub 仓库中手动启用 Pages（关键！）

即使你用 Actions 自动部署，首次仍需在 UI 上启用 Pages 并选择“GitHub Actions”作为源。

1. 打开你的 GitHub 仓库。
2. 点击顶部菜单栏的 Settings。
3. 在左侧边栏找到并点击 Pages（或直接访问 https://github.com/<your-name>/<repo>/settings/pages）。
4. 在 Source 部分：
   • Branch: 不要选 main 或 gh-pages！
   • 而是选择 “GitHub Actions”（如下图）
     
5. 点击 Save。

⚠️ 如果你没看到 “GitHub Actions” 选项，请先确保你的仓库里有 .github/workflows/*.yml 文件（即已定义 Actions workflow），然后刷新页面。

---

步骤 2：确认你的 Workflow 使用了正确的 Pages Action 组合

一个标准的 VitePress + GitHub Pages 部署 workflow 应包含以下三步：

# .github/workflows/deploy.yml
name: Deploy Docs to Pages

on:
  push:
    branches: [main]  # 或你指定的分支

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 必须！否则 VitePress 的 lastUpdated 可能出错

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - name: Install pnpm
        run: npm install -g pnpm

      - name: Install dependencies
        run: pnpm install

      - name: Build docs
        run: pnpm docs:build  # 确保这个脚本能生成 ./dist-docs

      - name: Setup Pages
        uses: actions/configure-pages@v4
        with:
          # 可选：自动启用 Pages（但首次仍建议手动开启）
          enablement: true

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist-docs  # 与 vitepress config 中 outDir 一致

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

🔍 注意：

• pnpm docs:build 应输出到 ./dist-docs（或你指定的目录）
• upload-pages-artifact 的 path 必须指向该目录

---

步骤 3（可选）：使用 enablement: true 自动启用 Pages

虽然推荐手动开启，但你也可以在 configure-pages 中加：

- name: Setup Pages
  uses: actions/configure-pages@v4
  with:
    enablement: true  # 自动启用 Pages（需 repo admin 权限）

但这不能替代首次 UI 配置，尤其在新仓库中可能仍会失败。最可靠的方式仍是手动在 Settings → Pages 中选择 “GitHub Actions” 作为源。

---

🧪 验证是否成功

• 成功后，workflow 日志中会显示：

  Environment URL: https://<your-name>.github.io/<repo>/
  

• 访问该 URL 即可看到你的文档站点。

---

❌ 常见误区

误区	正确做法
以为只要写 workflow 就能自动开通 Pages	必须在 Settings → Pages 中显式启用
把 Pages 源设为 gh-pages 分支	若用 Actions 部署，必须选 “GitHub Actions”
构建输出目录和 upload-pages-artifact 路径不一致	确保 vitepress build 输出路径 = path

---

完成上述步骤后，重新触发 workflow（如 push 一次），应该就能成功部署了！