1.1 安装 Git#

1. 打开浏览器访问
   https://git-scm.com/downloads
2. 下载 Windows 版本的安装包（一般会自动识别）。
3. 双击安装，一路「Next」即可，遇到选项保持默认：
   • 编辑器选项可以保留默认的 Vim，后面我们自己用 VS Code。
   • PATH 配置选择默认那一项（推荐）。
4. 安装完成后，按下 Win + S 搜索「PowerShell」，打开一个终端，输入：

1
git --version

看到类似 git version 2.x.x 就说明安装成功。

1.2 安装 Node.js#

1. 打开 https://nodejs.org/
2. 下载推荐的 LTS 版本（绿色「LTS」按钮）。
3. 安装过程：
   • 双击安装包，勾选「I accept the terms of the License Agreement」
   • 其它选项保持默认，直到完成。
4. 安装完同样在 PowerShell 里检查：

1
node -v
2
npm -v

如果能同时看到 vXX.X.X 和 X.X.X 两行，即 Node 和 npm 都 OK。

1.3 安装 pnpm（全局）#

Fuwari 官方推荐用 pnpm 管理依赖，我们整套方案都用 pnpm。

在 管理员权限的 PowerShell 中执行：

1
npm install -g pnpm

安装完成后，验证：

1
pnpm -v

能看到一个版本号，比如 9.14.4，就说明 pnpm 安装成功。

npm 和 pnpm 的关系

• npm 是 Node 自带的包管理器
• pnpm 是第三方的高性能包管理器（节省磁盘空间）
• 我们用 npm 的唯一用途是：npm install -g pnpm，之后项目内部只用 pnpm

2.1 选择一个存放项目的目录#

我习惯把所有代码放在用户目录下，比如：C:\Users\TX。

打开 PowerShell：

1
cd C:\Users\TX

2.2 克隆 Fuwari 主题#

Fuwari 的 GitHub 仓库地址为：https://github.com/saicaca/fuwari

在 C:\Users\TX 下执行：

1
git clone https://github.com/saicaca/fuwari.git astro-blog-demo

这里我把目标文件夹命名为 astro-blog-demo，你也可以换成 blog 或任意喜欢的名字。

克隆完成后，终端会多出一段 Cloning into 'astro-blog-demo'... 的输出。

2.3 进入项目目录#

很多新手（包括我自己第一次）都会在这里踩坑： 没有 cd 进入项目目录就直接运行 npm/pnpm 命令，导致各种「找不到 package.json」。

请一定确认：

1
cd .\astro-blog-demo

此时终端提示应该变成：

1
PS C:\Users\TX\astro-blog-demo>

你可以用 dir 看看目录里是否有 package.json：

1
dir

• 顶部是 PS C:\Users\TX\astro-blog-demo>
• 下面 dir 输出中能看到 package.json 的那一行。

npm error enoent 如果你在 C:\Users\TX> 直接执行 npm install， npm 会报： Error: ENOENT: no such file or directory, open 'C:\Users\TX\package.json' 这就是没进到项目目录。

2.4 用 pnpm 安装项目依赖#

现在我们已经在项目根目录（有 package.json 的地方），执行：

1
pnpm install

这是一个关键步骤，会做这些事：

• 读取 package.json 中的 dependencies / devDependencies
• 在本地创建 node_modules，下载所有依赖
• 生成 pnpm-lock.yaml 锁定版本

注意：Fuwari 的 package.json 里有这一行：

1
"preinstall": "npx only-allow pnpm"

这表示如果你用 npm install 或 yarn，会直接报错并提示「请使用 pnpm」。 我们现在是 pnpm install，所以是正确的方式。

安装过程中可能会看到很多 WARN（弃用包、兼容性提示），只要最后没有红色的 ERROR，就说明成功。

2.5 启动本地开发服务器#

依赖安装完毕后，运行：

1
pnpm dev

稍等片刻，终端会提示类似：

1
  astro  v5.x.x ...
2

3
  Local    http://localhost:4321
4
  Network  http://192.168.xx.xx:4321

打开浏览器，访问：

1
http://localhost:4321

就能看到 Fuwari 的默认首页。

1. 终端中 pnpm dev 输出 Local http://localhost:4321 的画面；
2. 浏览器里显示 Fuwari 首页的截图（地址栏是 http://localhost:4321）。

要停止开发服务器，在终端里按下 Ctrl + C。

3.1 删除原仓库的 .git 目录#

