AstroBlog 首页不是一个单独的大组件，而是由页面路由、全局布局、网格布局和多个功能模块组合出来的。维护首页时，先区分页面内容与页面外壳：根路由 src/pages/[...page].astro 决定首页挂载 HomeHero.astro 和百叶窗层，src/layouts/Layout.astro 负责 HTML、主题、元信息和客户端初始化，src/layouts/MainGridLayout.astro 负责 Banner、主栏和侧栏的空间关系。
页面组合关系
src/pages/[...page].astro ↓Layout.astro ↓MainGridLayout.astro ┌────┼──────────────┐ Banner Main content SideBar │ │ │ video recent posts widgetsLayout.astro 在 <head> 中生成语言、viewport、title、description、Open Graph、Twitter Card、favicon 和字体链接。它还把站点色相、默认主题、壁纸模式和首页视频地址通过 define:vars 注入首屏脚本，确保浏览器第一次绘制前已经确定基础颜色和布局状态。
MainGridLayout.astro 根据 sidebarLayoutConfig 和当前是否为文章页计算网格列。单侧栏、双侧栏、隐藏侧栏和文章页临时显示双侧栏都有不同的响应式类。页面内容使用 CSS Grid 占据中间轨道，侧栏组件由 SideBar.astro 根据配置动态渲染。这个计算集中在布局层，卡片组件不需要知道当前页面是否有左右侧栏。
首页模块的数据来源
首页的内容模块直接读取内容集合或配置：最近文章来自 getSortedPostsList()，动态来自 getPublicMoments()，站点公告和每日引用来自 siteConfig.portal，侧栏顺序来自 sidebarConfig.ts。文章卡片只接受经过整理的 entry，不会在组件内再次调用 getCollection()。
这种组合方式让首页只负责布局，文章查询规则仍由 content-utils.ts 统一维护；关闭某个模块时只需要修改配置或对应组件，不需要修改文章 Schema。模块的空状态也在自己的组件内处理，不会让首页出现一大段条件判断。
Hero 视频层
首页视频由 HomeVideoLayer.astro 和布局中的壁纸容器负责。视频地址来自首页壁纸配置，生产环境使用 media.yukihime.dev，Layout.astro 在首页提前建立 preconnect 和 DNS 预解析。视频只是视觉背景，标题、导航、最近文章和交互按钮仍然是普通 HTML，因此视频加载失败时页面仍然可用。
背景模式有 banner、overlay 和 none 等状态。布局层根据模式决定主面板是否向 Banner 重叠，setting-utils.ts 在运行时切换 data-wallpaper-mode、wallpaper-transparent 等类名。首页百叶窗覆盖主视觉时，脚本会暂停背景视频，避免不可见的视频继续消耗解码和网络资源。
维护视频时需要同时检查壁纸配置候选资源、HomeVideoLayer.astro 的 DOM 属性、setting-utils.ts 的模式切换逻辑，以及 verify-home-wallpaper 和浏览器回归脚本。只替换 URL 而不更新候选数据，可能导致刷新后选择状态和实际视频节点不一致。
主题和首屏闪烁
主题初始化脚本放在 Layout.astro 的 <head>，它先读取 localStorage，再依据默认模式写入 html.dark、data-theme 和 CSS 变量。运行时切换由 src/utils/setting-utils.ts 的 setTheme、applyThemeToDocument 和 initThemeListener 负责。首屏初始化和运行时切换必须使用相同的模式名称，否则页面会先以浏览器默认颜色绘制，再跳到博客主题。
页面布局也在首屏脚本中设置。Banner 高度、主内容宽度和色相通过 define:vars 传入，避免在 JavaScript 中重新读取构建时配置。修改页面宽度或 Banner 高度时，不要只调整某个 CSS 类，还要检查 MainGridLayout.astro 的计算值和 Layout.astro 的首屏类名。
响应式布局
侧栏布局由 responsive-utils.ts 生成。桌面端可以显示左右侧栏，平板端根据 tabletSidebar 选择保留一侧，移动端则将侧栏移动到主内容之后或隐藏。首页和文章页的侧栏策略不同：文章页可以通过 showBothSidebarsOnPostPage 临时启用对侧组件，但这个决定在布局层完成，不由文章内容决定。
首页修改完成后要检查桌面端的 Banner 与双栏宽度、平板端的侧栏收缩、移动端的主内容顺序。特别是视频和覆盖层，要确认覆盖层不会挡住导航焦点，视频没有阻塞滚动，没有加载视频时首屏高度仍然稳定。
首页修改入口
修改首页模块顺序，从 src/pages/[...page].astro、HomeHero.astro 和 siteConfig.portal 开始；修改页面外壳，从 Layout.astro、MainGridLayout.astro 开始；修改 Banner 或视频，从 HomeVideoLayer.astro、壁纸配置和 setting-utils.ts 开始；修改侧栏，从 sidebarConfig.ts 和 SideBar.astro 开始；修改单个卡片或小部件，只进入对应的 src/components/ 文件。
首页的稳定性依赖这些层之间的契约：路由负责选择布局，布局负责空间，配置负责开关，组件负责内容，脚本负责浏览器状态。把新功能放入对应层，才能避免首页文件越来越长，也能让其他页面复用同一套布局逻辑。
HomeHero 和百叶窗
根路由只挂载两个首页专用组件：HomeHero.astro 负责门户主视觉、头像、站点标题和入口按钮，HomePortfolioShutterLayer.astro 负责首页进入后的遮罩和过渡。两者都位于 src/components/layout/，而不是 src/pages/ 中直接写大量 HTML。百叶窗层会在状态完成后移除或降低遮罩，期间首页视频保持可控播放状态。
如果要新增一个首页入口，通常需要同时修改 HomeHero 的链接结构、siteConfig 中的页面开关、对应页面的 sitemap 过滤和移动端样式。入口如果需要打开房间或外部站点，还要确认 target、rel、prefetch 和 Swup ignore 规则，避免把独立页面错误地作为主站容器替换。
空状态和静态输出
首页模块应当接受空数组。最近文章为空时，PostPage 显示明确的空状态；动态、书籍或友链为空时，各自组件返回空状态或隐藏。不要在首页用“至少插入一条假数据”的方式撑布局，这会污染 Pagefind、RSS 和归档。
首页是静态构建的，模块中的日期、文章标题和链接在构建时确定。需要实时数据的功能，例如访客数量或音乐播放状态，只能通过客户端脚本或 Worker API 增强，不能在 Astro 构建时依赖一个不稳定的远程请求。
首页修改的回归范围
首页改动至少会影响三种输出：静态 HTML 的结构、壁纸和主题的首屏脚本、以及 Swup 后续替换时的容器状态。新增模块如果包含客户端脚本，应确认脚本是否需要在 page:view 重新执行；如果模块只在首页出现，还要确认 Swup 从文章页返回首页时它能重新挂载。
构建后可以直接检查 dist/index.html 是否包含标题、导航和最近文章的可索引文本，再用浏览器检查视频、遮罩和交互。不要只打开开发服务器，因为开发环境的 Vite HMR 会掩盖缺少静态输出或脚本重复执行的问题。