Skip to content

将 Astro 站点部署到 GitHub Pages

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

¥You can use GitHub Pages to host an Astro website directly from a repository on GitHub.com.

如何部署

Section titled 如何部署

¥How to deploy

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

¥You can deploy an Astro site to GitHub Pages by using GitHub Actions to automatically build and deploy your site. To do this, your source code must be hosted on GitHub.

Astro 维护了官方的 withastro/action，只需很少的配置即可部署你的项目。按照以下说明将 Astro 站点部署到 GitHub 页面，如果需要更多信息，请参阅 包自述文件。

¥Astro maintains the official withastro/action to deploy your project with very little configuration. Follow the instructions below to deploy your Astro site to GitHub pages, and see the package README if you need more information.

为 GitHub Pages 配置 Astro

Section titled 为 GitHub Pages 配置 Astro

¥Configure Astro for GitHub Pages

部署到 github.io URL

Section titled 部署到 github.io URL

¥Deploying to a github.io URL

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

¥Set the site and base options in astro.config.mjs.

astro.config.mjs
import { defineConfig } from 'astro/config'


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

site

Section titled site

site 的值必须是以下之一：

¥The value for site must be one of the following:

  • 以下基于你的用户名的 URL：https://<username>.github.io

  • 为 GitHub 组织的私有页面 自动生成的随机 URL：https://<random-string>.pages.github.io/

base

Section titled base

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

¥A value for base may be required so that Astro will treat your repository name (e.g. /my-repo) as the root of your website.

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

¥The value for base should be your repository’s name starting with a forward slash, for example /my-blog. This is so that Astro understands your website’s root is /my-repo, rather than the default /.

使用带有自定义域的 GitHub 页面

Section titled 使用带有自定义域的 GitHub 页面

¥Using GitHub pages with a custom domain

要配置 Astro 以使用带有自定义域的 GitHub 页面，请将你的域设置为 site 的值。不要为 base 设置值：

¥To configure Astro for using GitHub pages with a custom domain, set your domain as the value for site. Do not set a value for base:

astro.config.mjs
import { defineConfig } from 'astro/config'


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

配置 GitHub 操作

Section titled 配置 GitHub 操作

¥Configure a GitHub Action

  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@v4
          - name: Install, build, and upload your site
            uses: withastro/action@v3
            # with:
              # path: . # The root location of your Astro project inside the repository. (optional)
              # node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 20. (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)
    

      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. On GitHub, go to your repository’s Settings tab and find the Pages section of the settings.

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

  4. Commit the new workflow file and push it to GitHub.

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

¥Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you.

More Deployment Guides

Astro 中文网 - 粤ICP备13048890号