基于 Astro + Firefly 的博客部署到 Cloudflare Pages 完整指南

📖 前言#

在现代 Web 开发中，选择合适的部署平台对于博客的性能和用户体验至关重要。Cloudflare Pages 作为一个全球分布式边缘计算平台，提供了出色的性能、可靠性和免费的额度，非常适合部署静态网站和 JAMstack 应用。

本文将详细记录我如何将基于 Astro 5.14.7 和 Firefly 主题的个人博客从本地开发环境成功部署到 Cloudflare Pages 的全过程，包括遇到的问题和解决方案。

🎯 技术栈概览#

在开始之前，先了解一下本博客项目使用的技术栈：

前端框架: Astro 5.14.7
博客主题: Firefly (基于 Fuwari)
UI 框架: Tailwind CSS + Svelte 5.41.1
包管理器: pnpm 9.14.4
部署平台: Cloudflare Pages + Workers
CI/CD: GitHub Actions
内容管理: Decap CMS (原 Netlify CMS)
搜索功能: Pagefind

🔧 项目配置详解#

1. Cloudflare 适配器配置#

首先需要安装并配置 Cloudflare 适配器，使 Astro 能够在 Cloudflare Workers 环境中运行。

安装依赖：

1
pnpm add @astrojs/cloudflare

在 astro.config.mjs 中配置适配器：

1
import cloudflare from "@astrojs/cloudflare";
2
import { defineConfig } from "astro/config";
3

4
export default defineConfig({
5
  site: "https://blog-4qk.pages.dev/",
6
  base: "/",
7
  trailingSlash: "always",
8

9
  // 添加 Cloudflare 适配器
10
  adapter: cloudflare(),
11

12
  // 其他配置...
13
});

关键配置说明：

site: 部署后的完整 URL，用于生成正确的 sitemap 和 RSS 链接
trailingSlash: "always": 确保所有 URL 都以斜杠结尾，避免重定向问题
adapter: cloudflare(): 使用 Cloudflare 适配器，自动处理 SSR 和边缘函数

2. 构建配置优化#

在 package.json 中配置构建脚本：

1
{
2
  "scripts": {
3
    "dev": "astro dev",
4
    "build": "astro build && pagefind --site dist && node scripts/fix-routes.js",
5
    "preview": "astro preview",
6
    "check": "astro check || true"
7
  }
8
}

构建流程解析：

astro build: 构建静态资源和边缘函数
pagefind --site dist: 为博客生成全文搜索索引
node scripts/fix-routes.js: 修复路由规则（如有需要）

3. Wrangler 配置（可选）#

虽然 Cloudflare Pages 可以自动检测 Astro 项目，但创建 wrangler.jsonc 可以提供更细粒度的控制：

1
{
2
  "name": "blog",
3
  "compatibility_date": "2025-11-12",
4
  "pages_build_output_dir": "./dist"
5
}

🚀 部署流程#

方式一：通过 Cloudflare Dashboard 手动部署#

Step 1: 构建项目#

在本地完成开发后，执行构建命令：

1
pnpm build

构建成功后会在项目根目录生成 dist 文件夹。

Step 2: 安装 Wrangler CLI#

1
pnpm add -D wrangler

Step 3: 登录 Cloudflare#

1
pnpm wrangler login

这会打开浏览器窗口，完成 OAuth 认证。

Step 4: 部署到 Cloudflare Pages#

1
pnpm wrangler pages deploy dist --project-name=blog

首次部署会自动创建项目，后续部署会更新现有项目。

部署成功输出示例：

1
✨ Success! Uploaded 245 files (3.2 sec)
2
✨ Deployment complete! Take a peek over at https://blog-4qk.pages.dev

方式二：GitHub Actions 自动部署（推荐）#

自动化部署能够在每次推送代码时自动触发构建和部署，大大提高效率。

Step 1: 创建 GitHub Actions 工作流#

在项目根目录创建 .github/workflows/deploy.yml：

1
name: Deploy to Cloudflare Pages
2

3
on:
4
  push:
5
    branches:
6
      - main  # 或者你的默认分支名称
7

8
jobs:
9
  deploy:
10
    runs-on: ubuntu-latest
11
    permissions:
12
      contents: read
13
      deployments: write
14

15
    steps:
16
      - name: Checkout
17
        uses: actions/checkout@v4
18

19
      - name: Setup Node.js
