遇到的错误：
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”作为源。
- 打开你的 GitHub 仓库。
- 点击顶部菜单栏的 Settings。
- 在左侧边栏找到并点击 Pages（或直接访问
https://github.com/<your-name>/<repo>/settings/pages）。 - 在 Source 部分：
- Branch: 不要选
main或gh-pages！ - 而是选择 “GitHub Actions”（如下图）
- Branch: 不要选
- 点击 Save。
⚠️ 如果你没看到 “GitHub Actions” 选项，请先确保你的仓库里有
.github/workflows/*.yml文件（即已定义 Actions workflow），然后刷新页面。
步骤 2：确认你的 Workflow 使用了正确的 Pages Action 组合
一个标准的 VitePress + GitHub Pages 部署 workflow 应包含以下三步：
# .github/workflows/deploy.yml
name: Deploy Docs to Pageson:push:branches: [main] # 或你指定的分支jobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4with:fetch-depth: 0 # 必须！否则 VitePress 的 lastUpdated 可能出错- name: Setup Nodeuses: actions/setup-node@v4with:node-version: 20cache: pnpm- name: Install pnpmrun: npm install -g pnpm- name: Install dependenciesrun: pnpm install- name: Build docsrun: pnpm docs:build # 确保这个脚本能生成 ./dist-docs- name: Setup Pagesuses: actions/configure-pages@v4with:# 可选：自动启用 Pages（但首次仍建议手动开启）enablement: true- name: Upload artifactuses: actions/upload-pages-artifact@v3with:path: ./dist-docs # 与 vitepress config 中 outDir 一致- name: Deploy to GitHub Pagesid: deploymentuses: actions/deploy-pages@v4
🔍 注意：
pnpm docs:build应输出到./dist-docs（或你指定的目录）upload-pages-artifact的path必须指向该目录
步骤 3（可选）：使用 enablement: true 自动启用 Pages
虽然推荐手动开启，但你也可以在 configure-pages 中加：
- name: Setup Pagesuses: actions/configure-pages@v4with: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 一次），应该就能成功部署了！
