将 Astro 站点部署到 GitHub Pages

你可以使用 GitHub Actions 直接从 GitHub.com 上的存储库托管静态预渲染的 Astro 网站。

¥You can use GitHub Pages to host a static, prerendered Astro website directly from a repository on GitHub.com using GitHub Actions.

如何部署

¥How to deploy

Astro 维护着一个配置极少的 用于将项目部署到 GitHub Pages 的官方 Astro GitHub Action，是部署到 GitHub Pages 的推荐方式。

¥Astro maintains an official Astro GitHub Action to deploy your project to a GitHub Pages with very little configuration and is the recommended way to deploy to GitHub Pages.

请按照以下说明使用 GitHub Action 将你的 Astro 网站部署到 GitHub Pages。这将从你的存储库在 GitHub URL（例如 https://<username>.github.io/<my-repo>）创建一个网站。部署完成后，你可以选择使用 配置自定义域 将你的 GitHub Pages 站点部署到你首选的域名（例如 https://example.com）。

¥Follow the instructions below to use the GitHub Action to deploy your Astro site to GitHub Pages. This will create a website from your repository at a GitHub URL (e.g. https://<username>.github.io/<my-repo>). Once deployed, you can optionally configure a custom domain to deploy your GitHub Pages site at your preferred domain (e.g. https://example.com).

1. Create a new file in your project at .github/workflows/deploy.yml and paste in the YAML below.

   deploy.yml

   name: Deploy to GitHub Pages
   
   on:
     # Trigger the workflow every time you push to the `main` branch
     # Using a different branch name? Replace `main` with your branch’s name
     push:
       branches: [ main ]
     # Allows you to run this workflow manually from the Actions tab on GitHub.
     workflow_dispatch:
   
   # Allow this job to clone the repo and create a 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@v5
         - name: Install, build, and upload your site
           uses: withastro/action@v5
           # with:
             # path: . # The root location of your Astro project inside the repository. (optional)
             # node-version: 24 # The specific version of Node that should be used to build your site. Defaults to 22. (optional)
             # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
             # build-cmd: pnpm run build # The command to run to build your site. Runs the package build script/task by default. (optional)
           # env:
             # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # Use single quotation marks for the variable value. (optional)
   
     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

   The Astro action can be configured with optional inputs. Provide these by uncommenting the with: line and the input you want to use.

   If your site requires any public environment variables, uncomment the env: line and add them there. (See the GitHub documentation on setting secrets for adding private environment variables.)

   Caution

   The official Astro action scans for a lockfile to detect your preferred package manager (npm, yarn, pnpm, or bun). You should commit your package manager’s automatically generated package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb file to your repository.

2. In your Astro config file, set site to the GitHub URL of your deployed site.

   astro.config.mjs

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

   The value for site must be one of the following:

   • The following URL based on your username: https://<username>.github.io
   • The random URL autogenerated for a GitHub Organization’s private page: https://<random-string>.pages.github.io/

3. In astro.config.mjs, configure a value for base (usually required).

   GitHub Pages will publish your website at an address that depends on both your username and your repository name (e.g. https://<username>/github.io/<my-repo>/). Set a value for base that specifies the repository for your website. This is so that Astro understands your website’s root is /my-repo, rather than the default /. You can skip this if your repository name matches the special <username>.github.io pattern (e.g. https://github.com/username/username.github.io/)

   Configure base as the repository’s name starting with a forward slash ( e.g. /my-repo):

   astro.config.mjs

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

   Internal links with base configured

   When this value is configured, all of your internal page links must be prefixed with your base value:

   <a href="/my-repo/about">About</a>

   See more about configuring a base value.

4. On GitHub, go to your repository’s Settings tab and find the Pages section of the settings.

5. Choose GitHub Actions as the Source of your site.

将更改推送到 Astro 项目仓库后，GitHub Action 会自动将其部署到你的 GitHub URL。

¥When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you at your GitHub URL.

将你的 GitHub URL 更改为自定义域名

¥Change your GitHub URL to a custom domain

按照上述说明使用 部署到 GitHub Pages（GitHub 地址） URL 完成 Astro 项目后，你可以配置自定义域名。这意味着用户可以通过自定义域名 https://example.com 而不是 https://<username>.github.io 访问你的网站。

¥Once your Astro project is deployed to GitHub pages at a GitHub URL following the previous instructions, you can configure a custom domain. This means that users can visit your site at your custom domain https://example.com instead of https://<username>.github.io.

1. Configure DNS for your domain provider.

2. Add a ./public/CNAME record to your project.

   Create the following file in your public/ folder with a single line of text that specifies your custom domain:

   public/CNAME

   sub.example.com

   This will deploy your site at your custom domain instead of user.github.io.

3. In your Astro config, update the value for site with your custom domain. Do not set a value for base, and remove one if it exists:

   astro.config.mjs

   import { defineConfig } from 'astro/config'
   
   export default defineConfig({
     site: 'https://example.com',
     base: '/my-repo'
   })

4. If necessary, update all your page internal links to remove the base prefix:

   <a href="/my-repo/about">About</a>

示例

¥Examples

• GitHub Pages 部署入门模板

• Starlight Flexoki 主题（生产环境）

• Expressive 代码颜色芯片（生产环境）站点）

• Starlight Markdown 区块（生产环境）

更多部署指南

• 

  AWS

• 

  通过 Flightcontrol 使用 AWS

• 

  通过 SST 使用 AWS

• 

  Azion

• 

  Buddy

• 

  Cleavr

• 

  Clever Cloud

• 

  Cloudflare

• 

  CloudRay

• 

  Deno Deploy

• 

  DeployHQ

• 

  Firebase

• 

  Fleek

• 

  Fly.io

• 

  GitHub Pages

• 

  GitLab Pages

• 

  Google Cloud

• 

  Heroku

• 

  Juno

• 

  Kinsta

• 

  Microsoft Azure

• 

  Netlify

• 

  Railway

• 

  Render

• 

  Seenode

• 

  Stormkit

• 

  Surge

• 

  Vercel

• 

  Zeabur

• 

  Zephyr Cloud

• 

  Zerops