确保当前路径还是项目根目录：

1
PS C:\Users\TX\astro-blog-demo>

执行：

1
Remove-Item -Recurse -Force .git

或简写：

1
rm -r -Force .git

删完可以用 dir -Force 看一下 .git 是否已经不在了。

3.2 初始化新的 Git 仓库#

1
git init
2
git add .
3
git commit -m "初始化 Astro + Fuwari 博客（使用 pnpm）"

4.1 在 GitHub 上新建仓库#

1. 登录 GitHub，点击右上角 + → New repository
2. Repository name 填写：astro-blog-demo（推荐与本地目录同名）
3. 其它选项保持默认，点击 Create repository

成功后会看到一个页面，上面有类似：

1
…or push an existing repository from the command line
2
git remote add origin https://github.com/你的用户名/astro-blog-demo.git
3
git branch -M main
4
git push -u origin main

4.2 本地绑定远程并推送代码#

回到 PowerShell（项目目录）：

1
cd C:\Users\TX\astro-blog-demo
2

3
git remote add origin https://github.com/你的用户名/astro-blog-demo.git
4
git branch -M main
5
git push -u origin main

⚠️ 一定要把 你的用户名 换成你真实的 GitHub 用户名。

如果一切正常，终端会显示上传进度，最后类似：

1
To https://github.com/你的用户名/astro-blog-demo.git
2
 * [new branch]      main -> main
3
Branch 'main' set up to track remote branch 'main' from 'origin'.

然后回到 GitHub 刷新仓库页面，就能看到所有项目文件。

远程地址写错 如果远程仓库没创建好，或者 URL 里还残留示例中的 你的用户名， git push 会报：remote: Repository not found. 可以用 git remote -v 检查当前绑定的 URL 是否正确。

5.1 选择部署方式：推荐 Git 集成（GitHub → Pages 自动构建）#

Cloudflare Pages 支持直接连接 GitHub 仓库：每次 push 自动构建并发布。

5.2 在 Cloudflare Pages 创建项目并连接仓库#

1. 进入 Cloudflare 控制台 → Workers & Pages → 创建 Pages 项目
2. 选择 GitHub，授权并选中你的博客仓库（比如 astro-blog-demo）
3. 构建设置（Astro/Fuwari 常见配置）：
   • Build command：pnpm build
   • Build output directory：dist
   • （如果有 Node 版本选项，选一个 LTS；pnpm 作为包管理器）

说明：这一步完成后，你会先得到一个默认域名：<PROJECT_NAME>.pages.dev。

5.3 绑定自定义域名（让域名指向 Pages）#

到 Pages 项目 → Custom domains → “Set up a domain”，按向导添加你的域名。

• 如果你用子域名（推荐，如 blog.example.com）：
  • 按文档要求，在 DNS 里添加 CNAME 指向你的 xxxx.pages.dev。
  • 重要：不要只在 DNS 里手动加 CNAME；要先在 Pages 里把域名“关联/激活”，否则可能解析失败并报错。
• 如果你用根域名（example.com）：
  • 需要把域名作为 Cloudflare zone 并把 NS 切到 Cloudflare，然后 Pages 会帮你处理所需记录。

8.1 新建一篇文章#

以 Fuwari 的内容目录结构为准（例如 src/content/posts）， 新建一个文件 src/content/posts/hello-fuwari.md：

1
---
2
title: "Hello Fuwari"
3
published: 2025-12-08
4
description: "第一篇测试文章"
5
tags: ["测试"]
6
category: "随笔"
7
draft: false
8
---
9

10
这是我用 Fuwari + pnpm 重建博客后的第一篇测试文章。

8.2 本地预览确认文章正常#

在项目目录中运行：

1
pnpm dev

然后打开 http://localhost:4321，看首页是否已经出现新文章。确认没问题后，按 Ctrl + C 停掉 dev。

8.3 提交并推送#

1
git add src/content/posts/hello-fuwari.md
2

3
git commit -m "发布第一篇文章：Hello Fuwari"
4

5
git push

然后去 Cloudflare Pages 的 Deployments 页面，等待部署完成。

8.4 访问正式域名#

浏览器访问：

• https://<project>.pages.dev（默认域名）
• 或 https://blog.XXX.XXX（你绑定的自定义域名）

能看到首页已经更新，并且可以点击进入《Hello Fuwari》这篇文章，就说明博客已顺利部署完成 ✅。