为什么需要这个 Skill
部署一个 Astro 静态站点到 GitHub Pages 涉及多个步骤：GitHub 认证、仓库创建或 Fork、项目配置修改、GitHub Actions 工作流编写、Pages 启用、自定义域名绑定、HTTPS 强制加密，以及最终的站点验证。每一步都可能遇到网络代理、Token 权限、API 参数格式等坑。
将这些经验沉淀为一个 Skill 后，其他 Agent 或开发者在遇到类似部署需求时，可以直接加载技能按步骤执行，而不必重复踩坑。
Skill 涵盖的 7 个阶段
整个 Skill 将部署流程拆分为 7 个独立但连续的阶段：
| 阶段 | 内容 | 关键操作 |
|---|---|---|
| Phase 1 | GitHub 认证 | Token 登录、代理配置、credential helper |
| Phase 2 | 仓库设置 | Fork 模板或新建仓库、remote 配置 |
| Phase 3 | 项目配置 | 修改 siteURL、创建 deploy.yml 工作流 |
| Phase 4 | 启用 Pages | 通过 API 配置构建类型和 CNAME |
| Phase 5 | 触发部署 | 手动触发工作流、监控构建状态 |
| Phase 6 | HTTPS 加密 | 启用强制加密、验证证书状态 |
| Phase 7 | 验证站点 | DNS 解析、HTTP 状态码、页面标题 |
实际部署记录
以下是使用该 Skill 部署 Mizuki 博客到 blog.xzones.top 的实际执行结果：
✓ 构建阶段: 41 秒✓ 部署阶段: 10 秒✓ HTTPS 状态: 200 OK✓ 页面标题: Mizuki - One demo website✓ SSL 证书: approved (有效期至 2026-10-22)从触发工作流到站点可访问，总耗时约 1 分钟。
踩过的坑与解决方案
Token 权限问题
GitHub Token 缺少 read:org scope 时，gh auth status 会报错。但实际操作个人仓库时这个 scope 并非必需，通过 GH_TOKEN 环境变量传 token 即可绕过 keyring 存储的限制。
API 布尔参数格式
启用 HTTPS 强制加密时，gh api 命令的参数格式有坑：
# 错误写法 — 会报 HTTP 422gh api repos/USER/REPO/pages -X PUT -f https_enforced=true
# 正确写法 — 使用 -F 传递布尔值gh api repos/USER/REPO/pages -X PUT -F https_enforced=true-f 将值作为字符串传递（"true"），-F 将值作为布尔值传递（true）。GitHub API 对类型有严格校验，用错就会 422。
工作流未自动触发
将 deploy.yml 推送到仓库后，有时不会自动触发首次运行。这时需要手动触发：
gh workflow run "Deploy to GitHub Pages" --repo USER/REPO --ref masterNode.js 20 弃用警告
GitHub Actions 运行时会提示 Node.js 20 已弃用，但这只是警告，不影响构建。后续可以通过升级 actions 版本（如 actions/checkout@v5）来消除。
工作流核心配置
部署工作流 deploy.yml 的核心结构如下：
permissions: contents: read pages: write id-token: write
concurrency: group: "pages" cancel-in-progress: false
jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: lts/* - uses: pnpm/action-setup@v4 with: run_install: false - run: pnpm install --frozen-lockfile - run: pnpm build env: ENABLE_CONTENT_SYNC: "false" - uses: actions/configure-pages@v5 - uses: actions/upload-pages-artifact@v3 with: path: dist
deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment uses: actions/deploy-pages@v4两个 Job 分离设计和部署，concurrency 确保同一时间只运行一个部署，避免冲突。
Skill 的复用价值
这个 Skill 不局限于 Mizuki 博客，适用于任何基于 Astro 的静态站点部署到 GitHub Pages 的场景。关键复用点包括：
- 通用工作流模板：
deploy.yml可直接用于任何 pnpm + Astro 项目 - API 操作脚本：Pages 启用、域名绑定、HTTPS 加密的
gh api命令 - 故障排查表：四类常见错误的快速定位指南
- Fork 同步策略：模板项目的上游更新流程
文件位置
Skill 文件位于项目根目录的 .trae/skills/astro-github-pages-deploy/SKILL.md，遵循 TRAE 技能规范，包含 frontmatter 元数据和完整的 Markdown 指令体。
如果你也在用 Astro 搭建博客并计划部署到 GitHub Pages，欢迎参考这个 Skill。它不能替你点 DNS 记录，但能让从代码到上线的每一步都有据可循。
If this article helped you, please share it with others!
Some information may be outdated