步骤 1 · 安装 Node.js（网站的”发动机”）#

Firefly 需要 Node.js 版本 ≥ 22。

1. 打开浏览器，访问官网：https://nodejs.org
2. 首页会看到两个大按钮：LTS（长期支持版） 和 Current。点 LTS 那个（更稳定），下载 Windows 安装包（.msi）。
3. 双击下载好的安装包，一路点 Next（下一步），全部用默认勾选，最后点 Install（安装）。
4. 装完重启一下电脑（或至少重开所有命令行窗口），让系统认到新装的命令。

验证装好了没（重要，每次装完都验证一遍）：

1. 按键盘 Win 键，输入 PowerShell，点打开”Windows PowerShell”。
2. 输入下面这行，按回车：

1
node -v

3. 如果显示类似 v22.x.x（数字 ≥ 22 就行），✅ 成功。如果显示”node 不是内部或外部命令”，说明没装好或没重启，回去重装/重启。

步骤 2 · 安装 pnpm（包管理器，Node 不带它）#

pnpm 是一个”帮我们把模板需要的几百个小零件一次性下载好”的工具。Node 自带的是 npm，但 Firefly 官方指定用 pnpm，所以必须单独装。

在刚才的 PowerShell 里输入：

1
npm install -g pnpm

• 等几十秒，看到进度条走完、回到光标闪烁，就装好了（中间可能刷一堆字，正常现象）。
• -g 意思是”全局安装”，装一次，以后所有项目都能用。

验证：

1
pnpm -v

显示版本号（比如 10.x 或 11.x）就是成功。如果报”pnpm 不是内部命令”——关掉 PowerShell 再重开一次再试（这是最常见的小坑，重开就好）。

步骤 3 · 安装 Git（把网上的模板”下载”到本地）#

Git 是用来从 GitHub 把 Firefly 代码完整拉到电脑上的工具。

1. 访问 https://git-scm.com/download/win，下载 64-bit 安装包。
2. 双击安装，除了”选择默认编辑器”那一步可以选你熟悉的（比如选 Notepad 记事本），其余全程 Next 默认即可。
3. 装完同样重开 PowerShell。

验证：

1
git --version

显示 git version 2.x.x 即成功。

步骤 4 · 选个放项目的文件夹#

建议直接放在某盘根目录，简单好找。比如放在 D:\。

在 PowerShell 里：

1
cd D:\

（cd 是”切换目录”，D:\ 是 D 盘根目录。你也可以换成 E:\ 或别的盘。）

步骤 5 · 克隆（下载）Firefly 模板#

1
git clone https://github.com/CuteLeaf/Firefly.git myblog

• git clone = 把网上的完整代码下载下来
• 最后 myblog 是你给文件夹起的名字（随意，比如 blog、firefly-blog 都行）
• 执行后 D 盘会多出 D:\myblog\ 文件夹

⏳ 这一步从 GitHub 下载，国内可能要 1~3 分钟，看到进度条在走就别打断。

⚠️ 如果一直卡 0%、连不上 GitHub（国内常见）：把地址前面加个代理前缀再试：

1
git clone https://ghproxy.com/https://github.com/CuteLeaf/Firefly.git myblog

步骤 6 · 进入项目目录并安装依赖#

1
cd myblog
2
pnpm install

• cd myblog：进入刚下载的项目文件夹（以后所有 pnpm 命令都要先 cd 进这个目录再执行）
• pnpm install：读项目里的清单，把 Astro、Tailwind 等几百个零件下载安装好。第一次会下载较多，可能要几分钟，屏幕刷进度是正常的，不要中断。看到最后回到光标、没有红色报错 = 成功。

步骤 7 · 本地预览，看看默认长什么样#

1
pnpm dev

• 它会启动本地预览，最后一行通常显示 localhost:4321
• 打开浏览器，访问 http://localhost:4321 ，能看到 Firefly 默认首页（带示例文章）= ✅ 模板可用
• 看完按 Ctrl + C 停止预览（回到命令行）

💡 以后每次想本地看效果，都运行 pnpm dev。

步骤 8 · 改站点基本信息（siteConfig.ts）#

用记事本打开 src\config\siteConfig.ts，找到类似下面的内容，把中文部分改成你自己的：

1
export const siteConfig = {
2
  title: "我的博客",          // 浏览器标签页上显示的站名
3
  description: "记录学习与生活的点滴",  // 网站一句话简介
4
  // lang、base 等先别动，后面讲域名时再说
5
};

改完保存即可。

步骤 9 · 改个人资料与社交链接（profileConfig.ts）#

打开 src\config\profileConfig.ts：

