环境与初始构建#

项目依赖 Node.js（版本 <= 22）并使用 pnpm 管理依赖。构建初始项目时，可以通过以下命令生成模板：

1
pnpm create fuwari@latest

生成项目后，通过安装依赖并启动开发服务器进行预览：

1
pnpm install
2
pnpm dev

浏览器可访问 http://localhost:4321 进行实时预览。

文章与内容管理#

文章以 Markdown 格式存放在 src/content/posts/ 目录下。每篇文章需包含 Frontmatter 信息：

1
---
2
title: "文章标题"
3
published: true
4
draft: false
5
tags: ["标签1", "标签2"]
6
category: "专题名称"
7
---

• published 与 draft 字段控制文章是否显示
• tags 数组用于标签页展示
• category 用于专题页分类

初始构建中，发现首页可以显示文章，但专题页、标签页和归档页为空。原因是 Fuwari 的 collection 系统严格依赖 Frontmatter 与 collection type 的匹配。确保 Frontmatter 完整且字段符合 collection schema，可以解决此问题。

配置与自定义#

Fuwari 提供多个配置模块：

• siteConfig：网站标题、语言、主题色、横幅、目录等
• navBarConfig：导航栏链接
• profileConfig：头像、简介及社交链接
• licenseConfig：版权声明
• expressiveCodeConfig：代码块主题

在写作阶段，可保持默认配置，仅专注于文章内容。About 页面和友情链接页面可以通过对应的 Markdown 文件进行编辑，而无需修改布局组件。

构建与部署#

完成文章编辑后，通过以下命令生成静态站：

1
pnpm build
2
pnpm preview

生成的静态文件位于 ./dist/ 目录，可上传至静态站托管服务，如 Vercel、Netlify 或 GitHub Pages。

版本管理#

建议使用 Git 对项目进行版本管理：

1
git init
2
git add .
3
git commit -m "Initial commit - Fuwari setup"

同时配置 .gitignore，忽略依赖与构建产物：

1
node_modules/
2
dist/
3
.env
4
.vscode/

日常写作只需提交 src/content/posts/ 下的 Markdown 文件，即可保持内容版本控制，支持回滚和远程备份。

意外#

若遇到可能意外的构建问题，回到项目根目录（项目名称目录，不是构建项目时最开始那个目录。例如在根目录下构建了名为 Project 的项目，则 Project 这个文件夹内为项目根目录）并执行以下代码：

1
rm -rf dist node_modules package-lock.json pnpm-lock.yaml yarn.lock
2
pnpm install
3
pnpm dev

总结#

Fuwari 主题提供现代前端效果和静态站高性能展示，但与传统 CMS 系统不同，需要严格遵守 Frontmatter 和 collection 的结构规则。写作阶段只需保证 Markdown 文件完整即可专注内容生产，而主题自定义和魔改可以在后续熟悉文件之后再进行。