Astro 以及 Planet Source-of-USTB
Published on: 2026-07-17
Written by: Siriuns
description: 简单介绍一下文件结构
本文记录了 Planet Source-of-USTB 的一些基本文件结构, 这个项目用的是 Astro, 可以作为 Astro 项目的简单参考.
Astro 是一个 JS web 框架, 可以用来搭建网站, 其特点是静态优先, JS少, 从而减少运行负担.
这网站能维护下去吗(?)
0. 创建项目与模板文件
运行 npm create astro@latest 即可在当前目录下创建一个 Astro 项目, 一般长这样:
.
├── public/
├── src/
├── .vscode/
├── astro.config.mjs
├── .gitignore
├── package.json
├── README.md
└── tsconfig.json依赖放在 node_modules/, 公共资源放在 public/, 核心源码在 src/.
1. Astro 的核心文件结构
在 Astro 框架下, 网站的大部分改动在 src/ 下, 一般会有类似 components/, layouts/, pages/ 等文件夹.
1.1. components
components/ 下一般放可复用的组件, 比如 Footer, Header 这种, 还有类似自己写的 LineChart, GlassCard 等, 会通过 Astro.props 这个函数来接受调用处传入的参数, 举个例子, 如果我们有这样的一个组件 Px:
---
// src/components/Px.astro
const { x } = Astro.props;
---
<p>{x}</p>然后在别处调用
---
// src/pages/index.astro
import Px from '../components/Px.astro';
---
<Px x=0 />页面上此处就会被替换成 <p>0</p>
1.2. layouts
layouts/ 下面往往是页面的基础模板, 会有 <slot /> 这种用于注入的标识, 调用方式其实和 component 差不多. 比如一个简单的 layout:
---
// /src/layouts/BaseLayout.astro
const { y } = Astro.props;
---
<p>{y}</p>
<slot />
<p>{y+1}</p>然后如此调用
---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout y=0>
<p>2</p>
<BaseLayout />
页面就会变成
<p>0</p>
<p>2</p>
<p>1</p>1.3. pages
pages/ 下面一般是具体页面, 比如 index.astro 这种, 对于博客网站一般还会有子目录 posts, 用来放 markdown 文章, 以本文为例, 其结构一般如下(还有自指)
---
layout: ../../layouts/MarkdownPostLayout.astro
title: 'Astro 以及 Planet Source-of-USTB'
pubDate: 2026-7-17
description: '文件结构简介'
author: 'Siriuns'
tags: ['Astro']
---
这是正文2. Planet Source-of-USTB 的结构
src/
├── components/
├── data/
│ ├── generated/ // 自动生成的构建页面用数据
│ └── members.ts // 手动更改的成员数据
├── layouts/
├── pages/
│ ├── about.astro
│ ├── history/
│ │ ├── index.astro // history路由下的主页面
│ │ └── [memberId].astro // 根据 memberId 生成的静态网页
│ ├── index.astro
│ ├── members.astro
│ └── rss.xml.ts // 用来生成 rss.xml
public/
└── avatars/ // 头像2.1. 添加成员
要添加一个成员, 只需要在 members.ts 中按照模板填入对应的网站信息, 然后在 public/avatars/ 下放入头像即可, 要保证网站开启了 rss.
2.2. 自动构建网页
在 scripts/ 下, 放了几个脚本, 是用来获取/维护数据用的. 在 .github/workflows/ 下有两个定时触发的 ci, 其中 deploy.yml 是自动构建 ci, 每周自动执行, 会调用 scripts/ 下的 build-member-map.ts, fetch-feeds.ts, build-post-counts.ts, 来更新数据, 然后构建网站并部署到 git pages.
2.2. 文章计数维护
网站有一个 post-counts.json, 用来存储每次构建网站时的 总文章数和每个人的文章数, 用来画 history 路由下面的网页. 存在的问题是: 每次完全根据 rss 来, 有可能生成rss的时候限制了只展示最新的 20 篇文章之类的; 但是如果只增不减, 又会导致网站还保留着被删除的文章. 所以 .github/workflow/ 下面还有一个 audit-links.yml, 一个月定时执行一次, 不直接删除文章而是写入 data/review/, 需要人工审查.
-1. misc
在 src/assets/fonts 下有三个字体文件, 是思源宋体, 网站的 css 里面指定了字体是宋体, 虽然有办法能让网页被访问的时候去 google 那边下载字体, 但是不知道会不会被墙, 遂改称了直接存着.
src/styles/ 下是全局 css(网站还没有美化过), src/type 下面是提取出来的 ts 类型, src/utils/ 下面是提取出来的函数(好像没啥提取的必要).
public/icon/ 下面放了网站的图表, 从 Material Symbols and Icons 上下载下来的(很神秘啊).