跳转到内容

部署你的 Astro 站点至 GitHub Pages

你可以使用 GitHub Pages ，通过 GitHub Actions 直接从 GitHub.com 上的代码仓库托管静态的、预渲染的 Astro 网站。

如何部署

Section titled “如何部署”

Astro 维护了一个 官方的 Astro GitHub Action，只需进行极少的配置即可将你的项目部署到 GitHub Pages，这是部署到 GitHub Pages 的推荐方式。

按照以下说明使用 GitHub Action 将你的 Astro 站点部署到 GitHub Pages。这将在 GitHub URL（例如：https://<username>.github.io/<my-repo>）上从你的代码仓库创建一个网站。部署完成后，你可以选择 配置自定义域名，将你的 GitHub Pages 网站部署到你偏好的域名（例如：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@v5
          - name: Install, build, and upload your site
            uses: withastro/action@v5
            # with:
              # path: . # 存储库中 Astro 项目的根位置。（可选）
              # node-version: 20 # 用于构建站点的特定 Node.js 版本，默认为 20。（可选）
              # package-manager: pnpm@latest # 应使用哪个 Node.js 包管理器来安装依赖项和构建站点。会根据存储库中的 lockfile 自动检测。（可选）
              # build-cmd: pnpm run build # 用于构建你的网站的命令。默认运行软件包的构建脚本或任务。（可选）
            # env:
              # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # 对变量值使用单引号。（可选）
    

      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 action。要使用这些输入，请取消注释 with: 这一行以及你想要使用的输入。

    如果你的网站需要任何公共环境变量，取消注释 env: 行，然后将其添加在那里。（详见 GitHub 文档中关于添加私有环境变量的私密变量设置。）

  2. 在你的 Astro 配置文件中，将 site 设置为你已部署站点的 GitHub URL。

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

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

    site 的值必须满足以下条件之一：

    • The following URL based on your username: https://<username>.github.io
    • 根据你的用户名，链接是：https://<username>.github.io
    • 对于 GitHub 组织的私有页面，链接是：https://<random-string>.pages.github.io/

  3. 在 astro.config.mjs 中，配置 base 的值（通常需要）。

    GitHub Pages 会将你的网站发布到一个取决于你的用户名和仓库名称的地址（例如：https://<username>/github.io/<my-repo>/）。 为 base 设置一个值，指定你网站的仓库。这样 Astro 才能理解你网站的根是 /my-repo，而不是默认的 /。如果你的仓库名称匹配特殊模式 <username>.github.io（例如：https://github.com/username/username.github.io/），你可以跳过这一步。

    将 base 设置为仓库名称，以正斜杠开头（例如：/my-repo）：

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

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

  4. 在 GitHub 上，进入你的仓库的 Settings 选项卡，然后找到设置中的 Pages 部分。

  5. 选择 GitHub Actions 作为你的网站 Source。

当你将更改推送到 Astro 项目的代码库时，GitHub Action 会自动将这些更改部署到你的 GitHub 网址。

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

Section titled “将你的 GitHub 链接更改为自定义域名”

按照前面的说明将 Astro 项目 部署到 GitHub Pages 并获得 GitHub URL 之后，你就可以配置自定义域名。这意味着用户可以通过你的自定义域名 https://example.com 访问你的网站，而不是使用 https://<username>.github.io。这意味着用户可以通过你的自定义域名 https://example.com 访问你的网站，而不是使用 https://<username>.github.io。

  1. 为你的域名提供商配置 DNS。

  2. 在你的项目中添加一个 ./public/CNAME 记录。

    在你的 public/ 文件夹中创建下列文件，并在其中写入一行用于指定自定义域名的文本：

    public/CNAME
    sub.example.com

    这样你的网站会部署到自定义域名，而不是 user.github.io。

  3. 在你的 Astro 配置中，用你的自定义域名更新 site 的值。不要为 base 设置任何值，如果已经存在则将其删除。

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

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

  4. 如有需要，请更新你所有页面的内部链接以移除 base 前缀：

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

示例

Section titled “示例”

更多部署指南

贡献 社区 赞助