20
        uses: actions/setup-node@v4
21
        with:
22
          node-version: '20'
23

24
      - name: Install pnpm
25
        uses: pnpm/action-setup@v4
26
        with:
27
          version: 9.14.4
28

29
      - name: Install dependencies
30
        run: pnpm install --frozen-lockfile
31

32
      - name: Build
33
        run: pnpm build
34

35
      - name: Deploy to Cloudflare Pages
36
        uses: cloudflare/pages-action@v1
37
        with:
38
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
39
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
40
          projectName: blog
41
          directory: dist
42
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

Step 2: 配置 GitHub Secrets#

在 GitHub 仓库设置中添加以下 Secrets：

获取 Cloudflare API Token
- 访问 Cloudflare API Tokens
- 点击 “Create Token”
- 选择 “Edit Cloudflare Workers” 模板
- 确保包含权限：Account - Cloudflare Pages (Edit)
- 复制生成的 Token
获取 Cloudflare Account ID
- 访问 Cloudflare Dashboard
- 在右侧栏可以看到 “Account ID”
- 复制该 ID
在 GitHub 中配置
- 进入仓库 Settings → Secrets and variables → Actions
- 添加两个 Repository secrets：
  - CLOUDFLARE_API_TOKEN: 粘贴 API Token
  - CLOUDFLARE_ACCOUNT_ID: 粘贴 Account ID

Step 3: 推送代码触发部署#

1
git add .
2
git commit -m "feat: 配置 GitHub Actions 自动部署"
3
git push origin main

推送后，GitHub Actions 会自动触发构建和部署流程，你可以在仓库的 “Actions” 标签页查看部署进度。

🎨 内容管理系统集成#

为了方便非技术用户编辑博客内容，我集成了 Decap CMS（原 Netlify CMS）。

Decap CMS 配置#

在 public/admin/config.yml 中配置：

1
backend:
2
  name: github
3
  repo: johntime2005/blog
4
  branch: main
5
  base_url: https://blog-4qk.pages.dev
6
  auth_endpoint: /api/auth
7

8
media_folder: "public/assets/uploads"
9
public_folder: "/assets/uploads"
10

11
collections:
12
  - name: "posts"
13
    label: "博客文章"
14
    folder: "src/content/posts"
15
    create: true
16
    slug: "{{slug}}"
17
    fields:
18
      - {label: "标题", name: "title", widget: "string"}
19
      - {label: "发布日期", name: "published", widget: "datetime"}
20
      - {label: "描述", name: "description", widget: "text"}
21
      - {label: "标签", name: "tags", widget: "list"}
22
      - {label: "分类", name: "category", widget: "string"}
23
      - {label: "草稿", name: "draft", widget: "boolean", default: false}
24
      - {label: "正文", name: "body", widget: "markdown"}

OAuth 认证处理#

在 Cloudflare Pages Functions 中实现 GitHub OAuth：

functions/api/auth.ts:

1
export async function onRequestGet(context) {
2
  const { searchParams } = new URL(context.request.url);
3
  const code = searchParams.get('code');
4

5
  if (!code) {
6
    return new Response('Missing code parameter', { status: 400 });
7
  }
8

9
  // 交换 access token
10
  const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
11
    method: 'POST',
12
    headers: {
13
      'Content-Type': 'application/json',
14
      'Accept': 'application/json',
15
    },
16
    body: JSON.stringify({
17
      client_id: context.env.GITHUB_CLIENT_ID,
18
      client_secret: context.env.GITHUB_CLIENT_SECRET,
19
      code: code,
20
    }),
21
  });
22

23
  const data = await tokenResponse.json();
24

25
  // 返回 HTML 页面，通过 postMessage 将 token 发送回父窗口
26
  return new Response(`
27
    <!DOCTYPE html>
28
    <html>
29
      <head>
30
        <script>
31
          window.opener.postMessage(
32
            'authorization:github:success:${JSON.stringify(data)}',
33
            '*'
34
          );
35
          window.close();
36
        </script>
37
      </head>
38
      <body>认证成功，正在关闭窗口...</body>
39
    </html>
40
  `, {
41
    headers: { 'Content-Type': 'text/html' },
42
  });
43
}

配置环境变量：

在 Cloudflare Pages 项目设置中添加：

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET

🐛 常见问题与解决方案#

1. pnpm 版本冲突#

