1. 创建仓库 <username>.github.io#

在创建仓库页面中，依次填入以下内容：

• Repository name：<username>.github.io
• Description：Personal blog website hosted on GitHub Pages

直接点击 Create Repository 按钮创建仓库，无需调整其他选项。

2. Fork 原项目到我的仓库#

打开项目 Firefly 主页，点击页面右上角的 Fork 按钮，无需修改任何选项，直接点击 Create fork 按钮即可。

NOTE

原项目使用 master 作为默认分支，而非现在常见的 main。

3. 将我的 Fork 仓库 clone 到本地#

在项目目录下运行：

1
git clone git@github.com:<username>/Firefly.git
2
code Firefly

这将用 VSCode 打开刚拉取下来的项目。

4. 在本地仓库创建并切换到 custom 分支#

在项目目录下运行：

1
git branch custom
2
git checkout custom

5. 禁用会报错的 workflow 文件#

在实操过程中，我发现 .github/workflows 目录下工作流文件 biome.yml 和 build.yml 运行时会报错。考虑到后续可能需要修改，暂不删除，而是通过在文件名末尾添加 .disabled 后缀来禁用它们。

6. 修改 workflow 文件以自动部署到另一个仓库#

根据之前的思路：每当接收到推送事件时，自动构建静态网站，并将生成的文件推送到 <username>.github.io 仓库。

需要修改 .github/workflows 目录下的 deploy.yml 文件：

1
name: Deploy to Pages Branch
2

3
on:
4
  # 每次推送到 `main` 分支时触发这个"工作流程"
5
  # 如果你使用了别的分支名，请按需将 `main` 替换成你的分支名
6
  # 每次推送到 `custom` 分支时触发这个"工作流程"
7
  push:
8
    branches: [ main ]
9
    branches: [ custom ]
10
  # 允许你在 GitHub 上的 Actions 标签中手动触发此"工作流程"
11
  workflow_dispatch:
12

13
# 需要写入权限来推送到pages分支
14
permissions:
15
  contents: write
16

17
jobs:
18
  build-and-deploy:
19
    runs-on: ubuntu-latest
20
    steps:
21
      - name: Checkout your repository using git
22
        uses: actions/checkout@v4
23

24
      - name: Setup Node.js
25
        uses: actions/setup-node@v4
26
        with:
27
          node-version: '20'
28

29
      - name: Setup pnpm
30
        uses: pnpm/action-setup@v4
31
        with:
32
          version: 9.14.4
33
          run_install: false
34

35
      - name: Install dependencies
36
        run: pnpm install --no-frozen-lockfile
37

38
      - name: Build site
39
        run: pnpm run build
40

41
      - name: Deploy to pages branch
42
        uses: JamesIves/github-pages-deploy-action@v4
43
        with:
44
          branch: pages # 部署到pages分支
45
          token: ${{ secrets.GH_PAT }} # 需要在仓库的Settings->Secrets and variables->Actions中添加GH_PAT，该Token需要有写入权限
46
          repository-name: <username>/<username>.github.io # 你的GitHub Pages仓库名称
47
          branch: main # 部署到custom分支
48
          folder: dist # Astro默认构建输出目录
49
          clean: true # 清理目标分支中的旧文件

7. 创建 PAT#

点击 GitHub 账号右上角头像 → 选择 Settings → 左侧边栏点击 Developer settings → 点击 Personal access tokens → 选择 Fine-grained tokens → 点击右侧 Generate new token。

在创建页面中，依次填写以下内容：

• Token name： 为令牌命名（如：blog-deploy）
• Expiration： 设置过期时间（如：90 days）
• Repository access：选择 Only select repositories，并仅勾选 <username>.github.io
• Permissions：点击 Add permissions，添加以下三项权限：
  • Contents → 设为 Read and write（用于更改仓库内容）
  • Pages → 设为 Read and write（用于部署 GitHub Pages）
  • Metadata → 保持默认（Read-only，自动包含）

这样可避免生成的令牌可访问的仓库范围过广或权限过大。

点击 Generate token 按钮，并记录下生成的令牌。

8. 创建环境变量#

在我的 Fork 仓库页面，点击顶部导航栏的 Settings → 左侧边栏点击 Secrets and variables → 选择下拉项 Actions → 点击右侧 New repository secret 按钮。

在创建页面中，依次填写以下内容：

• Name：GH_PAT
• Secret：粘贴刚才保存的令牌

点击 Add secret 按钮。

9. 修改部署地址#

根据 Astro 官方文档里的部署指南，需要将 astro.config.mjs 文件里的 site 改成 GitHub Pages 部署地址：

1
export default defineConfig({
2
    site: "https://demo-firefly.netlify.app/",
3
    site: "https://<username>.github.io",
4
})

10. 添加 .nojekyll 文件#

在使用 Astro 构建项目时，Astro 会在 dist 输出目录中生成一个 _astro 文件夹，其中包含 JavaScript 代码和静态资源。

GitHub Pages 对于基于分支自动构建的方式，会默认启用 Jekyll 构建引擎，而 Jekyll 会自动忽略所有以下划线 _ 开头的文件和目录。

因此，当基于分支把 Astro 构建出的 dist 目录部署到 GitHub Pages 时，_astro 目录会被 Jekyll 忽略，不会被发布，这导致网页显示不正常，功能异常。

解决办法很简单，在部署目录 dist 添加一个名为 .nojekyll 的空文件，用于告诉 GitHub Pages：不要用 Jekyll 处理这个站点。

实际上，在我的项目 public 目录下添加空文件 .nojekyll 即可。因为 Astro 在构建站点时，会将它复制到 dist 部署目录。

在项目目录下运行：

1
touch public/.nojekyll

11. 提交 commit 并推送代码到远程仓库#

在项目目录下运行：

1
git rm .github/workflows/biome.yml
2
git add .github/workflows/biome.yml.disabled
3
git rm .github/workflows/build.yml
4
git add .github/workflows/build.yml.disabled
5
git commit -m "chore: 临时禁用冗余的 workflow 文件"
6

7
git add .github/workflows/deploy.yml
8
git commit -m "chore: 调整工作流文件中的引用 main 为 custom，并使打包后的文件部署到另一个仓库的 main 分支上"
9

10
git add astro.config.mjs
11
git commit -m "修改部署地址"
12

13
git add public/.nojekyll
14
git commit -m "fix: 添加文件 public/.nojekyll 以正确提供 _astro 目录中的文件"
15

16
git push origin custom

12. 验证部署结果#

• 打开我的 Fork 仓库页面，点击顶部导航栏的 Actions
• 等待最新的工作流运行完成，确保没有发生错误
• 打开 <username>.github.io 仓库页面，可看到已部署好的站点文件。GitHub Pages 会自动从 main 分支部署站点，无需额外操作
• 点击顶部导航栏的 Actions，等待 GitHub Pages 部署站点完成
• 访问 https://<username>.github.io，观察页面是否正常显示
• 按 F12 键打开开发人员工具，切换到控制台面板，检查其中是否有严重错误报告信息