首页板块与路由

本页说明网站的路由结构、首页板块的渲染机制、导航栏的配置方式，以及各组件与配置来源的对应关系。

路由

网站只有两个路由（src/App.jsx），对比如下表所示：

路径	页面	加载方式
/	首页 HomePage	同步加载
/contributors	全部贡献者 AllContributorsPage	React.lazy 懒加载 + Suspense 过渡动画

两个路由共享的全局组件结构如下：

App
├── ThemeProvider        主题（浅色/深色/跟随系统）
├── MusicProvider        音乐播放器状态
└── BrowserRouter
    ├── Navbar           顶部导航栏（含音乐按钮、主题切换）
    ├── Routes
    │   ├── /            → HomePage
    │   └── /contributors → AllContributorsPage（懒加载）
    └── MusicPlayerWidget 全局悬浮音乐播放器

提示

/contributors 使用懒加载，首屏不会下载该页面的代码，减小初始加载体积。切换页面时播放器挂在外层，音乐不会中断。

首页板块渲染机制

首页内容完全由 content.config.js 的 homeSections 驱动，src/pages/HomePage.jsx 负责渲染：

1. 过滤出 status === 'enable' 的板块
2. id === 'hero' 的板块单独渲染在最上方（全屏首屏，不占内容流）
3. 其余板块按数组顺序渲染，统一包裹在 ContentParticles 粒子层里
4. 页面末尾渲染 <Footer />

板块 id 与组件的对应关系在 sectionComponents 中注册：

const sectionComponents = {
  hero: HeroSection,
  coreContributors: CoreContributors,
  recruit: RecruitPanel,
  contact: ContactPanel,
};

注意

id 是板块与组件之间的查找键。改名会导致该板块渲染为空。新增板块的正确做法见 新增板块与组件。

导航栏（Navbar）

顶部导航栏由 src/components/Navbar.jsx 实现，不由配置文件驱动。调整导航时，修改该文件中的三个数组：

// 左侧：首页 + 页面内锚点
const navLinks = [
  { id: 'home', label: '首页', to: '/' },
  { id: 'recruit', label: '招募信息', to: '/#recruit' },
  { id: 'contact', label: '联系方式', to: '/#contact' },
];

// 右侧：独立页面
const rightNavLinks = [
  { id: 'contributors', label: '贡献者', to: '/contributors' },
];

// 外链图标区（新窗口打开）
const externalLinks = [
  { label: 'B站', href: 'https://space.bilibili.com/...', icon: BilibiliIcon },
];

三个数组的显示位置与 to 的写法如下表所示：

数组	显示位置	to 的写法
navLinks	导航栏左侧	'/' 是路由；'/#xxx' 是首页内锚点（自动平滑滚动）
rightNavLinks	导航栏右侧	独立页面路由
externalLinks	右侧图标区	完整 http(s) 链接，新窗口打开；清空数组则整块隐藏

导航栏的其它行为：

• 首页封面模式：浅色模式下滚动条位于首屏时，导航栏自动切换为深色外观（因为首屏本身就是深色的星空背景），滚出首屏后恢复
• 音乐按钮：歌单非空时显示，点击弹出播放器卡片；超宽屏（2xl）下隐藏（由页面角落的悬浮条接管）
• 移动端：折叠为汉堡菜单，菜单项带依次淡入的过渡动画

板块间导航

Hero 的「立即加入」「了解更多」按钮通过 targetId 平滑滚动到页面内对应板块：

primaryButton:   { text: '立即加入', targetId: 'recruit' },
secondaryButton: { text: '了解更多', targetId: 'contact' },

targetId 填写目标板块的 id。从 /contributors 页面点击导航栏的锚点链接时，会先路由回首页，再自动滚动到目标板块。

组件一览

全部组件及其配置来源如下表所示：

组件	位置	作用	主要配置来源
Navbar	全站顶部	导航栏	组件内 navLinks 等数组
HeroSection	首页首屏	大标题、描述、按钮、贺图轮播、倒计时	content.config.js hero 板块 + theme.config.js home.hero
CountdownTimer	Hero 内	生日倒计时	site.config.js birthday
Starfield	Hero 背景	DOM 星空 + 星云（CSS 动画）	theme.config.js effects.starfield + home.hero
ContentParticles	内容区背景	花瓣 / 粒子 / 雾气 / 闪电	theme.config.js effects.contentParticles
CoreContributors	首页	核心贡献者卡片	content.config.js coreContributors
RecruitPanel	首页	招募岗位卡片	content.config.js recruit
ContactPanel	首页	QQ 群卡片 + 复制群号	content.config.js contact + site.config.js qqGroup
Footer	页面底部	页脚	content.config.js footerConfig + site.config.js
FooterParticles	页脚背景	深色模式上升粒子	theme.config.js effects.footerParticles
MusicPlayerWidget / MusicPlayerCard	全局	悬浮音乐播放器	content.config.js playlist
ThemeToggle	导航栏	主题切换按钮	——
Toast	全局	轻提示（如「群号已复制」）	theme.config.js effects.toast
OptimizedImage	通用	懒加载图片	——
LiquidGlass / Glass	通用	玻璃卡片容器	theme.config.js preset