Skip to content

Latest commit

 

History

History
145 lines (105 loc) · 5.82 KB

github.mdx

File metadata and controls

145 lines (105 loc) · 5.82 KB
Raw
title description type
部署你的 Astro 站点至 GitHub Pages
如何使用 GitHub Pages 将你的 Astro 网站部署到网络上。
deploy

import { Steps } from '@astrojs/starlight/components';

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

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）视为你网站的根目录。

:::note 如果出现了以下情况，则不要设置 base 参数：

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

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

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

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

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

在 GitHub Pages 上使用自定义域名

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

sub.mydomain.com

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

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

import { defineConfig } from 'astro/config'

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

配置 GitHub Action

1. 在你的项目中的 `.github/workflows/` 目录创建一个新文件 `deploy.yml`，并粘贴以下 YAML 配置信息。 
```yaml title="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@v3
        # 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
```

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

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

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

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

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

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