# fuwari

**Repository Path**: worhllo/fuwari

## Basic Information

- **Project Name**: fuwari
- **Description**: 基于 Astro + Svelte 的静态博客系统，支持多种主题与评论（Fork from saicaca/fuwari）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🌸 Fuwari Enhanced

**基于 [saicaca/fuwari](https://github.com/saicaca/fuwari) 定制的个人博客系统**

[![Astro](https://img.shields.io/badge/Astro-5.x-FF5D01?logo=astro&logoColor=white)](https://astro.build)
[![Svelte](https://img.shields.io/badge/Svelte-5.x-FF3E00?logo=svelte&logoColor=white)](https://svelte.dev)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.x-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

</div>

---

## ✨ 已实现特性

在保留原版 fuwari 设计的基础上，本仓库当前实际包含以下功能：

### 📝 内容增强
- **文章置顶/置底** — frontmatter `order` 字段（`1` 置顶 / `-1` 置底 / `0` 默认），同级按发布时间倒序
- **目录导航 (TOC)** — 长文自动生成右侧目录，支持 1~3 级深度
- **数学公式** — KaTeX 渲染，支持 LaTeX 语法
- **GitHub 风格提示块** — `note` / `tip` / `important` / `caution` / `warning`
- **代码块增强** — ExpressiveCode + 行号 + 可折叠区段 + 语言徽标 + 自定义复制按钮（GitHub Dark 主题）
- **二级导航菜单** — `navBarConfig` 支持 `children` 字段

### 🎨 视觉与交互
- **明暗主题切换** — 支持 light / dark / auto 三种模式，可记忆选择
- **主题色调** — 可调 hue，支持锁定
- **页面过渡** — Swup 驱动的淡入切换
- **自定义滚动条** — OverlayScrollbars
- **图片灯箱** — PhotoSwipe（点击图片放大、滚轮缩放、双击缩放）
- **页脚运行时间** — 显示站点已运行时长

### 🔍 搜索与 SEO
- **站内搜索** — Pagefind（生产环境异步加载）
- **Sitemap** — 自动生成 `sitemap-index.xml`
- **RSS** — 自动生成 `rss.xml`
- **robots.txt** — 自动生成
- **JSON-LD** — 文章页输出 `BlogPosting` 结构化数据
- **Open Graph / Twitter Card** — 基础元信息输出

### 💬 评论与友链
- **Giscus 评论** — 文章页与友链页均启用
- **友链页面** — 静态数据驱动（`src/friends_data.ts`），卡片网格展示

### 🔒 隐私与分析
- **Umami 分析** — 无 Cookie 的隐私友好分析，默认关闭，在 `config.ts` 中配置 `umamiConfig` 后启用

### 🌐 国际化
- **UI 文案 i18n** — 内置 10 种语言（en / zh_CN / zh_TW / ja / ko / es / th / vi / tr / id）

---

## 🚀 快速开始

### 环境要求
- **Node.js** 18+（CI 验证过 22 / 23）
- **pnpm** 9+（已通过 `preinstall` 钩子强制）

### 安装与运行

```bash
# 克隆仓库
git clone <仓库地址>

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

访问 `http://localhost:4321` 即可预览。

---

## 📂 项目结构

```
src/
├── config.ts          # 站点配置入口（必改）
├── content/
│   ├── posts/         # 博客文章（Markdown）
│   └── spec/          # about / friends 等特殊页面
├── components/        # UI 组件
│   ├── control/       # 分页、按钮、回到顶部
│   ├── misc/          # Giscus、图片包装、License、Markdown
│   └── widget/        # 侧边栏、TOC、分类、标签、Profile
├── layouts/           # 页面布局
├── pages/             # 路由页面
├── plugins/           # Rehype/Remark 插件
├── i18n/              # 国际化
├── styles/            # 样式
├── utils/             # 工具函数
└── types/             # 类型定义
scripts/
└── new-post.js        # 创建新文章脚本
```

---

## ⚙️ 常用命令

| 命令 | 说明 |
| :--- | :--- |
| `pnpm dev` | 启动开发服务器 |
| `pnpm build` | 构建生产版本（含 Pagefind 索引生成） |
| `pnpm preview` | 预览生产构建 |
| `pnpm new-post "标题"` | 创建新文章 |
| `pnpm gen-ai` | 调用 LLM 生成 AI 摘要（见下文说明） |
| `pnpm check` | Astro 类型检查 |
| `pnpm type-check` | TypeScript 类型检查 |
| `pnpm lint` | 代码检查（Biome，自动修复） |
| `pnpm format` | 代码格式化（Biome） |

---

## 📝 文章 Frontmatter

```yaml
---
title: '文章标题'           # 必填
published: 2026-03-30       # 必填，发布日期
description: '文章摘要'     # 选填，默认空字符串
image: '封面图链接'          # 选填，默认空字符串
tags: ['标签1', '标签2']    # 选填，默认空数组
category: '文章类别'        # 选填，默认空字符串
draft: false                # 选填，默认 false
lang: ''                    # 选填，默认空字符串（留空则使用站点语言）
order: 0                    # 选填，1=置顶 / -1=置底 / 0=默认
updated: 2026-04-01         # 选填，更新日期
ai: 'AI 生成的文章摘要'     # 选填，由 pnpm gen-ai 预生成，留空则不显示摘要区块
---
```

---

## 🤖 AI 摘要生成

文章页支持展示 AI 生成的摘要。摘要通过本地脚本调用 LLM 预生成，写回 frontmatter 的 `ai` 字段，**构建时静态渲染**，无需运行时调用，API Key 不会泄露。

### 1. 配置 API

在项目根目录创建 `.env` 文件（已被 `.gitignore` 忽略）：

```bash
# 必填
AI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# 可选（默认 OpenAI）
AI_BASE_URL=https://api.openai.com/v1
AI_MODEL=gpt-4o-mini

# 可选：自定义摘要风格
AI_MAX_TOKENS=200
AI_SYSTEM_PROMPT=你是一个技术博客的摘要助手...
```

兼容任何 OpenAI 格式的 API：

| 服务商 | AI_BASE_URL | AI_MODEL 示例 |
| :--- | :--- | :--- |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
| Moonshot | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` |
| 本地 Ollama | `http://localhost:11434/v1` | `qwen2.5:7b` |

### 2. 生成摘要

```bash
pnpm gen-ai                  # 增量：只处理缺失 ai 字段的文章
pnpm gen-ai --force          # 强制全量重新生成
pnpm gen-ai --only=文章slug  # 只处理指定文章
```

脚本会读取每篇文章正文，调用 LLM 生成 80-150 字摘要，写回 frontmatter：

```yaml
---
title: 我的第一篇文章
ai: "本文分享了作者搭建个人博客系统的全过程，涵盖技术选型、主题定制、部署上线等关键步骤..."
---
```

### 3. 安全说明

- API Key 仅存在本机 `.env`，**不会提交到 Git**，**不会进入构建产物**
- 摘要文本写入 markdown 文件随 Git 提交，可审阅、可回滚
- 增量生成避免重复调用，省 token 费用

---

## 🔧 配置说明

主要配置位于 `src/config.ts`：

| 配置项 | 说明 |
| :--- | :--- |
| `siteConfig` | 站点标题、副标题、语言、主题色、banner、TOC、favicon |
| `navBarConfig` | 导航栏链接，支持一级与二级菜单 |
| `profileConfig` | 作者头像、昵称、简介、社交链接 |
| `licenseConfig` | 文章页底部版权声明 |
| `expressiveCodeConfig` | 代码块主题（建议选暗色主题） |
| `umamiConfig` | Umami 无 Cookie 分析配置（默认关闭） |
| `commentConfig` | Giscus 评论配置（文章页与友链页共用） |

部署前请确保已配置 `astro.config.mjs` 中的 `site` 字段为实际域名。

---

## 🌐 部署

本项目支持以下平台一键部署：
- [Vercel](https://vercel.com)
- [Cloudflare Pages](https://pages.cloudflare.com)
- [Netlify](https://netlify.com)
- [EdgeOne](https://edgeone.ai)

---

## 📄 许可证

本项目基于 [MIT License](./LICENSE) 开源。

内容遵循 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) 协议。