Cloudflare Pages部署Firefly（流萤）博客完整步骤

Firefly 是基于 Astro 的静态博客主题，源码：github.com/CuteLeaf/Firefly

前置条件：GitHub账号、Cloudflare账号、本地安装Git；Node.js ≥22，pnpm≥9（本地调试用）

一、Fork源码到自己GitHub仓库（推荐）

1. 打开官方仓库：github.com/CuteLeaf/Firefly
2. 点击右上角 Fork，复刻到你的GitHub账号下，不要勾选Copy the main branch only，直接Fork。

   不fork也可以本地clone后推送到自己新建仓库，Fork方便后续同步上游更新。

二、（可选）本地自定义博客配置

# 克隆你fork后的仓库，替换为你的仓库地址
git clone https://github.com/你的github用户名/Firefly.git
cd Firefly

# 安装依赖
npm install -g pnpm
pnpm install

# 本地预览，访问 http://localhost:4321
pnpm dev

修改博客配置：

• src/config/siteConfig.ts：站点名称、描述、语言、作者信息
• src/content/posts/：存放你的markdown文章
  修改完成提交推送：

  git add .
  git commit -m "初始化博客配置"
  git push origin main

三、Cloudflare Pages连接GitHub仓库部署

1. 登录 Cloudflare控制台
2. 左侧菜单：Workers & Pages → 创建应用程序 → Pages → 连接Git
3. 授权GitHub，选择你Fork的Firefly仓库，点击开始设置

⚙️关键构建设置（Firefly/Astro必须严格填写）

添加环境变量（高级）

• 变量名：NODE_VERSION
• 值：22

  Firefly强制要求Node22版本，不填会构建失败

全部填好，点击保存并部署。

等待1‑3分钟构建完成，成功后会生成默认域名：项目名.pages.dev，直接访问即可看到博客。

四、绑定自定义域名（可选）

1. Pages项目页面 → 自定义域名 → 设置自定义域
2. 填入你的域名，按照Cloudflare提示，在域名DNS添加CNAME记录指向pages.dev分配的地址。

   域名托管在Cloudflare，会自动配置SSL证书。

五、后续更新博客流程

1. 本地修改文章/配置

   git add .
   git commit -m "更新文章"
   git push origin main

2. push到GitHub main分支后，Cloudflare Pages自动触发重新构建部署，等待1‑2分钟网站更新。

六、直接上传dist文件夹部署（不使用GitHub，备选）

如果你本地已经执行pnpm run build生成dist静态产物：

1. Workers & Pages → 创建应用程序 → Pages → 直接上传资产
2. 将本地dist文件夹全部拖拽上传，完成部署。

   缺点：后续更新需要手动重新上传，没有自动CI。

常见报错排查

1. 构建报错Node版本过低：确认环境变量NODE_VERSION=22，不要写小数如22.11.0，填大版本数字即可。
2. 构建成功页面空白/样式丢失
   • 检查astro.config.mjs的site配置，绑定域名时填写完整网站地址。
   • Cloudflare后台清除缓存。
3. pnpm未找到：Cloudflare Pages对Astro项目原生支持pnpm，无需额外安装；如果报错，构建命令改为npm install -g pnpm && pnpm run build。
4. 预览地址正常，正式域名异常：检查DNS解析，等待DNS生效。

补充参考文档

• Firefly官方文档：docs-firefly.cuteleaf.cn
• Astro在Cloudflare Pages部署文档：Cloudflare官方Astro适配器文档。

本作品采用《CC 协议》，转载必须注明作者和本文链接