blog-fuwari/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

基于 Fuwari 的静态博客，使用 Astro 6.1 + TailwindCSS 3.4 + Svelte 5。

• 包管理器: pnpm 9（preinstall hook 强制只允许 pnpm）
• 语言: TypeScript (strict)
• 代码规范: Biome（同时负责 format 和 lint），无 ESLint/Prettier
• 部署: Cloudflare Pages（见 wrangler.toml）

常用命令

命令	用途
pnpm dev	启动本地开发服务器 (localhost:4321)
pnpm build	构建生产版本到 ./dist/ 并运行 Pagefind 索引
pnpm preview	本地预览构建产物
pnpm check	运行 Astro 类型检查
pnpm type-check	运行 TypeScript 类型检查 (tsc --noEmit)
pnpm format	Biome 格式化 ./src
pnpm lint	Biome 检查和修复 ./src
pnpm new-post <filename>	在 src/content/posts/ 创建新文章 Markdown
pnpm astro	直接调用 Astro CLI

项目结构

src/
├── config.ts              # 站点主配置（标题、导航、个人资料、许可证等）
├── content.config.ts      # Astro Content Collections 定义（posts + spec）
├── content/
│   ├── posts/             # 博客文章（.md / .mdx），通过文件系统集合加载
│   └── spec/              # 特殊页面集合
├── components/
│   ├── widget/            # 侧边栏组件（Profile, TOC, Tags, Categories 等）
│   ├── control/           # 交互控件（BackToTop, Pagination, ButtonLink 等）
│   ├── misc/              # 杂项（ImageWrapper, License, Markdown）
│   └── *.astro/*.svelte   # 页面级组件（Navbar, Footer, Search, PostPage 等）
├── pages/
│   ├── [...page].astro    # 首页分页路由
│   ├── posts/[...slug].astro  # 文章详情页
│   ├── archive.astro      # 归档页
│   ├── about.astro        # 关于页
│   ├── friends.astro      # 友链页
│   ├── rss.xml.ts         # RSS 生成
│   └── robots.txt.ts      # robots.txt
├── layouts/
│   ├── Layout.astro       # 根布局（SEO、主题、Umami 分析、PhotoSwipe）
│   └── MainGridLayout.astro # 主网格布局（导航栏、Banner、侧边栏、TOC）
├── plugins/               # Remark/Rehype 插件 + Expressive Code 插件
├── i18n/                  # 多语言翻译（en, zh_CN, ja, ko 等）
├── utils/                 # 工具函数（content-utils, date-utils, url-utils, setting-utils）
├── types/                 # TypeScript 类型定义
├── constants/             # 常量（分页大小、主题模式、Banner 高度等）
└── styles/                # CSS 文件（main.css, markdown.css, scrollbar.css 等）

关键架构信息

内容管理

• 文章以 Markdown/MDX 格式存储在 src/content/posts/
• 使用 Astro Content Collections 加载，schema 在 content.config.ts 中定义
• 文章 frontmatter 包含: title, published, description, image, tags, category, draft, lang, showcover, customcover 等

路由

• [...page].astro — 首页分页
• posts/[...slug].astro — 文章详情页，生成 JSON-LD 结构化数据
• archive.astro — 归档，tags，categories
• 自定义页面: about.astro, friends.astro

路径别名（tsconfig 配置）

• @/* → src/*，@components/* → src/components/*，@assets/* → src/assets/*
• @utils/* → src/utils/*，@i18n/* → src/i18n/*
• @layouts/* → src/layouts/*，@constants/* → src/constants/*

页面过渡

• 使用 Swup 实现 SPA 风格页面过渡
• 支持自定义滚动条 (OverlayScrollbars)，图片点击放大 (PhotoSwipe)

Markdown 扩展

• GitHub Admonitions (note, tip, important, caution, warning)
• GitHub 仓库卡片，数学公式 (KaTeX)
• 扩展代码块 (Expressive Code) 支持折叠、行号、复制按钮、语言徽章
• 自动标题锚点链接

外部服务

• 分析: Umami（自建）+ Google Analytics
• 评论: Giscus（基于 GitHub Discussions）
• 搜索: Pagefind（构建时生成搜索索引）
• 统计: 通过 Umami API 获取文章浏览量

注意事项

• src/config.ts 是站点配置中心
• 构建会先运行 astro build，然后执行 pagefind --site dist 生成搜索索引
• Biome 不处理 CSS 文件（在 biome.json 中排除）
• Svelte 组件使用 Svelte 5 语法
• 主题色基于 CSS 变量 --hue 动态计算
• 不要执行构建，除非特别要求