静态网站生成器实战:用VuePress与GitHub Pages构建班级同学录 📅 发布时间:2026/9/5 3:57:42 👁 浏览次数: 简介这是一份面向网页开发初学者与班级信息化建设需求者的同学录网页实战资源聚焦于静态班级网站的快速搭建与功能理解。资源以精简实用为特点共27个文件包含23张GIF导航与模块装饰图、1个JPG首页图、1个CSS样式表、1个HTML主页文件及1个Access数据库.db整体仅86KB轻量易部署。已有111人学习下载适合用于课程设计、毕业实践或班级数字化管理入门。解压后可直接浏览index.htm查看完整页面结构CSS文件定义全局样式GIF素材覆盖顶部横幅、侧栏图标、底部装饰等UI组件数据库则承载基础通讯录数据配合HTML实现静态展示逻辑虽未含动态脚本但目录结构清晰、模块命名规范是理解同学录网页典型布局与资源组织方式的优质参考样本。1. 项目缘起为什么我们需要一个“同学录”网页前几天整理旧物翻出了一本泛黄的纸质同学录。看着上面歪歪扭扭的留言和早已模糊的照片一个念头突然冒了出来在2024年的今天我们是否还需要一个“同学录”或者说我们需要一个什么样的“同学录”答案显然是肯定的。但形式早已不同。微信群聊固然方便但信息流太快珍贵的照片、留言、每个人的近况很容易被淹没。我们需要一个更“慢”一点、更“聚焦”一点的地方一个属于我们班级自己的数字空间。它不只是一个通讯录更是一个承载集体记忆、记录成长轨迹的线上家园。这就是我动手制作这个“同学录”班级网页项目的初衷。这个项目我把它命名为“tongxuelu.rar”既是对那个以.rar压缩包传递文件的互联网古早时代的调侃也寓意着这个网页就像一个打包好的、完整的记忆压缩包随时可以打开、回味。它的核心目标很简单为我的高中班级创建一个私密、美观、易于维护的线上同学录。任何有一点前端基础的朋友都可以基于这个思路为自己的班级复现一个。2. 技术选型与架构设计轻量、静态、可托管既然目标是让尽可能多的同学能轻松访问且我个人维护成本要低技术选型上我排除了需要服务器、数据库的动态网站方案。我选择了目前非常成熟的“静态网站生成器 免费静态托管”路线。2.1 为什么是静态网站动态网站如用PHPMySQL功能强大但你需要租用服务器、配置环境、担心数据库安全和性能。对于同学录这种内容更新频率极低可能一年更新一两次、访问量不大的项目来说杀鸡用牛刀了。静态网站则不同极致的速度与安全所有页面都是预先生成的HTML文件访问时无需服务器端计算速度快如闪电。没有数据库也就几乎没有被SQL注入等攻击的风险。零服务器成本可以直接托管在GitHub Pages、Vercel、Netlify等平台上完全免费。版本化管理所有网页源文件HTML、CSS、JS、图片都可以用Git管理每一次修改都有记录可以轻松回滚。离线也能看生成后的网站就是一堆文件可以下载到本地在没有网络的时候也能浏览。2.2 核心工具链VuePress 2 GitHub Pages我最终选择了VuePress 2作为静态网站生成器并用GitHub Pages进行托管。VuePress 2它是一个基于Vue.js的静态网站生成器特别适合技术文档但用来做同学录也绰绰有余。它的优势在于约定大于配置按照固定的目录结构放文件就能自动生成路由和页面省去大量手动配置。Markdown驱动每个同学的信息、班级日志都可以用Markdown书写简单直观非技术人员比如班长稍加学习也能参与内容维护。主题系统有丰富的主题可选也可以自定义能轻松做出美观的界面。Vue组件支持可以在Markdown里嵌入Vue组件这为我们实现一些交互功能比如留言板、照片墙轮播提供了可能。GitHub Pages这是GitHub提供的免费静态网站托管服务。你只需要将VuePress构建好的dist目录中的文件推送到一个特定的GitHub仓库或分支网站就自动上线了。域名可以是yourname.github.io/repo-name也可以绑定自己的自定义域名如class2024.com。2.3 数据存储设计用文件代替数据库这是本项目的关键设计。我们没有数据库那么每个同学的信息、班级相册、留言等数据存在哪里 我的方案是用结构化的Markdown和JSON/YAML文件来存储。同学档案 (/classmates/): 为每个同学创建一个Markdown文件例如zhangsan.md。文件内容分为两部分Front Matter (YAML格式)用于存储结构化数据。--- name: 张三 nickname: 三哥 avatar: /avatars/zhangsan.jpg enrollment: 2010-09 seat: 第三排第二列 now: 某互联网大厂高级工程师 location: 北京 contact: wechat: zhangsan2024 email: zhangsanexample.com tags: - 篮球高手 - 数学课代表 - 睡神 ---正文内容同学自己写的近况、想对大家说的话、回忆片段等用Markdown自由书写。班级相册 (/gallery/): 创建一个gallery.data.js的JSON文件来描述相册。// gallery.data.js export default [ { year: 2011, event: 春季运动会, photos: [ { src: /gallery/2011-sports-1.jpg, desc: 4x100米接力夺冠瞬间 }, { src: /gallery/2011-sports-2.jpg, desc: 全班大合影 } ] }, { year: 2012, event: 毕业旅行, photos: [ ... ] } ]留言墙 (/messages/): 同样用一个JSON数组来存储留言。但注意静态网站无法直接写入文件。这里的“留言”功能可以有两种实现静态预置在每次班级聚会后由管理员我收集大家的留言更新到JSON文件中重新构建网站。这是最安全简单的方式。第三方服务接入使用诸如Gitalk、Utterances等基于GitHub Issues的评论系统或者LeanCloud等BaaS服务实现动态留言。这需要一些额外的集成工作。整个项目的架构非常清晰用文本文件管理内容用VuePress生成静态页面用GitHub Pages提供全球访问。3. 核心功能实现细节与踩坑记录有了架构接下来就是一步步实现功能。这里分享几个核心模块的实现思路和过程中遇到的“坑”。3.1 自动化生成同学索引页我们有了几十个zhangsan.md、lisi.md如何自动生成一个按姓名或学号排序的“同学名录”页面 VuePress的自定义布局和客户端增强功能派上了用场。在.vuepress/components目录下创建一个ClassmateList.vue组件。在这个组件中利用Vite/Rollup的import.meta.globAPI动态导入/classmates/目录下所有的.md文件。// ClassmateList.vue 部分脚本 const classmates import.meta.glob(../../classmates/*.md, { eager: true });从每个文件的frontmatter中提取信息name,avatar,tags等渲染成一个卡片列表。在需要展示名录的页面Markdown中直接使用这个组件ClassmateList /。踩坑记录VuePress 2默认使用Vite但import.meta.glob在构建时SSG阶段和运行时行为有差异。必须确保{ eager: true }选项才能在构建阶段将文件内容内联否则部署后路径会出错。最初没注意这点导致线上页面卡片全部加载失败。3.2 实现一个“有灵魂”的照片墙简单的图片罗列太枯燥。我想做一个能按年份、事件筛选并且点击能放大查看的照片墙。数据驱动如前所述照片数据存放在gallery.data.js中。组件化构建创建PhotoGallery.vue组件。组件内部使用computed属性根据用户选择的年份selectedYear过滤出对应照片集。用CSS Grid或Flexbox实现响应式图片布局。集成一个轻量级的图片预览库如viewer.js或photo-swipe实现点击放大、滑动浏览。这里我选择了viewer.js因为它配置简单与Vue集成方便。性能优化几十张高清照片直接加载页面会非常慢。必须做图片懒加载和响应式图片。懒加载使用Intersection Observer API或者vue-lazyload库让图片进入视口时才加载。响应式图片在构建时使用sharp库或vite-plugin-image-optimizer等工具自动为每张原图生成480w,800w,1200w等不同宽度的版本并在img标签中使用srcset属性让浏览器根据设备屏幕选择合适尺寸的图片。这一步能极大提升移动端访问体验。3.3 私密性保障如何给网页加把“锁”同学录包含个人联系方式和生活近照完全公开不合适。但静态网站如何实现密码保护 完全意义上的后端鉴权无法实现但我们可以做前端模拟的密码访问。原理在网站入口如首页设置一个密码输入框。密码验证密码不通过网络传输验证。而是在前端对用户输入的密码进行哈希例如使用bcryptjs的纯前端实现与一个预先硬编码在代码中的哈希值进行比较。状态保持如果密码正确则利用localStorage或sessionStorage在浏览器中存储一个通过验证的标记如isAuthenticated: true。路由守卫在Vue RouterVuePress基于它的全局前置守卫中检查localStorage中的标记。如果标记不存在或无效则拦截所有导航跳转回密码输入页。重要警告这不是真正的安全因为哈希值和所有前端代码都对用户可见一个稍微懂技术的用户就能破解。这只能防住普通浏览者和网络爬虫绝对不适合存储真正敏感的信息。因此我在同学录中不存放电话号码、家庭住址这类高敏感信息只放微信可设置添加权限和邮箱。真正的隐私信息还是建议在微信小群里沟通。这个“锁”更像是一个礼貌的“门帘”告诉访客这是一个私人空间非请勿入。4. 部署、维护与内容更新流程项目开发完成如何让它上线并持续运行4.1 自动化部署到GitHub Pages手动构建再上传太麻烦。我利用GitHub Actions实现了CI/CD持续集成/持续部署。在项目根目录创建.github/workflows/deploy.yml文件。编写Action脚本主要步骤包括监听main分支的push事件。拉取代码安装Node.js环境。运行npm install和npm run buildVuePress的构建命令。将构建产物dist目录推送到名为gh-pages的分支。在GitHub仓库设置中将GitHub Pages的源设置为gh-pages分支。 从此以后我只需要将更新的代码push到main分支几分钟后网站就会自动更新。4.2 内容更新让非技术同学也能参与这是项目能否持续的关键。不能每次更新都让我来改代码。我的解决方案是规范化模板为classmates目录下的README.md文件写一个详细的Markdown模板说明Frontmatter每个字段怎么填正文写什么。协作流程我管理员在GitHub上为每个同学创建一个分支例如feat/update-lisi。将模板和该同学旧的文件内容放进去然后发起一个Pull Request (PR)。将PR链接发到班级群对应同学。同学可以在GitHub网页端直接点击“编辑文件”在线修改Markdown内容。修改后提交会自动更新到PR中。我和其他同学可以在PR下评论、Review。确认无误后我合并PR到main分支触发Actions自动部署。 这个过程虽然比在线编辑器复杂但引入了版本控制和审核机制避免了内容被随意覆盖也让大家接触了一点极客协作文化反响意外地不错。4.3 域名绑定与HTTPS免费的github.io域名不够个性化。我申请了一个简短的域名如class2010.top。在域名注册商处添加几条CNAME记录指向yourname.github.io。在项目仓库根目录添加一个名为CNAME的文件里面只写一行你的自定义域名如class2010.top。GitHub Pages会自动处理SSL证书为你的网站启用免费的HTTPS。这一点非常重要确保了数据传输的安全。5. 项目复盘与未来可扩展方向这个“tongxuelu.rar”项目从构思到上线大约用了我两个周末的零散时间。技术栈本身并不复杂更多的是对产品逻辑和用户体验的思考。5.1 值得肯定的设计静态架构零运维成本、访问速度快、安全性高完美匹配项目需求。文件驱动内容用Markdown和JSON管理内容直观且易于版本化巧妙避开了数据库。自动化流水线GitHub Actions自动化部署解放双手。渐进式增强核心功能浏览信息、照片完全静态交互功能留言可通过第三方服务接入架构灵活。5.2 遇到的挑战与妥协动态功能局限这是静态网站的原罪。像实时留言、在线签到这类功能必须引入外部服务增加了复杂性和依赖。密码保护的心理安慰如前所述前端密码保护更多是象征性的。这要求我们在内容设计上必须把握分寸不存放真正确切的隐私。同学参与门槛尽管极力简化让所有同学通过GitHub PR来更新内容仍然有一定门槛。目前只能依靠几个热心班干部作为“中间人”来收集和提交信息。5.3 未来可以尝试的扩展时间线功能除了按同学索引可以增加一个全局的“班级时间线”将每次聚会、重要事件的照片和描述以时间流的形式展示出来更具故事性。“那年今日”小插件在网站侧边栏或首页增加一个小模块随机展示往年今天同月同日班级发生的事或拍的照片增加访问的趣味性和期待感。集成轻量级后端Serverless如果确实需要更安全的身份验证和真正的动态数据可以考虑接入Supabase或Firebase这类BaaS服务。它们提供数据库、认证和函数但按量付费在访问量极低的情况下成本近乎为零。这可以作为项目功能增强的备选方案。生成纪念册PDF利用puppeteer等无头浏览器技术写一个脚本可以自动将网站内容排版生成一份精美的PDF电子纪念册供大家下载珍藏。这个项目做下来最大的感触是技术是为情感服务的。我们用了看似“极客”的静态网站、Git工作流但最终目的是为了守护一段共同的情谊创造一个不被日常聊天淹没的记忆锚点。当看到同学们在更新自己的页面认真写下近况贴上家庭合影时我觉得所有的代码都值了。如果你也想为你的班级、社团、项目组打造这样一个空间不妨就从 fork 这个“tongxuelu.rar”开始吧。本文还有配套的精品资源点击获取