1
export const profileConfig = {
2
  // 头像：把你的头像图片放到 src/assets/images/ 下，这里填 "assets/images/你的图.avif"
3
  // 也可以直接填一个网络图片地址，如 "https://xxx.com/avatar.jpg"
4
  avatar: "assets/images/avatar.avif",
5

6
  name: "你的昵称",          // 比如 "齐先生"
7
  bio: "这是我的个性签名",     // 比如 "热爱生活，记录成长"
8

9
  // 社交链接：下面每条是一个图标按钮
10
  links: [
11
    {
12
      name: "GitHub",
13
      icon: "fa7-brands:github",   // 图标样式（不用改）
14
      url: "https://github.com/你的用户名",  // 改成你的地址
15
      showName: false,             // false=只显示图标；true=图标+文字
16
    },
17
    {
18
      name: "Email",
19
      icon: "fa7-solid:envelope",
20
      url: "mailto:你的邮箱@qq.com",   // 改成你的邮箱
21
      showName: false,
22
    },
23
    // 想加微信？复制上面一条，改成：
24
    // { name: "微信", icon: "fa7-brands:weixin", url: "https://u.wechat.com/你的二维码链接", showName: false },
25
  ],
26
};

怎么换头像：把你的一张正方形头像（建议 .jpg 或 .png）放进 myblog\src\assets\images\ 文件夹，假设叫 me.jpg，就把 avatar 改成 "assets/images/me.jpg"。

步骤 10 · 填友情链接（friendsConfig.ts）#

“交友链接”就是博客里常见的”友情链接”板块——把你欣赏的其他博客/朋友网站列出来，互相推荐。

打开 src\config\friendsConfig.ts，里面是一个列表，每条长这样：

1
export const friendsConfig = [
2
  {
3
    title: "对方网站的名字",                 // 比如 "小明的学习笔记"
4
    imgurl: "https://对方头像或图标地址",      // 可用 https://weavatar.com/ 生成，或对方 favicon
5
    desc: "一句话介绍对方网站",               // 比如 "分享编程与生活的博客"
6
    siteurl: "https://对方的网址",            // 比如 "https://xiaoming.com"
7
    tags: ["Blog"],                         // 标签，可写 ["博客"] 等
8
    weight: 10,                             // 排序权重，数字越大越靠前
9
    enabled: true,                          // true=显示；false=隐藏
10
  },
11
  // 想再加一个？复制上面整个 { ... } 块，粘贴在逗号后面，改内容即可
12
];

每条填什么，对照表：

💡 imgurl 不会找？两个简单办法：① 去 https://weavatar.com/ 输入对方邮箱或域名，自动生成头像地址；② 直接填对方网站域名的 favicon，如 https://xiaoming.com/favicon.ico。

💡 不想显示某个友链，把它的 enabled 改成 false 即可，不用删。

步骤 11 · 换网站背景主题图（backgroundWallpaper.ts）★你特别问的#

网站打开时那张好看的背景大图，就是在这里换的。

第 1 步：准备你的图片

• 挑一张**横向、清晰、不太大（建议压缩到 1MB 以内，否则加载慢）**的图片，比如 mybg.jpg。
• 放进 myblog\src\assets\images\DesktopWallpaper\ 文件夹（这个文件夹本来就有，专门放桌面背景图）。

第 2 步：改配置 打开 src\config\backgroundWallpaper.ts，找到这一段：

1
src: {
2
  // 桌面端背景图
3
  desktop: [
4
    "assets/images/DesktopWallpaper/d1.avif",
5
    // ... 原来一堆 d2 d3 ...
6
  ],
7
  // 手机端背景图
8
  mobile: [
9
    "assets/images/MobileWallpaper/m1.avif",
10
    // ...
11
  ],
12
},

把它改成只指向你自己的那张图（最不容易出错）：

1
src: {
2
  desktop: "assets/images/DesktopWallpaper/mybg.jpg",  // 你的桌面背景
3
  mobile:  "assets/images/MobileWallpaper/mybg.jpg",   // 你的手机背景（没有就也用同一张）
4
},

⚠️ 重要：Firefly 自带的示例图名叫 d1~d6、m1~m6。别用这些名字覆盖它们，否则以后官方更新模板会把你的图冲掉。你用自己的名字（如 mybg）就安全。

第 3 步（可选）：改首页大标题文字 同一个文件往下找 common.homeText：

1
homeText: {
2
  enable: true,
3
  title: "这里写首页主标题",        // 比如 "欢迎来到我的博客"
4
  subtitle: [                      // 副标题，会打字机效果轮播
5
    "一句话介绍你自己",
6
    "另一句想说的话",
7
  ],
8
  // ...
9
},

改完保存。运行 pnpm dev 刷新就能看到新背景和新标题。

💡 背景模式有 4 种：banner（横幅，默认）、fullscreen（全屏）、overlay（全屏透明）、none（纯色无图）。在文件最上面的 mode: "banner" 改。小白先用默认 banner 即可。

