· 学海斋  · 11 min read

XPlayHub 项目结构与使用手册

XPlayHub 项目结构与使用手册

项目结构概览

XPlayHub 是一个基于 Astro 和 Tailwind CSS 构建的现代化网站项目，采用了清晰的目录结构和模块化设计。以下是项目的主要结构：

xplayhub/
├── src/
│   ├── components/        # 组件目录
│   ├── content/           # 内容配置
│   ├── data/              # 数据文件
│   ├── layouts/           # 页面布局
│   ├── pages/             # 页面文件
│   ├── utils/             # 工具函数
│   ├── config.ts          # 配置文件
│   ├── navigation.ts      # 导航配置
│   └── types.d.ts         # 类型定义
├── public/                # 静态资源
├── astro.config.mjs       # Astro 配置
├── package.json           # 项目依赖
└── tailwind.config.mjs    # Tailwind 配置

详细目录说明

1. src/components/

用途：存放可复用的 UI 组件。

主要组件：

  • blog/ - 博客相关组件（列表、分页、标签等）
  • common/ - 通用组件（按钮、卡片等）
  • layout/ - 布局相关组件

示例：

  • BlogList.astro - 博客文章列表组件
  • Pagination.astro - 分页组件
  • Tags.astro - 标签组件

2. src/content/

用途：内容配置目录，定义内容集合。

主要文件：

  • config.ts - 内容集合配置，定义了文章的结构和验证规则

示例：

const postCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    category: z.string().optional(),
    image: z.string().optional(),
    tags: z.array(z.string()).optional(),
  }),
  loader: glob({ pattern: ['**/*.md', '**/*.mdx'], base: 'src/data/post' }),
});

3. src/data/

用途：存放实际的内容数据文件。

主要目录：

  • post/ - 博客文章目录，按分类组织
    • game/ - 游艺馆分类
      • pcgame/ - 电脑游戏
      • androidgame/ - 安卓游戏
      • modifier/ - 修改器
      • mods/ - 游戏模组
    • soft/ - 机巧堂分类
      • system-software/ - 系统软件
      • office-study/ - 办公学习
      • android-software/ - 安卓软件
      • entertainment/ - 休闲娱乐
    • videos/ - 映画舫分类
      • movies/ - 电影
      • series/ - 剧集
    • music/ - 听音阁分类
      • chinese-music/ - 华语音乐
        • pop/ - 流行精选
        • classic/ - 经典老歌
        • cantonese/ - 粤语金曲
        • folk/ - 民谣小调
        • rap/ - 说唱嘻哈
        • rock/ - 摇滚现场
        • female/ - 女声精选
        • male/ - 男声精选
        • artist-collection/ - 歌手合集
      • foreign-music/ - 海外音乐
        • western-pop/ - 欧美流行
        • japan-korea/ - 日韩音乐
        • english-classic/ - 英文经典
        • movie-songs/ - 影视神曲
        • western-edm/ - 欧美电音
        • foreign-folk/ - 海外民谣
        • band-collection/ - 乐队精选
        • artist-collection/ - 歌手合集
      • pure-music/ - 纯音乐
        • light-music/ - 轻音乐
        • piano/ - 钢琴曲
        • classical/ - 古典乐
        • sleep/ - 助眠音乐
        • study/ - 学习专注
        • meditation/ - 冥想放松
        • background/ - 背景音乐
        • audiophile/ - 发烧试听
      • soundtrack/ - 原声配乐
        • movie/ - 影视原声
        • anime/ - 动漫原声
        • game/ - 游戏原声
        • documentary/ - 纪录片配乐
        • classic-ost/ - 经典OST
        • theme-collection/ - 主题曲合集
      • collection/ - 音乐合集
        • artist-collection/ - 歌手合集
        • album-complete/ - 专辑全集
        • year-hits/ - 年度热歌合集
        • car-music/ - 车载音乐打包
        • ktv-hits/ - KTV热门歌曲包
        • retro-hits/ - 怀旧金曲合集
        • douyin-hits/ - 抖音热歌合集
        • shop-background/ - 店铺背景音乐合集
      • charts/ - 榜单专区
        • year-hot/ - 年度热歌榜
        • monthly-hot/ - 月度热门榜
        • platform-hot/ - 平台热播榜
        • new-releases/ - 新歌速递
        • retro-hits/ - 怀旧金曲榜
        • car-hot/ - 车载热听榜
      • tools/ - 音乐工具
    • tech/ - 智算苑分类
    • resources/ - 百宝楼分类
    • blog/ - 学海斋分类

4. src/layouts/

用途：页面布局模板。

主要文件：

  • PageLayout.astro - 主页面布局
  • BlogLayout.astro - 博客页面布局

5. src/pages/

用途：网站页面文件。

主要文件：

  • index.astro - 网站首页
  • [...blog]/ - 博客相关页面
    • [category]/ - 分类页面
    • [tag]/ - 标签页面
    • [...slug].astro - 文章详情页
  • services.astro - 服务页面
  • about.astro - 关于页面
  • contact.astro - 联系页面

6. src/utils/

用途：工具函数目录。

主要文件：

  • blog.ts - 博客相关工具函数
  • permalinks.ts - 链接生成工具
  • seo.ts - SEO 相关工具

7. 配置文件

  • src/config.ts - 网站配置
  • src/navigation.ts - 导航栏配置
  • src/types.d.ts - TypeScript 类型定义
  • astro.config.mjs - Astro 框架配置
  • tailwind.config.mjs - Tailwind CSS 配置
  • package.json - 项目依赖和脚本

导航配置

导航栏配置位于 src/navigation.ts 文件中，定义了网站的导航结构：

