9bca019b50
- Enable `ssr: true` in `nuxt.config.ts` for server-side rendering of meta tags. - Implement `useSeoMeta` in `events/.vue` with fallback logic for Open Graph and Twitter cards. - Update `content.config.ts` to use `asSeoCollection` for the news collection. - Migrate event markdown frontmatter to use standardized SEO fields.
永平中学校友会官网（YPHS Alumni）
一个基于 Nuxt 4 与 Nuxt Content 打造的内容型网站，面向永平中学校友与社会公众，提供新闻公告、活动预告、名人堂与校友组织介绍等信息。项目内置基础的后台界面脚手架，支持后续扩展会员管理与内容发布流程。
- 线上地址：https://yphsalumni.org
- 技术栈：Nuxt 4（Vue 3 + Nitro）、TypeScript、Tailwind CSS 4、@nuxt/ui、@nuxt/content、@nuxt/image、SEO/Sitemap/Robots 模块
项目亮点
- 内容优先：使用 Markdown + 前置属性（Frontmatter）管理新闻、活动、名人堂。
- 现代 UI：采用 @nuxt/ui + Tailwind CSS 4，内置响应式导航与主题样式。
- SEO 友好：内置 @nuxtjs/seo、@nuxtjs/sitemap、@nuxtjs/robots 与合理的默认
<head>元信息。 - 可扩展的后台：提供基础的「仪表盘 / 内容列表 / 模态编辑器」结构，便于后续对接真实后端。
- 零后端即可上线：作为纯内容站点可静态导出部署，也可运行 SSR 部署。
目录结构
关键目录说明：
app/pages/路由页面（首页、新闻、活动、名人堂、关于、入会申请、后台等）layouts/页面布局（default、admin-dashboard）components/组件（首页模块、后台弹窗、输入组件等）assets/css/样式（Tailwind 入口与 Markdown 样式）composables/可复用逻辑（日期格式化、国家数据等）data/静态数据（如国家拨号表）
content/Markdown 内容（news/、events/、hall-of-fames/）content.config.ts内容集合与字段 Schema 定义public/公开静态资源（Logo、封面图、音频、图片等）nuxt.config.tsNuxt 主配置（模块、SEO、站点信息等）docs/产品与信息架构文档
功能概览
- 首页：英雄区 + 最新新闻 + 活动卡片 + 名人堂预览 + 捐赠占位模块
- 新闻：列表与详情（Markdown 渲染，支持封面、标签、SEO 字段）
- 活动：列表与详情（日期/地点/封面，支持嵌入媒体）
- 名人堂：人物详情 + 图集 + 外链视频/媒体嵌入
- 关于页面：会徽含义、校歌音频等
- 入会申请：UI 表单（当前为占位，未连通后端）
- 后台（占位）：仪表盘、会员籍管理（示例数据）、新闻/活动/名人堂入口与新建弹窗（
md-editor-v3）
环境要求
- Node.js ≥ 18.20 或 20.x（推荐 20 LTS）
- 包管理器：pnpm（推荐）/ npm / yarn / bun
启用 pnpm（建议）：
corepack enable
corepack prepare pnpm@latest --activate
本地开发
安装依赖：
pnpm install
启动开发服务器（默认 http://localhost:3000）：
pnpm dev
构建与预览
SSR 构建与本地预览：
pnpm build
pnpm preview
静态导出（适合静态站部署，如 Netlify/Cloudflare Pages/Nginx 静态目录）：
pnpm generate
# 产物在 .output/public （仓库中有 dist -> .output/public 的软链）
部署指引
- 静态托管：执行
pnpm generate后，将.output/public（或dist软链）上传到任意静态空间（如 Cloudflare Pages、Netlify、GitHub Pages、Nginx 静态目录）。 - Node SSR：执行
pnpm build后，以 Node 方式运行.output/server/index.mjs，或使用平台的 Nuxt 运行时适配（Vercel/Netlify Functions/自托管 Node）。 - SEO：请在
nuxt.config.ts的site.url与app.head中更新为你自己的域名与元信息。
内容写作与数据结构
项目使用 @nuxt/content 管理内容，字段规则见 content.config.ts。在对应目录新增 Markdown 文件即可出现在站点中。
示例：新闻（content/news/20251001-official-web-launch.md）
---
title: "永中校友会官网正式上线"
date: "2025-10-01"
updated: "2025-10-01"
author: "作者名"
description: "用于列表摘要与 SEO 的简短说明"
cover: "/news/20251001-official-web-launch/Screenshot.png"
tags: ["活动", "公告"]
category: "通知"
highlight: true
seoTitle: "SEO 标题"
seoDescription: "SEO 描述"
ogImage: "/images/og/news-launch.jpg"
---
正文使用 Markdown 书写，支持图片、表格、引用与 HTML 块。
示例：活动（content/events/20250927-return-to-school.md）
---
title: "活动标题"
subtitle: "活动副标题"
date: "2025-09-27"
location: "地点名称"
cover: "/events/20250927-return-to-school/event-photo-1.jpg"
---
活动详情正文...
示例：名人堂（content/hall-of-fames/he-si-rong.md）
---
name: "人物姓名"
photo: "/hall-of-fame/he-si-rong/人物头像.png"
title: "人物头衔"
description: "简短介绍"
gallery:
[
"/hall-of-fame/he-si-rong/图1.webp",
"/hall-of-fame/he-si-rong/图2.webp"
]
---
正文可包含媒体嵌入。
定制与配置
- 站点信息与 SEO：
nuxt.config.tsapp.head.titleTemplate与默认title- Meta、OG、Twitter 卡片默认值
site.url（用于站点地图与 SEO）
- 导航与页脚：
app/layouts/default.vue - 样式与主题色：
app/assets/css/main.css（Tailwind v4 与自定义 CSS 变量） - Markdown 渲染样式：
app/assets/css/markdown.css - 首页区块：
app/components/index/*.vue - TikTok 嵌入组件：
app/components/TikTokEmbed.vue - 后台布局与侧边导航：
app/layouts/admin-dashboard.vue、app/composables/useDashboardSidebarLinks.ts - 分析脚本：
public/analytics.js（默认使用 Umami，若不需要可在nuxt.config.ts中移除<script src="/analytics.js">注入）
后台与数据（现状）
- 后台页面为 UI 脚手架，方便未来接入真实后端（当前示例页使用占位数据或仅展示结构）。
- 成员管理页使用示例 API（
jsonplaceholder）占位，待替换为校友会实际后端服务。 - 入会申请页面为 UI 表单与校验演示，暂未接入存储与流程（页面顶部已加“功能未开放”提示遮罩）。
若需接入真实后端，建议：
- 认证与权限：OAuth/JWT + 角色权限
- 数据库存储：PostgreSQL / MySQL；缓存：Redis
- 内容发布：保留 Markdown/Content 模式，或引入 Headless CMS（如 Strapi/Directus）
开发者指南
- 代码风格：TypeScript + Nuxt 约定式目录；组件与页面尽量保持职责单一
- 内容 schema：若新增内容类型，请在
content.config.ts中定义并校验字段 - 资源放置：公共图片/音频/图标放在
public/，内容相关配图走public/{模块}/... - 性能与无障碍：优先图片懒加载、合理的语义化标签与可访问性属性
路线图（Roadmap）
- 入会申请流程与后台审核对接
- 后台：内容 CRUD（新闻/活动/名人堂）与草稿/发布流
- 捐赠模块与支付对接
- 多语言与国际化（i18n）
- 校友企业/招聘板块
- 活动报名、签到与相册
贡献指南
欢迎 Issue 与 PR：
- Fork 本仓库并新建分支
- 本地开发与验证（
pnpm dev） - 提交 PR 并说明修改动机与影响范围
内容贡献：
- 新增/修改 Markdown 请遵循
content.config.ts中的 schema 字段 - 提交前请自查封面路径与日期格式是否规范
安全与隐私
- 如发现安全问题，请通过电子邮件私下报告给维护者，并避免公开披露（可在此处填写邮箱或表单链接）。
- 分析脚本（Umami）可选启用，默认文件位于
public/analytics.js，请替换为你自己的域名与website-id，或移除注入脚本。
许可证
本项目计划以开源方式发布。建议选择并添加合适的开源许可证（如 MIT、Apache-2.0）。
- 若你决定使用 MIT：请在仓库根目录新增
LICENSE文件并写明 MIT 许可条款。 - 在未选择明确许可证前，请勿对外分发未授权的二进制或闭源衍生物。
致谢
- 设计与技术支持：Tootaio Studio
- 内容与资料：永平中学校友会
- 技术框架与生态：Nuxt 团队与社区、@nuxt/ui、Tailwind CSS
—— 连接校友 · 传承精神 ——