👋 介绍

关于我们

这个网站由 25 级计算机应用 1 班 的同学自发创建与维护。我们希望把班级里那些有趣的、实用的、值得记录的瞬间，沉淀到一个可以长期访问的地方，让每一位同学都能在这里找到属于自己的回忆。

项目原理

项目的源代码托管在 GitHub 上，使用 Vercel 进行自动化的网站部署，并借助 GitHub Actions 完成 CI 流程。每一次提交代码后，网站都会自动构建并发布，无需人工干预。

分享什么

只要是班级或学校中发生的有趣、实用、新鲜的事，并且内容可以公开，我们都会在网站上分享出来。这里既可以是课堂上的小发现，也可以是社团活动、校园风景、学习心得，或是任何值得被记住的瞬间。

🚀 项目

技术栈

• Astro — 静态站点生成器，提供极快的页面加载速度与现代化的开发体验
• TypeScript — 为 JavaScript 加上静态类型支持，让代码更健壮、更易于维护
• Bun 1.4+ — 包管理器与构建工具，负责安装依赖、运行脚本与打包
• Node.js 22.12+ — Vercel 函数运行时（/api/status）
• Vercel — 托管与部署平台，提供全球 CDN 与自动化发布能力
• GitHub Actions — 持续集成与持续部署（CI/CD）工具
• Upstash Redis — Serverless Redis 数据库，用于状态卡片数据存储

项目结构

项目包含以下主要功能模块：

• 首页 (/) — 展示班级概览与快捷入口
• 关于页面 (/about) — 介绍班级与网站信息
• 状态页面 (/status) — 展示班级公告、安排与近况，按时间倒序排列
• 状态接口 (/api/status) — 从 Upstash Redis 中获取状态卡片数据
• 数据初始化脚本 (scripts/seed-status.mjs) — 向 Upstash Redis 写入初始状态卡片数据

状态页面行为

状态页面 (src/pages/status.astro) 在客户端通过 fetch('/api/status') 拉取数据（cache: 'no-store' 确保实时），并按 time 字段倒序渲染卡片。页面内置三种状态：

• 加载中：展示带脉冲动画的骨架屏
• 空状态：无数据时显示“暂无状态卡片”
• 错误状态：请求失败时显示“加载失败，请稍后重试”

每张卡片渲染标题、正文（保留换行 whitespace-pre-wrap）、标签（badge 样式）和格式化后的时间。所有用户内容均经过 HTML 转义，防止 XSS 注入。

状态接口

状态接口 (src/pages/api/status.ts) 仅提供 GET /api/status 读取功能，设置了 prerender = false 以在请求时实时读取 Redis 数据。接口通过 normalizeCards() 兼容 Upstash SDK 返回的数组或 JSON 字符串两种格式，确保返回值始终为数组。写入操作不通过接口完成。

数据初始化脚本

scripts/seed-status.mjs 用于向 Upstash Redis 的 status_cards 键写入初始数据：

bun scripts/seed-status.mjs

Bun 会自动加载 .env.local（无需 --env-file）。脚本使用 @upstash/redis SDK（自动对数组/对象执行 JSON.stringify），写入后会回读数据并打印以验证写入成功。

数据格式

状态卡片数据存储在 Upstash Redis 的 status_cards 键中，格式为 JSON 数组。每张卡片包含以下字段：

• id — 卡片唯一标识
• title — 标题
• content — 正文内容
• time — ISO 8601 格式的时间戳
• tags — 标签数组

环境变量

状态页面功能需要配置 Upstash Redis。在项目根目录创建 .env.local 文件：

UPSTASH_REDIS_REST_URL=your_upstash_redis_rest_url
UPSTASH_REDIS_REST_TOKEN=your_upstash_redis_rest_token

从 Upstash Redis 控制台获取这些凭据：https://upstash.com/

注意：状态卡片数据通过 Upstash 控制台或 CLI 管理，接口仅提供读取功能。

安全审计

在 npmmirror 等国内镜像源下，安全审计接口可能不可用。审计请使用官方源：

bun audit --registry=https://registry.npmjs.org

修复依赖漏洞同理：

bun audit fix --registry=https://registry.npmjs.org

本地构建

在开始之前，请确保你的电脑上已经安装了 Bun 1.4 或更高版本（Node.js 22.12+ 仅在 Vercel 函数运行时使用）。

# 克隆仓库
git clone https://github.com/mantoujun-lab/class-website.git # git
gh repo clone mantoujun-lab/class-website # Github CLI

# 进入项目目录
cd class-website

# 安装依赖
bun install

# 启动本地开发服务器
bun run dev

# 构建生产版本
bun run build

# 运行单元测试
bun run test

# 本地预览构建产物
bun run preview

启动开发服务器后，打开浏览器访问 http://localhost:4321 即可预览网站。

部署

项目已配置 Vercel 适配器，可直接部署到 Vercel：

1. 将仓库连接到 Vercel
2. 在 Vercel 控制台中添加环境变量 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN
3. 触发部署

Vercel 适配器已在 astro.config.mjs 中配置完成。

如需部署到其他平台，可参考 Astro 部署指南，支持 Netlify、Cloudflare Pages 等多种平台。

🤝 贡献

提出建议

如果你对网站有任何想法或建议，欢迎通过 GitHub Issues 提出。无论是新的功能、内容的策划，还是页面的小改进，我们都非常乐意倾听。

参与贡献

欢迎任何 同学/校友/外部开发者 参与到项目中来。贡献的方式非常多样：

• 🐛 提交 Issue 反馈 Bug 或提出建议
• 💡 发起 Pull Request 贡献代码或内容
• ✍️ 撰写并分享班级故事、校园资讯
• ⭐ 给项目点个 Star，这是对开发者最大的支持

在提交 Pull Request 之前，请先 Fork 仓库并创建一个新的分支。提交信息建议遵循项目中的约定式提交规范（Conventional Commits），例如 feat: 新增留言板页面、fix: 修复首页图片加载异常 等。

赞赏开发者

如果你愿意支持，可以扫描下方的微信赞赏码

项目维护不易，感谢你的鼓励 ☕

📄 许可证

本项目使用 MIT License 开源。可以自由地使用、修改和分发本项目的代码与内容。