部署你的 Astro 站点至 GitHub Pages

你可以使用 GitHub Pages 直接从 GitHub 上的存储库托管 Astro 网站。

如何部署

你可以使用 GitHub Actions 将 Astro 站点自动构建和部署到 GitHub Pages。为此，你的源代码必须托管在 GitHub 上。

Astro 维护了一个官方的 GitHub Action withastro/action 来帮助你部署项目；你只需很少的配置，就可以完成部署。按照下面的说明可以将你的 Astro 站点部署到 GitHub Pages，如果你需要更多信息，请参阅这个包的 README。

为 GitHub Pages 配置 Astro

部署到 `github.io` 网址

在 astro.config.mjs 中配置文件设置 site 和 base 选项。

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
  base: 'my-repo',
})

`site`

site 的值必须是以下之一：

基于你的用户名的以下网址：https://<username>.github.io
为 GitHub 组织的私有页面自动生成的随机网址：https://<random-string>.pages.github.io/

`base`

可能需要为 base 设置一个值，以便 Astro 将你的仓库名称（例如 /my-repo）视为你网站的根目录。

base 的值应该是你的仓库名称，以正斜杠开头，例如 /my-blog。这样做是为了让 Astro 理解你的网站根目录是 /my-repo，而不是默认的 /。

在 GitHub Pages 上使用自定义域名

你可以选择通过将一个 ./public/CNAME 文件添加到你的项目中，来设置自定义域：

sub.mydomain.com

这会将你的站点部署在你的自定义域而不是 <YOUR_USERNAME>.github.io。不要忘记为你的域名提供商配置 DNS。

要配置 Astro 以在 GitHub Pages 上使用自定义域名，请将你的域名设置为 site 的值。不要为 base 设置值：

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://example.com',
})

配置 GitHub Action

在你的项目中的 .github/workflows/ 目录创建一个新文件 deploy.yml，并粘贴以下 YAML 配置信息。

name: Deploy to GitHub Pages

on:
  # 每次推送到 `main` 分支时触发这个“工作流程”
  # 如果你使用了别的分支名，请按需将 `main` 替换成你的分支名
  push:
    branches: [ main ]
  # 允许你在 GitHub 上的 Actions 标签中手动触发此“工作流程”
  workflow_dispatch:

# 允许 job 克隆 repo 并创建一个 page deployment
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v3
        # with:
          # path: . # 存储库中 Astro 项目的根位置。（可选）
          # node-version: 20 # 用于构建站点的特定 Node.js 版本，默认为 20。（可选）
          # package-manager: pnpm@latest # 应使用哪个 Node.js 包管理器来安装依赖项和构建站点。会根据存储库中的 lockfile 自动检测。（可选）

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4