export const headerData = {
  links: [
    {
      text: '主页',
      links: [
        { text: 'SaaS', href: getPermalink('/homes/saas') },
        { text: 'Startup', href: getPermalink('/homes/startup') },
        // 其他子链接...
      ],
    },
    {
      text: 'Landing',
      links: [
        { text: 'Lead Generation', href: getPermalink('/landing/lead-generation') },
        // 其他子链接...
      ],
    },
    // 其他导航项...
  ],
  actions: [{ text: 'Download', href: 'https://github.com/arthelokyo/astrowind', target: '_blank' }],
};

分类系统

XPlayHub 采用了层级分类系统，主要分类包括：

  1. 游艺馆 (game)

    • 电脑游戏 (pcgame)
    • 安卓游戏 (androidgame)
    • 修改器 (modifier)
    • 游戏模组 (mods)

  2. 机巧堂 (soft)

    • 系统软件 (system-software)
    • 办公学习 (office-study)
    • 安卓软件 (android-software)
    • 休闲娱乐 (entertainment)

  3. 映画舫 (videos)

    • 电影 (movies)
    • 剧集 (series)

  4. 听音阁 (music)

    • 华语音乐 (chinese-music)
      • 流行精选 (chinese-pop)
      • 经典老歌 (chinese-classic)
      • 粤语金曲 (cantonese-music)
      • 民谣小调 (chinese-folk)
      • 说唱嘻哈 (chinese-rap)
      • 摇滚现场 (chinese-rock)
      • 女声精选 (chinese-female)
      • 男声精选 (chinese-male)
      • 歌手合集 (chinese-artist-collection)
    • 海外音乐 (foreign-music)
      • 欧美流行 (western-pop)
      • 日韩音乐 (japan-korea)
      • 英文经典 (english-classic)
      • 影视神曲 (movie-songs)
      • 欧美电音 (western-edm)
      • 海外民谣 (foreign-folk)
      • 乐队精选 (band-collection)
      • 歌手合集 (foreign-artist-collection)
    • 纯音乐 (pure-music)
      • 轻音乐 (light-music)
      • 钢琴曲 (piano)
      • 古典乐 (classical)
      • 助眠音乐 (sleep)
      • 学习专注 (study)
      • 冥想放松 (meditation)
      • 背景音乐 (background)
      • 发烧试听 (audiophile)
    • 原声配乐 (soundtrack)
      • 影视原声 (movie-soundtrack)
      • 动漫原声 (anime-soundtrack)
      • 游戏原声 (game-soundtrack)
      • 纪录片配乐 (documentary-soundtrack)
      • 经典OST (classic-ost)
      • 主题曲合集 (theme-collection)
    • 音乐合集 (music-collection)
      • 歌手合集 (collection-artist-collection)
      • 专辑全集 (album-complete)
      • 年度热歌合集 (year-hits)
      • 车载音乐打包 (car-music)
      • KTV热门歌曲包 (ktv-hits)
      • 怀旧金曲合集 (retro-hits)
      • 抖音热歌合集 (douyin-hits)
      • 店铺背景音乐合集 (shop-background)
    • 榜单专区 (music-charts)
      • 年度热歌榜 (year-hot)
      • 月度热门榜 (monthly-hot)
      • 平台热播榜 (platform-hot)
      • 新歌速递 (new-releases)
      • 怀旧金曲榜 (charts-retro-hits)
      • 车载热听榜 (car-hot)
    • 音乐工具 (entertainment)

  5. 智算苑 (tech)

  6. 百宝楼 (resources)

  7. 学海斋 (blog)

文章创建与管理

创建新文章

  1. 选择分类：根据文章内容选择合适的分类目录
  2. 创建文件：在对应分类目录中创建 .md 或 .mdx 文件
  3. 添加 Frontmatter：在文件开头添加文章元数据

Frontmatter 示例：

---
title: 游戏标题
description: 游戏描述
pubDate: 2026-04-09
category: pcgame  # 分类名称
image: ~/assets/images/game-image.jpg
tags: [游戏, 攻略]
---

分类页面

  • 点击导航栏中的分类名称会显示该分类下的所有文章
  • 部分分类有子分类，点击子分类会显示对应子分类的文章
  • 分类页面支持分页功能

开发与部署

开发环境

  1. 安装依赖：

    npm install

  2. 启动开发服务器：

    npm run dev

  3. 访问网站： 打开浏览器访问 http://localhost:4321

构建部署

  1. 构建项目：

    npm run build

  2. 预览构建结果：

    npm run preview

  3. 部署： 将 dist 目录部署到您的服务器或静态网站托管服务

自定义配置

导航栏配置

修改 src/navigation.ts 文件可以自定义导航栏结构，包括添加新的导航项、修改现有导航项或调整导航顺序。

网站配置

修改 src/config.ts 文件可以自定义网站的基本配置，如网站标题、描述、作者信息等。

分类配置

修改 src/utils/blog.ts 文件可以自定义分类的处理逻辑，包括添加新分类、修改分类名称等。

常见问题与解决方案

文章不显示在分类页面

原因：文章的 category 字段设置不正确 解决方案：确保文章的 category 字段与分类的 slug 一致

分类页面显示 404 错误

原因：分类没有在 blog.ts 中注册 解决方案：在 blog.ts 文件中添加分类信息和处理逻辑

导航栏链接不工作

原因：链接路径不正确 解决方案：使用 getPermalink 函数生成正确的链接路径

总结

XPlayHub 是一个结构清晰、功能完善的现代化网站项目，采用了 Astro 和 Tailwind CSS 技术栈，提供了丰富的分类系统和导航结构。通过本手册，您应该已经了解了项目的基本结构和使用方法，可以开始创建和管理您的内容了。

如果您有任何问题或需要进一步的帮助，请参考项目的文档或咨询开发团队。

Share:
Back to Blog

Related Posts

View All Posts »