跳转到内容

部署你的 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 Pages 配置 Astro

部署到 github.io 网址

段落标题 部署到 github.io 网址

astro.config.mjs 中配置文件设置 sitebase 选项。

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

site 的值必须是以下之一:

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

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

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

在 GitHub Pages 上使用自定义域名

段落标题 在 GitHub Pages 上使用自定义域名

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

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
site: 'https://example.com',
})
  1. 在你的项目中的 .github/workflows/ 目录创建一个新文件 deploy.yml,并粘贴以下 YAML 配置信息。

    deploy.yml
    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@v2
    # 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
  2. 在 GitHub 上,跳转到存储库的 Settings 选项卡并找到设置的 Pages 部分。

  3. 选择 GitHub Actions 作为你网站的 Source,然后按 Save

  4. 提交(commit)这个新的“工作流程文件”(workflow file)并将其推送到 GitHub。

你的网站现在应该已完成发布了!当你将更改推送到 Astro 项目的存储库时,GitHub Action 将自动为你部署它们。

更多部署指南