AstroBlog 首页渲染与页面布局

页面组合关系

src/pages/[...page].astro
        ↓
MainGridLayout.astro（hideSidebar）
   ├─ Layout.astro：HTML、主题、持久视频层
   └─ 页面内容
       ├─ HomeHero.astro
       └─ HomePortfolioShutterLayer.astro

Layout.astro 在 <head> 中生成语言、viewport、title、description、Open Graph、Twitter Card、favicon 和字体链接。它还把站点色相、默认主题、壁纸模式和首页视频地址通过 define:vars 注入首屏脚本，确保浏览器第一次绘制前已经确定基础颜色和布局状态。

MainGridLayout.astro 根据 sidebarLayoutConfig、页面 props 和页面类型计算普通页面网格列，处理单侧栏、双侧栏与隐藏侧栏。文章详情现由 ReadingLayout.astro 独立输出，不再通过这套网格承载阅读正文。页面内容使用 CSS Grid 占据中间轨道，侧栏组件由 SideBar.astro 根据配置动态渲染。这个计算集中在布局层，卡片组件不需要知道当前页面是否有左右侧栏。

首页与文章页的数据边界

首页路由通过 getSortedPosts() 参与静态路径生成，实际页面内容只挂载 Hero 和百叶窗层，并传入 hideSidebar。Hero 从 profileConfig 读取展示名称，百叶窗图片和滚动距离来自 homePortfolioShutterConfig.ts；首页没有直接渲染文章卡片或动态列表。

文章列表由 src/pages/posts/[...page].astro 独立生成，查询规则仍由 content-utils.ts 统一维护；侧栏显示条件由布局与 sidebarConfig.ts 决定。详情页改用固定白色阅读文档，字体仍沿用共享角色；首页与详情之间使用完整导航，主站普通页面间继续 Swup。维护首页视觉时进入首页组件，维护文章排序、卡片或分页时进入文章路由，避免让两个页面互相承担对方的职责。

Hero 视频层

首页视频由 HomeVideoLayer.astro 输出视频节点，homeWallpaperPlayer.ts 负责清单读取、候选选择和播放。播放器通过 /api/home-videos 获取启用资源与播放规则，接口不可用时回退缓存或 homeVideoConfig.ts 的内置候选。生产媒体使用 media.yukihime.dev，Layout.astro 在首页提前建立 preconnect 和 DNS 预解析。视频只是视觉背景，导航和页面内容仍由 HTML 输出，因此视频加载失败时页面仍然可用。

背景模式有 banner、overlay 和 none 等状态。布局层根据模式决定主面板是否向 Banner 重叠，setting-utils.ts 在运行时切换 data-wallpaper-mode、wallpaper-transparent 等类名。首页百叶窗覆盖主视觉时，脚本会暂停背景视频，避免不可见的视频继续消耗解码和网络资源。

播放规则支持固定、顺序和随机选择，以及播放结束或定时轮换。视频节点位于 Swup 替换容器之外，同一文档复用一个播放器；离开首页、切到后台标签页或被百叶窗遮挡时暂停播放。维护视频时需要同时检查 homeVideos.ts 的在线清单、homeWallpaperPlayer.ts 的播放状态、组件的 DOM 属性，以及 verify:home-wallpaper 和浏览器回归脚本。

主题和首屏闪烁

主题初始化脚本放在 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 生成，在不同桌面窗口宽度下计算主栏与侧栏的空间。首页通过 hideSidebar 隐藏侧栏，布局中保留的文章页兼容 props 不代表当前详情路由仍使用主网格；阅读文档的左侧目录由独立文章组件输出。这些决定在布局层完成，不由文章内容决定。站点保留非桌面访问拦截，页面验收以桌面浏览器为范围。

首页修改完成后要检查不同桌面窗口宽度下的 Hero、Banner 与内容区域，确认侧栏隐藏状态在刷新和页面切换后保持一致。特别是视频和覆盖层，要确认覆盖层不会挡住导航焦点，视频没有阻塞滚动，没有加载视频时首屏高度仍然稳定。

首页修改入口

修改首页组合，从 src/pages/[...page].astro、HomeHero.astro 和 HomePortfolioShutterLayer.astro 开始；修改页面外壳，从 Layout.astro、MainGridLayout.astro 开始；修改首页视频，从 HomeVideoLayer.astro、homeWallpaperPlayer.ts 和 homeVideos.ts 开始；修改侧栏，从 sidebarConfig.ts 和 SideBar.astro 开始；修改单个卡片或小部件，只进入对应的 src/components/ 文件。

首页的稳定性依赖这些层之间的契约：路由负责选择布局，布局负责空间，配置负责开关，组件负责内容，脚本负责浏览器状态。把新功能放入对应层，才能避免首页文件越来越长，也能让其他页面复用同一套布局逻辑。

HomeHero 和百叶窗

根路由只挂载两个首页专用组件：HomeHero.astro 负责主视觉装饰和入场动画，HomePortfolioShutterLayer.astro 负责图片面板、滚动过渡和小屋入口。两者都位于 src/components/layout/，而不是 src/pages/ 中直接写大量 HTML。百叶窗层通过播放器提供的暂停与恢复方法协调背景视频，避免遮挡期间仍持续播放。

新增首页入口时，先确定它属于公共导航还是首页组件，再核对目标页面开关、sitemap 和桌面布局。小屋入口打开独立站点，需要保留适当的 target、rel 和页面切换边界，避免把外部页面作为主站容器替换。

空状态和静态输出

媒体清单应当允许关闭或没有可播放资源，此时播放器保持空背景，不影响导航和内容区域。文章、动态、书籍和友链页面则由各自组件处理空状态。不要用虚构内容撑布局，这会污染 Pagefind、RSS 和归档。

首页结构和链接在构建时确定，视频清单与播放规则由客户端请求增强。维护时要保留这个边界，不能为了获取当前壁纸列表，让整个 Astro 构建依赖一次远程请求成功。

首页修改的回归范围

首页改动至少会影响三种输出：静态 HTML 的结构、壁纸和主题的首屏脚本、以及 Swup 后续替换时的容器状态。新增模块如果包含客户端脚本，应确认脚本是否需要在 page:view 重新执行；如果模块只在首页出现，还要确认从其他普通页面 Swup 返回首页时它能重新挂载，以及从文章阅读文档完整导航返回时首屏初始化正常。

构建后可以直接检查 dist/index.html 的主视觉、导航和小屋链接，再用浏览器检查视频、遮罩和交互。不要只打开开发服务器，因为开发环境的 Vite HMR 会掩盖缺少静态输出或脚本重复执行的问题。