1. 从零开始部署 Firefly（流萤）Astro 博客并上线 GitHub Pages

直接给你最简可用版，照着复制粘贴就行

1. 项目地址#

GitHub：https://github.com/cccoder159/astro-firefly （如果觉得项目不错，给作者点个 ⭐ 吧！）

2. 环境准备（小白必看）#

在开始之前，需要先安装两个工具：

2.1 安装 Git#

Windows 用户：

访问 https://git-scm.com/download/win
下载最新版本，一路点击”Next”即可
安装完成后，打开命令行输入 git --version 验证

macOS 用户：

打开终端，输入：

1
git --version

如果没有安装，会提示你安装 Xcode Command Line Tools。

2.2 安装 Node.js#

Windows / macOS / Linux 用户：

访问 https://nodejs.org/
下载 LTS（长期支持版）推荐版本
双击安装包安装

安装完成后，打开命令行验证：

1
node --version
2
npm --version

看到版本号表示安装成功。

3. 本地快速运行#

先确保装了 Node.js（18+ 版本）

1
# 克隆项目
2
git clone https://github.com/cccoder159/astro-firefly.git
3
cd astro-firefly
4

5
# 安装依赖
6
npm install
7

8
# 本地预览
9
npm run dev

打开浏览器访问：http://localhost:4321

4. 基本配置（改个人信息）#

打开文件：src/config/siteConfig.ts

4.1 网站基本信息#

配置项	说明	示例
`title`	网站标题	”我的博客”
`subtitle`	网站副标题	”记录生活点滴”
`site_url`	网站域名	”https://example.com”
`description`	网站描述（SEO用）	“这是一个个人博客”

1
title: "我的博客",
2
subtitle: "记录生活点滴",
3
site_url: "https://example.com",
4
description: "这是一个个人博客",

4.2 导航栏配置#

配置项	说明
`navbar.title`	导航栏显示的标题
`navbar.logo`	logo 图标（可换图标）

4.3 功能开关#

配置项	说明
`pages.friends`	友链页面
`pages.sponsor`	赞助页面
`pages.guestbook`	留言板
`pages.bangumi`	番剧页面
`pages.gallery`	相册页面

设为 true 开启，false 关闭。

4.4 主题颜色#

1
themeColor: {
2
    hue: 250,        // 主题色相（0-360）
3
    fixed: false,    // 是否固定主题色
4
    defaultMode: "system",  // 默认模式：light/dark/system
5
},

4.5 其他常用配置#

配置项	说明
`categoryBar`	是否显示分类栏
`showLastModified`	是否显示最后修改时间
`sharePoster`	是否开启分享海报
`siteStartDate`	网站成立日期

5. 写文章#

文章放在：src/content/posts/xxx.md

格式示例：

1
---
2
title: 文章标题
3
date: 2026-04-18
4
categories: [分类]
5
tags: [标签1, 标签2]
6
---
7

8
这里写正文

6. 部署到 GitHub Pages#

方法一：使用 GitHub Actions 自动部署#

1. 创建 GitHub 仓库

在 GitHub 上创建一个新仓库，例如：astro-firefly

2. 上传代码到仓库

1
# 初始化 git
2
git init
3

4
# 添加所有文件
5
git add .
6

7
# 提交
8
git commit -m "first commit"
9

10
# 添加远程仓库（替换为你的仓库地址）
11
git remote add origin https://github.com/你的用户名/astro-firefly.git
12

13
# 推送
14
git branch -M main
15
git push -u origin main

3. 创建 GitHub Actions 工作流

在仓库中创建文件：.github/workflows/deploy.yml

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [main]
6

7
jobs:
8
  build:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12

13
      - name: Setup Node
14
        uses: actions/setup-node@v4
15
        with:
16
          node-version: 20
17

18
      - name: Install pnpm
19
        uses: pnpm/action-setup@v2
20
        with:
21
          version: 8
22

23
      - name: Install dependencies
24
        run: pnpm install
25

26
      - name: Build
27
        run: pnpm run build
28

29
      - name: Upload Pages artifact
30
        uses: actions/upload-pages-artifact@v3
31
        with:
32
          path: dist
33

34
  deploy:
35
    needs: build
36
    runs-on: ubuntu-latest
37
    permissions:
38
      pages: write
39
      id-token: write
40
    environment:
41
      name: github-pages
42
      url: ${{ steps.deployment.outputs.page_url }}
43
    steps:
44
      - name: Deploy to GitHub Pages
45
        id: deployment
46
        uses: actions/deploy-pages@v4

4. 配置 GitHub Pages

进入仓库 Settings → Pages：

Source 选择 GitHub Actions

5. 推送代码触发部署

1
git add .
2
git commit -m "add deploy workflow"
3
git push

等待几分钟后，你的博客就会上线：https://你的用户名.github.io/astro-firefly

方法二：手动部署#

1
# 构建项目
2
npm run build
3

4
# 安装 gh-pages（如果没安装）
5
npm install -g gh-pages
6

7
# 部署到 GitHub Pages
8
gh-pages -d dist

音乐

音乐