问题：项目中 package.json 和 pnpm-lock.yaml 指定的 pnpm 版本不一致。

解决方案：

1
# 在 package.json 中统一指定版本
2
{
3
  "packageManager": "pnpm@9.14.4"
4
}

同时移除 .npmrc 或其他配置文件中的重复版本声明。

2. Biome 代码格式检查失败#

问题：提交时代码格式不符合 Biome 规范。

解决方案：

1
# 自动修复格式问题
2
pnpm format
3

4
# 修复 lint 问题
5
pnpm lint

3. Cloudflare Pages 构建超时#

问题：依赖安装或构建过程耗时过长。

解决方案：

使用 pnpm install --frozen-lockfile 避免重新解析依赖
在 GitHub Actions 中启用 pnpm 缓存
优化 astro.config.mjs 中的插件配置

4. CMS OAuth 认证失败#

问题：Decap CMS 登录时无法完成 OAuth 流程。

解决方案：

确保 GitHub OAuth App 的回调 URL 配置正确
检查 config.yml 中的 base_url 和 auth_endpoint 路径
验证 Cloudflare Pages Functions 环境变量是否设置

📊 性能优化建议#

1. 图片优化#

使用 Astro 的图片组件自动优化：

1
---
2
import { Image } from 'astro:assets';
3
import coverImage from './cover.jpg';
4
---
5

6
<Image src={coverImage} alt="封面图" width={800} height={400} />

2. 代码分割#

Astro 默认进行代码分割，但可以进一步优化：

1
export default defineConfig({
2
  vite: {
3
    build: {
4
      rollupOptions: {
5
        output: {
6
          manualChunks(id) {
7
            if (id.includes('node_modules')) {
8
              return 'vendor';
9
            }
10
          }
11
        }
12
      }
13
    }
14
  }
15
});

3. 缓存策略#

在 _headers 文件中配置 Cloudflare 缓存：

1
/assets/*
2
  Cache-Control: public, max-age=31536000, immutable
3

4
/*.js
5
  Cache-Control: public, max-age=31536000, immutable
6

7
/*.css
8
  Cache-Control: public, max-age=31536000, immutable

🔗 相关资源#

博客地址: https://blog-4qk.pages.dev
源码仓库: https://github.com/johntime2005/blog
Astro 官方文档: https://docs.astro.build
Cloudflare Pages 文档: https://developers.cloudflare.com/pages
Firefly 主题: https://github.com/CuteLeaf/Firefly
Decap CMS 文档: https://decapcms.org/docs/

🎉 总结#

通过本文的详细步骤，我们成功实现了：

✅ 将 Astro + Firefly 博客部署到 Cloudflare Pages ✅ 配置 GitHub Actions 实现 CI/CD 自动化 ✅ 集成 Decap CMS 实现可视化内容管理 ✅ 解决了部署过程中的各种常见问题

Cloudflare Pages 的全球 CDN、无限带宽和快速部署能力，让静态博客的性能达到了极致。配合 GitHub Actions 的自动化工作流，整个发布流程变得非常流畅。

如果你也在考虑将博客迁移到 Cloudflare Pages，希望这篇文章能够帮助到你！

欢迎在评论区分享你的部署经验或遇到的问题！

Lovely firefly!

基于 Astro + Firefly 的博客部署到 Cloudflare Pages 完整指南

📖 前言#

🎯 技术栈概览#

🔧 项目配置详解#

1. Cloudflare 适配器配置#

2. 构建配置优化#

3. Wrangler 配置（可选）#

🚀 部署流程#

方式一：通过 Cloudflare Dashboard 手动部署#

Step 1: 构建项目#

Step 2: 安装 Wrangler CLI#

Step 3: 登录 Cloudflare#

Step 4: 部署到 Cloudflare Pages#

方式二：GitHub Actions 自动部署（推荐）#

Step 1: 创建 GitHub Actions 工作流#

Step 2: 配置 GitHub Secrets#

Step 3: 推送代码触发部署#

🎨 内容管理系统集成#

Decap CMS 配置#

OAuth 认证处理#

🐛 常见问题与解决方案#

1. pnpm 版本冲突#

2. Biome 代码格式检查失败#

3. Cloudflare Pages 构建超时#

4. CMS OAuth 认证失败#

📊 性能优化建议#

1. 图片优化#

2. 代码分割#

3. 缓存策略#

🔗 相关资源#

🎉 总结#

分享

目录