目录结构

本页说明项目的目录组织方式，依次覆盖顶层结构、src 目录逐文件说明、常用修改入口速查，以及配置文件到页面的数据流。

顶层结构

keqing-birthday-2026/
├── public/                     # 静态资源（原样拷贝到 dist）
│   ├── images/                 # 首页标题图、贺图、头像、音乐封面
│   ├── music/                  # 歌曲文件
│   ├── favicon.png             # 站点图标（标签页 + 导航栏 logo）
│   ├── favicon-32x32.png       # 32×32 图标
│   ├── apple-touch-icon.png    # iOS「添加到主屏幕」图标
│   ├── icons.svg               # SVG 图标精灵（B 站图标）
│   ├── robots.txt              # 搜索引擎爬虫规则
│   ├── sitemap.xml             # 站点地图
│   └── _redirects              # SPA 路由回退（Cloudflare Pages）
├── src/
│   ├── config/                 # ★ 全站配置（改造网站只需改这里）
│   ├── components/             # React 组件
│   ├── context/                # React Context（主题、音乐）
│   ├── hooks/                  # 自定义 Hooks
│   ├── pages/                  # 页面组件
│   ├── assets/                 # 静态资源（Vite 模板自带，一般用不到）
│   ├── styles/                 # 组件级样式
│   ├── App.jsx                 # 路由与页面结构
│   ├── index.css               # 全局样式 + 自动注入的主题 CSS 变量
│   └── main.jsx                # 入口文件
├── scripts/
│   └── prerender.js            # 构建后预渲染（Playwright）
├── index.html                  # HTML 模板（SEO meta 在这里改）
├── tailwind.config.js          # Tailwind 配置（读取 theme.config.js）
├── vite.config.js              # Vite 配置（主题变量注入插件）
├── eslint.config.js            # ESLint 配置
├── postcss.config.js           # PostCSS 配置（Tailwind + autoprefixer）
├── wrangler.toml               # Cloudflare Pages 部署配置
└── package.json

src 目录逐文件说明

src/config/ —— 全站配置（高频修改）

文件	内容	文档
site.config.js	站名、组名、QQ 群、生日日期、备案号	说明
content.config.js	首页板块、贡献者、歌单、页脚	说明
theme.config.js	配色、字体、卡片预设、粒子特效、动效	说明

src/components/ —— React 组件

文件	用途
Navbar.jsx	顶部导航栏（导航链接、外链、音乐按钮、主题切换、移动端菜单）
HeroSection.jsx	首页首屏（大标题图、描述、按钮、贺图轮播、倒计时）
CountdownTimer.jsx	生日倒计时卡片组
Starfield.jsx	首屏星空 + 星云背景（DOM + CSS 动画）
ContentParticles.jsx	内容区粒子背景（花瓣 / 粒子 / 雾气 / 闪电）
FooterParticles.jsx	页脚深色模式上升粒子
CoreContributors.jsx	首页核心贡献者卡片
RecruitPanel.jsx	招募岗位卡片
ContactPanel.jsx	联系方式板块（群号卡片 + 复制按钮）
Footer.jsx	页脚
MusicPlayerWidget.jsx	页面角落的悬浮音乐迷你条（仅 2xl 超宽屏显示）
MusicPlayerCard.jsx	音乐播放卡片（紧凑形态）
ThemeToggle.jsx	主题切换按钮（浅色 / 深色 / 跟随系统）
Toast.jsx	全局轻提示（如「复制成功」）
Glass.jsx / LiquidGlass.jsx	玻璃卡片容器（跟随 preset 预设）
OptimizedImage.jsx	带懒加载的图片组件
icons/BilibiliIcon.jsx	B 站图标（外链用）

src/context/、src/hooks/、src/pages/、src/assets/、src/styles/

文件	用途
context/ThemeContext.jsx + theme-context.js + useTheme.js	主题 Provider（class 切换、localStorage、动画开关属性）与主题 Hook
context/MusicContext.jsx + music-context.js + useMusic.js	音乐播放器状态（歌单、播放、进度、音量、模式）
hooks/useCountdown.js	倒计时 Hook（自动跨年逻辑）
pages/HomePage.jsx	首页（板块注册与渲染）
pages/AllContributorsPage.jsx	全部贡献者页（懒加载）
styles/LiquidGlass.css	液态玻璃等卡片预设样式

关键路径速查

下表按常见修改需求列出对应的修改位置。

需求	修改位置
修改站名 / 群号 / 生日 / 备案号	src/config/site.config.js
修改首页文案 / 贡献者 / 歌单 / 页脚	src/config/content.config.js
更换主题色 / 字体 / 特效	src/config/theme.config.js
更换首页大标题图 / 贺图 / 头像	public/images/
新增歌曲	public/music/ + content.config.js 的 playlist
修改浏览器标签标题 / SEO 描述	index.html
修改导航栏链接 / 外链图标	src/components/Navbar.jsx
新增首页板块	src/components/ 新组件 + src/pages/HomePage.jsx 注册

配置 → 页面的数据流

配置文件中的字段通过三条路径进入页面：CSS 变量、Tailwind 主题扩展，以及组件直接 import。

theme.config.js ──(vite.config.js 注入插件)──> CSS 变量 --page-bg / --accent-purple ...
       │
       ├─(tailwind.config.js)──> keqing-purple / keqing-gold / font-title ...
       │
       └─(组件 import)────────> 粒子颜色数组、动画参数等 JS 值

site.config.js ────> 页脚 / 联系方式 / 倒计时 / 备案号
content.config.js ─> 首页板块 / 贡献者 / 歌单 / 页脚文案

提示

vite.config.js 中的 injectThemeVariables 插件会把 theme.config.js 里的标量值（字符串、数字）拍平成 CSS 变量（如 pageBg → --page-bg），数组则留给组件直接 import。因此修改主题配置无需手写 CSS。