步骤 12 · 改导航栏和页脚（可选）#

• 顶部菜单：打开 src\config\navBarConfig.ts，里面列着”首页 / 文章 / 友链”等菜单，照着格式增删即可。
• 页面底部：打开 src\config\footerConfig.ts，改版权信息、备案号（国内上线建议填 ICP 备案号）等。

这两步不急，先用默认也能跑，以后想精细化再改。

步骤 13 · 删除官方示例内容（换成你自己的）★你特别问的#

Firefly 下载下来自带十几篇演示文章和一堆示例图，必须删掉，否则别人看到的全是官方示例。

要删除的内容在 myblog\src\content\ 下：

怎么删（最简单）：

1. 打开文件夹 myblog\src\content\posts\
2. Ctrl + A 全选 → Delete 删除里面所有文件和 guide、images 子目录
3. 回到 myblog\src\content\，确认 posts 文件夹还在（空的就行）

✅ 删完后，这个目录就是”你放自己文章的地方”，下一步往里放你的文章。

步骤 14 · 写你自己的第一篇文章#

Firefly 的文章就是普通的 Markdown 文件（.md），放在 src\content\posts\。每篇顶部要写一段”文件头”（叫 frontmatter），告诉系统标题、日期等。

一个完整例子（新建文件 我的第一篇文章.md，内容如下）：

1
---
2
title: "我的第一篇博客"
3
published: 2026-08-18
4
description: "用 Firefly 搭建博客后写的第一篇"
5
tags: [随笔, 生活]
6
category: 日常
7
slug: my-first-post
8
---
9

10
这是正文第一段。Markdown 很好写：
11

12
## 一个小标题
13

14
- 列表项一
15
- 列表项二
16

17
**加粗**、*斜体*、`代码` 都支持。
18

19
> 引用块也支持。

frontmatter 字段说明（必须照格式写）：

⚠️ 最坑的一点：Firefly 用的是 published 当日期字段（不是 date，也不是 pubDate）。写错文章就不显示，千万别写错。

💡 嫌手填麻烦？我们做的上传辅助小程序里有”导入已有文档”功能，选你的 .md 文件后，会弹窗引导你填这些字段，自动帮你生成好 frontmatter（详见文末附录）。

写好多篇后，这个目录里就是你的全部文章了。

步骤 15 · 构建出 dist 文件夹#

在 myblog 目录下执行：

1
pnpm build

• 它会把你写的 Markdown + 模板，编译成纯静态网页，生成在 myblog\dist\ 文件夹。
• 看到”完成/无报错”就成功。dist\ 里就是最终要上传的全部网站文件（index.html、assets\ 等）。

❌ 如果报错：90% 是某篇文章的 frontmatter 写错了（尤其是 published 写成 date、或引号用了中文引号）。把报错里提到的文件名和行号发给我，我帮你查。

步骤 16 · 你已经有服务器了#

阿里云轻量应用服务器 / ECS 都行。本文假设你已经有了一台（2 核 2G 足够跑静态网站）。如果没有，去阿里云买一台”轻量应用服务器”，系统选 Ubuntu 22.04 或 CentOS 7/8。

步骤 17 · 在云平台放行端口（很多人卡在这）#

别人要用浏览器访问你的网站，服务器的”门”得打开。

1. 登录阿里云控制台 → 找到你的服务器 → 防火墙 / 安全组
2. 添加规则，放行以下端口：
   • 22（SSH，用来远程登录和传文件）
   • 80（HTTP，普通访问）
   • 443（HTTPS，加密访问，后面开小绿锁用）
3. 保存。

轻量应用服务器叫”防火墙”，ECS 叫”安全组”，是一回事。

步骤 18 · 远程登录服务器#

在你电脑的 PowerShell 里：

1
ssh root@你的服务器公网IP

• 第一次会问 Are you sure...，输入 yes 回车
• 然后输入 root 密码（输入时不显示，正常）
• 看到命令行变成 root@xxxx:~# 就是登进去了

步骤 19 · 安装 Nginx（纯净环境做法）#

Nginx 是”把网站文件对外提供访问”的软件。

Ubuntu / Debian：

1
apt update
2
apt install -y nginx

CentOS / Rocky：

1
yum install -y nginx
2
systemctl enable --now nginx

装完在浏览器访问 http://你的服务器IP，看到 Nginx 欢迎页 = ✅ 成功。

步骤 20 · 建网站目录#

还在服务器命令行里：

1
mkdir -p /var/www/firefly

这就是以后放网站文件的地方（记住这个路径）。

步骤 21 · 配置 Nginx 指向网站目录#

写入一份站点配置：

