文章信息

标题: 网站初步建成：架构说明与改版记录
发布时间: 2026 年 5 月 4 日
最近更新: 2026 年 6 月 20 日
来源: https://physchen.com/zh-Hans/blog/site-initial-build-log/
摘要: physchen.com 静态站的内容集合、双语路由、页面分工、图片管线、搜索/RSS 与工程改版的客观记录。

网站初步建成：架构说明与改版记录

2026 年 5 月 4 日 ·

最近更新： 2026 年 6 月 20 日

本文记录站点在 Astro 5 上的静态架构，以及后续工程层面的调整。

技术栈

层	选型
框架	Astro 5（`output: 'static'`）
交互	React（搜索、部分客户端脚本）
样式	全局 CSS + Tailwind 4
公式	`remark-math` + `rehype-katex`
搜索	Pagefind（构建后索引 `dist/`）
部署	GitHub Actions → rsync → Nginx 静态目录

构建命令：pnpm assets:sync && astro build && pagefind --site dist。

内容模型

内容集合定义于 src/content.config.ts：

集合	路径	用途
`blog`	`src/content/blog/{zh-Hans,en}/`	日志
`physics`	`src/content/physics/{zh-Hans,en}/`	物理文章
`programming`	`src/content/programming/{zh-Hans,en}/`	编程文章
`teaching`	`src/content/teaching/{zh-Hans,en}/`	教学文章
`pages`	`src/content/{about,index}.*.mdx`	关于页与首页 SEO 元数据

文章集合共用 frontmatter：title、description、pubDate、updatedDate、tags、categories、permaLink、pinned、draft、comments、heroImage、author（comments 省略默认启用，仅 false 关闭该篇评论）。

pages 集合不含 pubDate 必填约束；about.*.mdx 走 MDX 正文渲染，index.*.mdx 仅被路由读取 title 与 description（见下文首页分工）。

已发布内容经 getPublishedCollection() 过滤 draft: true。

双语路由

采用物理隔离：中英文内容分目录，路由分前缀，而非单页内切换文案。

语言	URL 前缀	内容目录后缀
简体中文	`/zh-Hans/`	`zh-Hans/`
英文	`/en/`	`en/`

astro.config.mjs：prefixDefaultLocale: true，redirectToDefaultLocale: false。

根路径 /（src/pages/index.astro）：

构建时输出中文首页静态 HTML（供爬虫抓取）。
浏览器端 LocaleRedirect.astro 按 localStorage.locale-preference 或 navigator.languages 跳转至 /zh-Hans/ 或 /en/。
禁用 JavaScript 时停留在根页中文 HTML。

文章 URL 由 src/utils/post-taxonomy.ts 统一生成，格式为 /{locale}/{collection}/{slug}/；slug 优先取 permaLink，否则由文件 id 推导。

各集合另有 /categories/[category]、/tags/[tag] 归档路由；旧路径 /blog/categories/... 等保留为兼容跳转。

页面分工

首页

组件 / 文件	职责
`src/pages/{zh-Hans,en}/index.astro`	读取 `pages` 集合中对应 `index.*.mdx` 的元数据
`src/components/HomePageLayout.astro`	`<head>` SEO、`SeoJsonLd`、页壳
`src/components/HomeLanding.astro`	Hero、五栏目卡片、各集合精选文章、摄影条带
`src/content/index.*.mdx`	仅 `title`、`description`（无正文渲染）

文章详情

src/layouts/BlogPost.astro：hero 图、日期、语言切换、MDX 正文；Waline 评论区已接入但全站默认关闭（waline-config.ts → enabled: false）。Hero 解析见 src/utils/hero-image.ts。

文章列表

src/components/PostIndexPage.astro：置顶双栏（pinned: true 或最新一篇）、双列列表、分类/标签筛选入口。

关于页

src/pages/{locale}/about.astro 渲染 about.*.mdx 全文。

摄影

摄影不占用 content collection；数据来自 src/assets/photos/ 与 config.json，由 src/utils/photography.ts 装配。

路由	组件
`/{locale}/photography/`	`PhotographyIndexPage.astro`
`/{locale}/photography/[category]/`	`PhotographyCategoryPage.astro`
首页条带	`PhotographyStrip.astro`

文章系统配置

栏目级行为集中在 src/utils/post-collection-config.ts：

enableCategories：是否生成分类归档页。
categoryArticleNavigation：从分类页进入文章后，前后篇是否限定在该分类内（当前四集合均为 category）。
各栏目中英文列表标题与筛选文案。

