启用 pnpm#

本项目要求使用 pnpm。现代 Node 自带 corepack，可以用它来启用 pnpm。在终端执行：

1
# Windows (PowerShell) / macOS / Linux 通用
2
corepack enable
3
corepack prepare pnpm@latest --activate

执行后运行 pnpm -v，能看到版本号即表示成功。

为什么不直接用 npm？Fuwari 官方的 package.json 中声明了 packageManager: [email protected]，并带有 preinstall: npx only-allow pnpm 钩子，强制使用 pnpm 以避免锁文件不一致带来的问题。

1. 用 Fuwari 模板初始化项目#

在你想存放项目的目录下，执行 create 命令：

1
# Windows (PowerShell)
2
npm exec --yes -- create-fuwari@latest my-blog

1
# macOS / Linux
2
pnpm create fuwari@latest my-blog

npm exec --yes -- create-fuwari@latest 与 pnpm create fuwari@latest 效果一致，都会调用官方的 create 脚手架并生成一个名为 my-blog 的目录。如果你的终端对某个命令报错，换另一种即可。

命令执行后会询问几个初始化选项（是否初始化 git、是否安装依赖等），按提示选择即可。A: 交互式询问会让你选 TypeScript 类型、是否安装依赖等，全部选默认（Enter）即可。

进入项目目录并安装依赖：

1
cd my-blog
2
pnpm install

依赖安装完成后，项目结构类似：

1
my-blog/
2
├── src/
3
│   ├── config.ts          # 站点配置（标题、头像、导航等）
4
│   ├── content/
5
│   │   └── posts/         # 博客文章存放处
6
│   ├── layouts/
7
│   └── pages/
8
├── astro.config.mjs       # Astro 与部署配置
9
├── package.json
10
└── pnpm-lock.yaml

2. 本地预览#

启动开发服务器：

1
pnpm dev

终端会输出本地地址，通常是 http://localhost:4321。用浏览器打开，你应该能看到 Fuwari 的默认样式的博客首页。

开发服务器会热更新：修改代码或文章后，浏览器自动刷新，无需手动重启。

3. 修改站点配置#

先改最基础的站点信息，确认配置链路是通的。打开 src/config.ts，找到 siteConfig 部分：

1
export const siteConfig: SiteConfig = {
2
    title: "我的博客",
3
    subtitle: "记录技术与生活",
4
    lang: "zh_CN",
5
    // ...
6
};

把 title 和 subtitle 换成你自己的，保存后回到浏览器，首页标题应已变化。

src/config.ts 是 Fuwari 最主要的配置文件，相当于其它静态博客（如 Hexo）里的 _config.yml，站点标题、头像、导航、社交链接、主题色等都在这里设置。这一阶段先只改标题，其余后面再慢慢调。

4. 推送到 GitHub#

在 GitHub 上新建一个仓库（考虑到博客资源属于个人，建议使用私有仓库，Cloudflare Pages 支持私有仓库的访问）。

回到项目目录，初始化并推送：

1
git init
2
git add .
3
git commit -m "init: astro fuwari blog"
4
git branch -M main
5
git remote add origin https://github.com/YOUR_NAME/my-blog.git
6
git push -u origin main

把 YOUR_NAME 替换成你的 GitHub 用户名，my-blog 替换成你的仓库名。此时推送的是源码，不是构建产物，所以不用担心仓库体积。

5. 连接 Cloudflare Pages 并部署#

1. 登录 Cloudflare 控制台。
2. 进入左侧 计算 / Workers & Pages。
3. 点击 Create application → 选择 Pages 标签页 → Connect to Git。
4. 授权 GitHub，并选择你刚才推送的 my-blog 仓库，建议按最小权限规则，仅允许Cloudflare访问勾选的项目，后续想要更改权限的时候访问这个链接。
5. 在构建配置中填写：

6. 点击 Save and Deploy。

Cloudflare 会依次执行：拉取源码 → 安装 pnpm 依赖 → pnpm build → 发布 dist。

为什么构建命令是 pnpm build、输出目录是 dist？Fuwari 的 package.json 里 build 脚本是 astro build && pagefind --site dist（其中 pagefind 是内置的静态搜索，下一阶段会讲），产物统一输出到 dist 目录，所以这里要填 dist。

部署完成后，Cloudflare 会给你一个临时地址，形如：

