Astro 博客 GitHub Actions 自动部署到 GitHub Pages

完整记录如何将 Astro 博客通过 GitHub Actions 自动构建并部署到 GitHub Pages，包括私有仓库源码管理、公开仓库部署、自定义域名配置等全流程。

2026年5月10日建站 2 分钟阅读

最近将博客从 VitePress 迁移到了 Astro，并配置了完整的自动化部署流程。这篇文章记录整个部署方案的实现过程。

采用私有仓库管理源码 + 公开仓库部署的分离方案：

┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  私有仓库 (source)  │────▶│  GitHub Actions  │────▶│  公开仓库 (blog) │
│  mechanical-mars    │     │  自动构建部署   │     │  GitHub Pages   │
└─────────────────────┘     └──────────────────┘     └─────────────────┘
                                                              │
                                                              ▼
                                                    ┌─────────────────┐
                                                    │  izqy.top  │
                                                    │   自定义域名    │
                                                    └─────────────────┘

源码安全：核心代码和敏感配置存储在私有仓库
自动化：推送到 main 分支即自动触发构建和部署
分离清晰：构建产物与源码完全分离
成本零：完全使用 GitHub 免费服务

源码仓库（私有）：

名称：mechanical-mars（或其他你喜欢的名字）
可见性：Private
用途：存储 Astro 源码和配置文件

部署仓库（公开）：

名称：blog（或 用户名.github.io）
可见性：Public
用途：接收构建产物，开启 GitHub Pages

在本地终端执行：

# 生成 ed25519 密钥对
ssh-keygen -t ed25519 -C "deploy-key" -f deploy_key -N ""

# 查看公钥（添加到 GitHub Deploy keys）
cat deploy_key.pub

# 查看私钥（添加到 GitHub Secrets）
cat deploy_key

私钥内容格式：

-----BEGIN OPENSSH PRIVATE KEY-----
xxx...
xxx...
-----END OPENSSH PRIVATE KEY-----

打开部署仓库（ZhengQinyu/blog）
进入 Settings → Deploy keys
点击 Add deploy key
Title: GitHub Actions Deploy
Key: 粘贴 deploy_key.pub 的公钥内容
✅ 勾选 Allow write access
点击 Add key

在源码仓库创建 .github/workflows/deploy.yml：

name: 构建并推送

on:
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 检出
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 安装 pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 9

      - name: 安装 Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: 下载依赖
        run: pnpm install

      - name: 构建
        run: pnpm build
        env:
          SITE_URL: ${{ vars.SITE_URL }}
          PUBLIC_GITHUB_HANDLE: ${{ vars.PUBLIC_GITHUB_HANDLE || github.repository_owner }}
          PUBLIC_GITHUB_REPO: ${{ vars.PUBLIC_GITHUB_REPO || github.event.repository.name }}
          PUBLIC_GISCUS_REPO: ${{ vars.PUBLIC_GISCUS_REPO }}

      - name: 添加 .nojekyll 文件
        run: touch ./dist/.nojekyll

      - name: 部署到公共仓库
        uses: peaceiris/actions-gh-pages@v4
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: ${{ vars.EXTERNAL_REPOSITORY }}
          publish_branch: main
          publish_dir: ./dist
          force_orphan: true

.nojekyll 文件：必须创建，否则 GitHub Pages 会忽略以下划线开头的目录（如 _astro）
force_orphan: true：每次部署都是全新提交，避免历史记录累积
deploy_key：使用 SSH 密钥方式推送，比 GITHUB_TOKEN 更安全可靠

在源码仓库（mechanical-mars）设置：

Name	Value
`ACTIONS_DEPLOY_KEY`	`deploy_key` 文件的私钥内容

Name	Value	说明
`EXTERNAL_REPOSITORY`	`ZhengQinyu/blog`	部署目标仓库
`SITE_URL`	`https://izqy.top`	站点 URL
`PUBLIC_GISCUS_REPO`	`ZhengQinyu/blog`	Giscus 评论仓库（可选）

在部署仓库（blog）设置：

进入 Settings → Pages
Source 选择 Deploy from a branch
Branch 选择 main，文件夹 /(root)
Custom domain 填写：izqy.top
✅ 勾选 Enforce HTTPS
点击 Save

在你的域名提供商（如阿里云、腾讯云等）添加 CNAME 记录：

类型	主机记录	记录值
CNAME	`blog`	`zhengqinyu.github.io`

DNS 生效通常需要 5-30 分钟。首次配置 SSL 证书可能需要 1 小时。

完成以上步骤后：

向源码仓库推送任意修改
访问 Actions 页面查看构建状态
构建成功后，访问 https://izqy.top 查看站点

问题	解决方案
`_astro` 目录 404	确认 `.nojekyll` 文件已创建
部署失败权限错误	检查 Deploy Key 是否有写权限
DNS 不生效	等待 30 分钟，或使用 `dig izqy.top` 检查
HTTPS 证书错误	等待 1 小时让 GitHub 生成证书

这套方案实现了：

✅ 源码私有，部署公开
✅ 推送即自动部署
✅ 自定义域名 + HTTPS
✅ 零成本（GitHub 免费服务）

适合个人博客、项目文档等静态站点的部署需求。

GitHub Pages 部署指南 - GitHub Pages 基础部署教程
VitePress 博客初始化 - 博客平台迁移前的 VitePress 部署方案

评论