列表排序（orderPostsForIndex）：置顶文优先，其余按 pubDate 降序；多篇 pinned: true 时取日期最新者占顶栏。

前后篇逻辑在 src/utils/post-routing.ts，支持带分类/标签筛选上下文。

评论区（Waline）：

全站开关：src/utils/waline-config.ts → enabled（当前默认 false）
文章级：全站启用后，frontmatter comments 省略或 true 显示入口；comments: false 关闭该篇
实现：WalineComments.astro + discussion-lazy.ts / discussion-mount.ts（点击后懒加载），挂载于正文下方

图片管线

两套目录：

类型	原图（不进 Git）	展示（进 Git）
普通图	`src/assets/images-originals/`	`src/assets/images/*.avif` + `config.json`
摄影	`src/assets/photos-originals/<分类>/`	`src/assets/photos/` + `config.json`、`featured.json`、`_category.json`

同步脚本：script/prepare-photos.mjs（pnpm assets:sync）。展示图 avif，长边 ≤ 2048px；展示目录镜像原图目录结构。

行为开关（src/consts.ts → SITE_IMAGE_SETTINGS）：

enableAstroImageOptimization
enableOriginalImageOnZoom（放大时是否请求服务器 /files/images-originals/ 等原图）

全站图片放大由 Header.astro 内联 lightbox 实现（site-lightbox）。

RSS 与搜索

RSS（src/pages/{locale}/rss.xml.js）：

聚合 blog、physics、programming 已发布文章（不含 teaching）。
中文源用 SITE_DESCRIPTION，英文源用 SITE_DESCRIPTION_EN（src/consts.ts）。

搜索：

构建末尾执行 pagefind --site dist。
UI：Header.astro 原生弹窗 + SearchResults.jsx + SearchResultList.jsx；pnpm dev 禁用输入，请用 pnpm build && pnpm preview 验证。

部署

git push → GitHub Actions 构建 dist/ → rsync 至服务器静态根目录。rsync 排除服务器上的 /files/images-originals/ 与 /files/photos-originals/。

改版记录

2026-05-04（初版）

五集合内容模型与 post-taxonomy 路径生成落地。
中英文并行路由、HomeLanding 首页、Pagefind 搜索、RSS 三集合聚合。
摄影模块与 prepare-photos.mjs 同步链路接入。

2026-06-20

首页 SEO 分工：index.*.mdx 删去未渲染正文，仅保留 frontmatter；视觉层仍由 HomeLanding.astro 负责。
站点描述：consts.ts 扩展 SITE_DESCRIPTION，新增 SITE_DESCRIPTION_EN 供英文 RSS 使用。
死代码清理：删除未引用的 Aside.astro、MediumZoom.jsx，移除 medium-zoom 依赖；删除 global.css 中 sidebar 遗留规则；lightbox loader 类名改为 site-lightbox__loader-ring。
分类元数据：IBDP.md 的 categories 由「IB 物理」改为 IBDP；部分 programming 英文 category 与中文对齐。
开发文档：重写 .github/copilot-instructions.md 以匹配当前多集合架构。

2026-06-25

子目录分类：physics / programming / teaching / blog 启用文件夹分类路由与子索引页；支持栏目/子目录 index.md 导语；pubDate / description 对索引文可选。
导航与搜索：桌面端分类下拉、移动端横向子分类、一级菜单分割线与毛玻璃遮罩；搜索改为原生弹窗 + SearchResults.jsx，修复 preview 下关闭与结果滚动。
内容迁移：物理/编程/教学文章迁入子目录；astro.config.mjs 保留部分旧物理路径重定向。

2026-06-23

Waline 评论区：接入 @waline/client，自托管服务端 comment.physchen.com；点击懒加载；全站默认关闭（waline-config.ts → enabled: false）。
站点图标：public/ favicon 资源包 + BaseHead.astro 引用。
文档：README 与 copilot 说明补充评论区、图标配置与启用步骤。

计划中的架构改动

以下项针对站点结构与体验，不涉及栏目发稿计划。

首页与栏目入口：在现有 HomeLanding 上调整布局层次与区块结构。
文章系统：归档页、列表页信息密度，以及分类/标签/搜索的发现路径。
交互与响应式：移动端导航、lightbox、文章前后篇行为的一致性。
摄影模块：分类页、单张查看与首页精选条带的展示逻辑。
工程与元数据：路由对称性、content schema、SEO 元数据分工、构建部署链路与依赖维护。