1
https://my-blog-xxx.pages.dev

打开它，你就能看到一个已上线的博客。至此，最小可运行链路已打通。

1. 理解 Frontmatter#

每篇文章都是一个 Markdown 文件，开头有一段 YAML 格式的 frontmatter 描述元信息。Fuwari 使用以下字段（以 src/content/config.ts 中的 schema 为准）：

1
---
2
title: 我的第一篇文章
3
published: 2026-09-07
4
description: 文章摘要
5
tags:
6
  - Astro
7
category: 技术
8
draft: false
9
---

字段说明：

• title：文章标题（必填）。
• published：发布日期（必填），用 YYYY-MM-DD 格式。
• description：文章摘要，可选。
• tags：标签，字符串数组。
• category：分类，单个字符串（不是数组）。
• draft：true 表示草稿，生产构建不展示；写好后改成 false。

2. 写一篇文章#

在 src/content/posts/ 下新建一个 Markdown 文件，例如 hello.md，填入 frontmatter 和正文：

1
---
2
title: 你好，世界
3
published: 2026-09-07
4
tags:
5
  - 测试
6
category: 日常
7
draft: false
8
---
9

10
这是我的第一篇博客文章。
11

12
## 小标题
13

14
正文内容，支持标准 Markdown 语法。

本地 pnpm dev 下应该能立刻在首页看到这篇文章。

3. 图片路径#

如果文章中要用本地图片，推荐把图片放在文章的同名目录下，正文用相对路径引用：

1
![配图](./hello/cover.png)

即 src/content/posts/hello/ 下放 cover.png。这样 Astro 会自动处理图片路径，部署后也不会失效。

避免使用磁盘上的绝对路径（如 C:\Users\... 或 D:\...），否则部署后图片会 404。

4. 提交并自动部署#

1
git add .
2
git commit -m "post: hello world"
3
git push

推送到 main 后，Cloudflare Pages 会自动重新构建并发布。等构建完成后刷新你的 pages.dev 地址，就能看到新文章。

1. 在 DNS 中添加记录#

假设你的域名是 example.com，博客想挂在 blog.example.com。

场景 A：域名已托管在 Cloudflare（推荐）

如果你的域名已经通过 Cloudflare 管理 DNS（即域名的 Nameserver 已指向 Cloudflare），在 Pages 项目里添加自定义域名时，Cloudflare 通常会自动创建 DNS 记录，无需手动操作。

场景 B：域名托管在其它注册商

需要在你的域名注册商（如阿里云、腾讯云、GoDaddy 等）的 DNS 管理里，手动添加一条记录：

若域名完全托管在 Cloudflare，把 Nameserver 改成 Cloudflare 提供的即可，之后 DNS 记录可在 Cloudflare 内统一管理，并开启橙色云朵（代理）以获得 CDN 加速。

2. 在 Pages 项目中添加自定义域名#

1. 进入你的 Pages 项目 → Custom domains → Set up a custom domain。
2. 输入 blog.example.com，点击继续。
3. 按 Cloudflare 的提示完成验证。

等待几分钟，Cloudflare 会自动为该域名签发 HTTPS 证书。

3. 修改 astro.config.mjs 的 site#

打开 astro.config.mjs，把 site 改成你的正式域名：

1
export default defineConfig({
2
    site: "https://blog.example.com/",
3
    base: "/",
4
    trailingSlash: "always",
5
    // ...
6
});

为什么必须改 site？它会影响到 Sitemap、RSS/Atom 的地址、canonical URL、Open Graph 等，如果还留着默认的演示地址，搜索引擎和订阅源会指向错误的位置。

改完后提交推送，重新部署。之后访问 https://blog.example.com/ 即可。

它已经默认启用了#

看 package.json 的 build 脚本：

1
"build": "astro build && pagefind --site dist"

每次 pnpm build 时，会在 dist 下生成搜索索引。部署到 Cloudflare Pages 后，页面上方导航栏的搜索框即可使用。

本地验证搜索#

1
pnpm build
2
pnpm preview

pnpm preview 会预览 dist 目录。打开预览地址，点导航栏的搜索框，输入文章标题中的关键词，应能搜到结果。

为什么本地 pnpm dev 下搜索可能不生效？因为 Pagefind 的索引是构建时生成的，开发模式不会运行 pagefind 命令。要验证搜索，请用 build + preview，而不是 dev。