1
cat > /etc/nginx/sites-available/firefly <<'EOF'
2
server {
3
    listen 80;
4
    server_name 你的服务器IP;   # 有域名后改成域名，如 blog.example.com
5
    root /var/www/firefly;
6
    index index.html;
7
    location / {
8
        try_files $uri $uri/ /index.html;
9
    }
10
}
11
EOF
12
ln -s /etc/nginx/sites-available/firefly /etc/nginx/sites-enabled/firefly
13
nginx -t          # 检查配置有没有错
14
systemctl reload nginx

最后两条没报错 = 配置生效。

🟦 宝塔用户看这里（跳过步骤 19/20/21）：你买服务器时如果一键装了宝塔面板，Nginx 已经在由宝塔管理，不要自己装、不要手写上面配置。你只需要：

1. 登录宝塔面板（地址 http://服务器IP:8888）
2. 左侧「文件」→ 进 /www/wwwroot/ → 新建文件夹 firefly
3. 左侧「网站」→「添加站点」，域名填你已有的 blog.xxx.cn（或临时填服务器IP）→ 提交（宝塔会自动建好 Nginx 配置）
4. 记住网站目录是 /www/wwwroot/firefly（不是 /var/www/firefly） 后面的”上传目录”一律用 /www/wwwroot/firefly。

步骤 22 · 用上传辅助小程序一键上传（最推荐，不用记命令）#

我们专门给你做了一个小程序（firefly_uploader/），双击 start.bat 就能用，界面引导式操作。用法：

1. 第 1 页 服务器连接：填 IP、用户名（root）、密码、SSH 端口（22）、远程网站目录（纯净环境填 /var/www/firefly；宝塔用户填 /www/wwwroot/firefly）。点”测试连接”确认能连上 → 保存。
2. 第 2 页 本地项目：选你的 myblog 文件夹路径（程序会自动找到里面的 dist）。
3. 第 3 页 写文档：可以手填生成文章，或点「导入已有文档」自动加 frontmatter 并上传（详见附录）。
4. 第 4 页 一键上传：点「🚀 一键上传」，程序自动 pnpm build + 把文件传到服务器。搞定。

⚠️ 宝塔用户务必在第 1 页把远程目录改成 /www/wwwroot/firefly，否则传上去网站不更新。

步骤 23 · 或手动用 scp 上传（不装小程序时）#

在你电脑的 PowerShell 里（注意先 cd 进项目目录）：

1
cd D:\myblog
2
scp -r .\dist\* root@你的服务器IP:/var/www/firefly/

宝塔用户把目标目录换成 /www/wwwroot/firefly/：

1
scp -r .\dist\* root@你的服务器IP:/www/wwwroot/firefly/

• 第一次连会问 yes，输入回车；再输密码
• 等文件传完即可

步骤 24 · 域名解析#

1. 在域名服务商（阿里云/腾讯云/DNSPod 等）给域名加一条 A 记录，指向你的服务器公网 IP。
2. 等几分钟生效（ping 一下你的域名看是否指向服务器 IP）。

步骤 25 · 申请免费证书并配置#

纯净环境（手动）：

1. 阿里云「SSL 证书」申请一张免费 DV 证书，下载 Nginx 版，传到服务器 /etc/nginx/ssl/
2. 把步骤 21 的 Nginx 配置改成 listen 443 ssl; 并填证书路径，加 80→443 跳转（需要我帮你写完整配置时再说）
3. 确认防火墙已放行 443（步骤 17 做过），nginx -t 检查后 systemctl reload nginx

宝塔用户（一键）：

1. 宝塔左侧「网站」→ 你的站点 →「SSL」→「Let’s Encrypt」→ 勾选域名 → 点「申请」
2. 申请完点「强制 HTTPS」
3. 宝塔自动配好证书和跳转，不用碰命令行

💡 没域名也能先用 IP 访问，证书晚点再弄，不影响看网站。

步骤 26 · 浏览器验证#

打开浏览器访问 http://你的服务器IP（或 https://你的域名）：

• ✅ 首页是你换的背景图 + 你的标题
• ✅ 文章列表里是你自己写的文章
• ✅ 点进文章，图片能显示
• ✅ 地址栏有小绿锁（HTTPS 正常）

步骤 27 · 以后怎么更新文章（日常流程）#

1. 在 myblog\src\content\posts\ 增删改你的 .md 文章
2. 改完配置/文章后，本地 pnpm build 重新生成 dist
3. 用辅助小程序「一键上传」（或 scp）传到服务器
4. 浏览器 Ctrl + F5 强刷，看到新内容 = 完成

服务器不用重装任何东西，只在第一次部署时配过 Nginx/宝塔。以后永远是”改文章 → 构建 → 上传”三步。

步骤 28 · 常见排错表#