手把手教程：用 Astro 构建静态博客并部署到 GitHub Pages（含自定义域名）

前言

Astro 是目前最火的静态站点生成器之一，支持 React、Vue、Svelte 等主流框架按需加载交互（Islands 架构），默认只输出纯 HTML + CSS + JS，体积极小。本文以 Astro 官方 Starter 为例，演示从零搭建一个个人博客，部署到 GitHub Pages，并绑定自定义域名启用 HTTPS。全程不需要服务器，也不需要花钱。

1. 环境准备

• Node.js >= 18（推荐 LTS 版本）
• Git
• 一个 GitHub 账号
  -（可选）一个自定义域名，例如在阿里云/腾讯云/Cloudflare 购买的域名

2. 创建 Astro 项目

npm create astro@latest my-blog
cd my-blog
npm install

创建向导中：

• 模板选 blog（或 minimal 也行，本文演示 blog 模板）。
• 类型检查选 TypeScript。
• 其他选默认回车即可。

安装完成后本地预览：

npm run dev

浏览器打开 localhost:4321 即可看到博客预览。

3. 编写第一篇博客文章

在 src/content/blog/ 目录下新建一篇 Markdown 文件，例如 hello-world.md：

---
title: "我的第一篇博客"
description: "用 Astro 搭建的个人博客正式上线。"
pubDate: 2026-10-20
heroImage: "../../assets/default-hero.jpg"
tags:
  - Astro
  - 博客
---

欢迎！这是基于 Astro 的博客第一篇文章。

Astro 的 Content Collections 会自动把这些文件渲染为带路由的文章页，例如 /posts/hello-world/。

4. 构建静态产物

npm run build

构建完成后，dist/ 目录就是纯静态文件（HTML/CSS/JS/图片）。GitHub Pages 需要的就是这些文件。

同时打开 astro.config.mjs，确保输出格式是 static（Astro 默认就是 static，无需额外配置）：

// astro.config.mjs（关键项）
import { defineConfig } from 'astro/config';

export default defineConfig({
  // 如果用自定义域名，base 保持空字符串 / ；
  // 如果部署在 user.github.io/<repo>，base 写成 '/<repo>'。
  // base: '/',
  output: 'static',
});

5. 部署到 GitHub Pages

5.1 推送仓库并开启 Pages

把项目推送到 GitHub（仓库名建议用小写，例如 my-blog），然后在仓库的 Settings → Pages → Source 中选择：

• 分支：main（或 master）
• 目录：/dist 并不直接可选，Astro 的惯例是把 dist 推到 main 分支根目录；更简洁的做法是用 GitHub Actions 自动构建（见 5.3）。

如果你不想用 Actions，也可以把 dist/ 的内容手动 git add 推到一个独立的 gh-pages 分支，然后在 Pages 设置中选择 gh-pages 分支的 / (root)。

仓库开启 Pages 后，站点会发布到 `<用户名>.github.io/<仓库名>`（组织仓库是 `<组织>.github.io/<仓库名>`）。

5.2 配置 DNS

到域名的 DNS 管理后台，添加一条 CNAME 记录，把子域名指向 GitHub Pages：

根域名（裸域名，如 example.com）按 RFC 不能直接设 CNAME。如果需要裸域名也生效，可以使用 Cloudflare 的 CNAME flattening（代理/橙云），或使用 DNS 服务商提供的 ALIAS/ANAME/URL 型记录 指向同样的 GitHub Pages 地址。

5.3 在仓库根目录放 CNAME 文件

在仓库的 main 分支根目录，新建一个没有后缀的文件，文件名就是 CNAME（注意全大写），文件内容只写你的目标域名一行，例如：

blog.example.com

GitHub Pages 检测到这个文件后，会自动为该域名签发 HTTPS 证书（通过 Let’s Encrypt）。通常几分钟到几十分钟后，访问 https://blog.example.com 就能看到博客，且浏览器地址栏显示安全锁。

5.4 用 GitHub Actions 自动化部署（推荐）

在仓库根目录创建 .github/workflows/deploy.yml：

name: 部署到 GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: 安装依赖并构建
        run: |
          npm ci
          npm run build
      - 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

提交并推送后，每次向 main 推送都会自动构建并发布。比手动推 dist 更不容易出错。

6. 常见问题与注意事项

• base 路径：如果你用的是 <用户名>.github.io/<仓库> 这种子路径地址，必须在 astro.config.mjs 里把 base 设成对应的子路径，否则图片和样式引用会 404。
• HTTPS：只有绑定了自定义域名才会自动启用 HTTPS；直接使用 <用户名>.github.io/... 地址本身也是 HTTPS，但自定义域名的证书由 GitHub Pages 在检测到 CNAME 文件后自动签发。
• 缓存：Cloudflare 或浏览器缓存可能导致 CNAME 生效时间变长，遇到 52x/连接失败可先 Ctrl+F5 或换 Incognito 验证。
• Astro 的 adapter：本文走的是 GitHub Pages（纯静态），所以使用默认的 static 输出即可；如果将来想部署到 Netlify/Vercel，Astro 也提供了对应的 adapter，切换时只要改 adapter 并推送到对应平台。

结语

Astro + GitHub Pages + 自定义域名的组合，门槛低、成本为零、速度也不差，非常适合开发者做个人笔记、作品集或者技术博客。把这篇教程里的 Actions workflow 直接复制到仓库，基本就能实现「写文章 → 提交 → 自动上线」的完整闭环。

有问题的话欢迎在评论区交流。祝搭建顺利！