Question

你可以使用 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 选项。

astro.config.mjs

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 参数：

• 你的页面是由根文件夹所提供。
• 你的源码存储库是位于 https://github.com/<USERNAME>/<USERNAME>.github.io。

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

警告

当配置了这个值后，你所有的内部页面链接都必须以你的 base 值作为前缀：

<a href="/my-repo/about">关于本站</a>

查看更多关于配置 base 值的信息。

在 GitHub Pages 上使用自定义域名

设置一个自定义域

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

public/CNAME

sub.mydomain.com

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

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

astro.config.mjs

import { defineConfig } from 'astro/config'


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

配置 GitHub Action

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

   注意

   Astro GitHub Action 接受几个可选的设置项。你可以通过取消注释 with: 行和你想要使用的设置值来提供这些设置项。

   警告

   官方提供的 Astro GitHub Action 会扫描项目根目录下的 lockfile 以检测你首选的包管理器（npm、yarn、pnpm 或 bun）。你应该将包管理器自动生成的 package-lock.json、yarn.lock、pnpm-lock.yaml 或 bun.lockb 文件提交到你的存储库。

2. 在 GitHub 上，跳转到存储库的 Settings 选项卡并找到设置的 Pages 部分。

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

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

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

更多部署指南

• 

  Netlify

• 

  Vercel

• 

  Deno Deploy

• 

  GitHub Pages

• 

  GitLab Pages

• 

  Cloudflare Pages

• 

  AWS

• 

  AWS via Flightcontrol

• 

  AWS via SST

• 

  Google Cloud

• 

  Firebase Hosting

• 

  Heroku

• 

  Microsoft Azure

• 

  Buddy

• 

  Edgio

• 

  Fly.io

• 

  Render

• 

  Stormkit

• 

  Surge

• 

  Cleavr

• 

  Kinsta

• 

  Deta Space

• 

  Zeabur

• 

  Zerops

Recipes