KVideo

基于 Liquid Glass 设计理念的现代化流媒体视频聚合平台

目录

• 关于项目
  • 核心特性
  • 技术栈
  • 设计理念
• 快速开始
  • 系统要求
  • 安装步骤
• 使用指南
  • 开发模式
  • 生产构建
• 核心功能
  • 智能并行搜索
  • 实时流式传输
  • 源可用性检测
  • 观看历史管理
  • 自适应视频播放器
• 项目架构
• 贡献指南
• 许可证
• 联系方式

关于项目

KVideo 是一个现代化的流媒体视频聚合平台，采用 Liquid Glass 设计系统打造极致的用户体验。平台通过智能并行搜索技术，实时聚合多个视频源的内容，为用户提供流畅、直观且视觉震撼的观影体验。

核心特性

• 🔍 智能并行搜索 - 同时查询 15+ 视频源，实时流式返回结果
• 🎬 自适应播放器 - 支持 HLS/M3U8 流，自动源切换，断点续播
• 🎨 Liquid Glass UI - 毛玻璃效果，流体动画，深浅色主题无缝切换
• ⚡ 实时可用性检测 - 搜索时自动过滤失效源，确保播放成功率
• 📊 类型智能筛选 - 自动识别分类（电影/剧集/综艺），支持多选过滤
• 📚 观看历史追踪 - 自动记录播放进度，快速恢复观看
• 🌐 无服务器架构 - 基于 Next.js App Router，API Routes 处理所有后端逻辑
• 📱 响应式设计 - 完美适配桌面、平板、移动设备

技术栈

前端框架

• Next.js 16.0 - React 元框架，提供服务端渲染和路由
• React 19.2 - 用户界面构建库
• TypeScript 5.x - 类型安全的 JavaScript 超集

样式系统

• Tailwind CSS 4.0 - 实用优先的 CSS 框架
• 自定义 Liquid Glass CSS 变量系统

状态管理 & 工具

• Zustand 5.0 - 轻量级状态管理
• Artplayer 5.1 - 现代化 HTML5 视频播放器
• HLS.js 1.5 - HLS 流协议支持

视频源整合

• 电影天堂、如意、暴风、天涯等 15+ 第三方视频 API
• 自定义源配置系统，支持动态添加

设计理念

KVideo 严格遵循 Liquid Glass 设计系统，灵感源自 Apple 的 visionOS 和 Jony Ive 的极简主义哲学：

1. 玻璃效果 - 毛玻璃材质（backdrop-filter: blur(25px) saturate(180%)）营造深度感
2. 通用柔软度 - 所有元素采用 rounded-2xl 或 rounded-full 圆角，无硬边
3. 流体动画 - 物理感知的缓动曲线（cubic-bezier(0.2, 0.8, 0.2, 1)）
4. 光学交互 - 悬停时内发光效果，仿佛组件在捕捉光线
5. 层次分明 - 清晰的 Z 轴深度，交互层始终位于视觉顶部

快速开始

系统要求

• Node.js 20.x 或更高版本
• npm 或 pnpm 包管理器
• 现代浏览器（Chrome 90+、Safari 14+、Firefox 88+）

安装步骤

1. 克隆仓库

   git clone https://github.com/KuekHaoYang/kvideo.git
   cd kvideo
   

2. 安装依赖

   npm install
   # 或使用 pnpm
   pnpm install
   

3. 启动开发服务器

   npm run dev
   

4. 访问应用

   打开浏览器访问 http://localhost:3000

使用指南

开发模式

开发模式支持热重载和快速调试：

npm run dev

应用将在 http://localhost:3000 启动，代码更改会自动刷新页面。

生产构建

构建优化后的生产版本：

# 构建应用
npm run build

# 启动生产服务器
npm start

代码检查

运行 ESLint 检查代码质量：

npm run lint

核心功能

智能并行搜索

KVideo 采用先进的并行搜索架构，同时查询多个视频源：

• 并发请求 - 15 个视频源同时搜索，无需等待
• 流式传输 - 结果实时流式返回，即查即得
• 缓存机制 - 搜索结果本地缓存，秒开历史查询
• 相关性排序 - 智能匹配算法，最相关内容优先展示

// 核心搜索 Hook - useParallelSearch
const { results, loading, performSearch } = useParallelSearch(
  saveToCache,
  onUrlUpdate
);

performSearch('电影名称'); // 触发并行搜索

实时流式传输

搜索过程采用服务端推送（SSE）技术：

1. 搜索阶段 - 显示已完成源数量 / 总源数量
2. 检测阶段 - 显示已验证视频数 / 总视频数
3. 结果推送 - 每验证通过一批视频立即推送

// API Route - /api/search-stream
// 返回格式：
// data: {"type": "progress", "stage": "searching", "checkedSources": 5}
// data: {"type": "videos", "videos": [...], "checkedVideos": 10}
// data: {"type": "complete", "totalResults": 120}

源可用性检测

搜索时自动验证视频源可用性，过滤无效链接：

• URL 格式验证 - 检查链接是否符合 M3U8/MP4 规范
• HEAD 请求预检 - 验证资源是否存在（状态码 200/206）
• 内容大小检测 - 确保内容大小 > 1KB，排除空文件
• 并发控制 - 同时检测 8 个链接，平衡速度与服务器压力

// 源检测核心函数
const availableVideos = await checkMultipleVideos(allVideos, 8);
// 仅返回可播放的视频

观看历史管理

基于 Zustand 的持久化历史记录：

• 自动记录 - 播放时自动保存到 localStorage
• 进度追踪 - 记录每集观看进度，支持断点续播
• 侧边栏展示 - 快速访问最近观看的视频
• 一键清除 - 支持批量或单个删除历史

// 历史存储 Store
const { addToHistory, clearHistory } = useHistoryStore();

addToHistory(videoId, title, playUrl, source, episodeName, currentTime);

自适应视频播放器

基于 Artplayer 构建的高级播放器：

• HLS 流支持 - 集成 hls.js，无缝播放 M3U8 格式
• 自动源切换 - 播放失败时自动尝试备用源
• 倍速播放 - 0.5x - 2x 速度调节
• 画质选择 - 自动识别多码率流
• 全屏控制 - 支持网页全屏和系统全屏
• 快捷键支持 - 空格暂停、方向键快进/快退

// 播放器核心 Hook - useVideoPlayer
const { videoData, playUrl, currentEpisode } = useVideoPlayer(
  videoId,
  source,
  episodeParam
);

项目架构

kvideo/
├── app/                        # Next.js App Router
│   ├── api/                    # API Routes
│   │   ├── search/             # 标准搜索 API
│   │   ├── search-stream/      # 流式搜索 API
│   │   ├── search-parallel/    # 并行搜索 API
│   │   ├── detail/             # 视频详情 API
│   │   └── hot/                # 热门推荐 API
│   ├── player/                 # 播放器页面
│   ├── history/                # 历史记录页面
│   ├── layout.tsx              # 根布局组件
│   ├── page.tsx                # 首页/搜索页
│   └── globals.css             # Liquid Glass 全局样式
│
├── components/                 # React 组件
│   ├── search/                 # 搜索相关组件
│   │   ├── SearchForm.tsx      # 搜索表单
│   │   ├── VideoGrid.tsx       # 视频网格布局
│   │   ├── TypeBadges.tsx      # 类型筛选徽章
│   │   └── ResultsHeader.tsx   # 搜索结果头部
│   ├── player/                 # 播放器组件
│   │   ├── VideoPlayer.tsx     # 主播放器
│   │   ├── EpisodeList.tsx     # 剧集列表
│   │   └── VideoMetadata.tsx   # 视频元数据
│   ├── history/                # 历史记录组件
│   │   └── WatchHistorySidebar.tsx
│   ├── home/                   # 首页组件
│   │   └── PopularFeatures.tsx
│   ├── ThemeProvider.tsx       # 主题提供器
│   └── ThemeSwitcher.tsx       # 主题切换器
│
├── lib/                        # 核心逻辑库
│   ├── api/                    # API 客户端
│   │   ├── client.ts           # HTTP 请求封装
│   │   └── video-sources.ts    # 视频源配置
│   ├── hooks/                  # 自定义 React Hooks
│   │   ├── useParallelSearch.ts    # 并行搜索 Hook
│   │   ├── useSearchStream.ts      # 流式搜索 Hook
│   │   ├── useVideoPlayer.ts       # 播放器 Hook
│   │   ├── useTypeBadges.ts        # 类型筛选 Hook
│   │   └── useSearchCache.ts       # 搜索缓存 Hook
│   ├── store/                  # Zustand 状态管理
│   │   ├── history-store.ts    # 历史记录 Store
│   │   ├── player-store.ts     # 播放器 Store
│   │   └── search-history-store.ts  # 搜索历史 Store
│   ├── types/                  # TypeScript 类型定义
│   │   └── index.ts
│   └── utils/                  # 工具函数
│       ├── source-checker.ts   # 源可用性检测
│       ├── url-validator.ts    # URL 验证
│       ├── m3u8-filter.ts      # M3U8 过滤
│       ├── episode-manager.ts  # 剧集管理
│       └── progress-tracker.ts # 进度追踪
│
├── public/                     # 静态资源
├── next.config.ts              # Next.js 配置
├── tailwind.config.ts          # Tailwind 配置
├── tsconfig.json               # TypeScript 配置
└── package.json                # 项目依赖

核心模块说明

API Routes（/app/api）

• search/ - 标准搜索，返回完整结果
• search-stream/ - SSE 流式搜索，实时推送
• search-parallel/ - 并行搜索，最快响应
• detail/ - 获取视频详细信息和播放链接

Hooks（/lib/hooks）

• useParallelSearch - 并行搜索管理，状态同步
• useVideoPlayer - 播放器状态、剧集切换
• useTypeBadges - 类型筛选逻辑
• useSearchCache - localStorage 缓存管理

Utils（/lib/utils）

• source-checker - 视频源健康检查
• url-validator - URL 格式验证
• m3u8-filter - M3U8 播放列表过滤
• episode-manager - 剧集解析与排序

贡献指南

我们热烈欢迎社区贡献！无论是修复 Bug、新增功能还是改进文档，您的参与都将使 KVideo 变得更好。

在开始贡献之前，请仔细阅读我们的 贡献指南（CONTRIBUTING.md），其中包含：

• 📋 完整的贡献流程
• 💻 代码规范和最佳实践
• 🎨 Liquid Glass UI 设计规范详解
• ✅ PR 提交检查清单
• 🧪 测试指南

快速开始

1. Fork 本仓库并克隆

   git clone https://github.com/YOUR_USERNAME/kvideo.git
   cd kvideo
   

2. 创建特性分支

   git checkout -b feature/your-feature-name
   

3. 安装依赖并开发

   npm install
   npm run dev
   

4. 提交更改（遵循 Conventional Commits）

   git commit -m "feat: 添加某个功能"
   

5. 推送并创建 Pull Request

   git push origin feature/your-feature-name
   

核心规范速览

代码规范：

• ✅ TypeScript 严格模式
• ✅ 单个文件不超过 150 行
• ✅ 遵循 Conventional Commits

Liquid Glass UI 设计规范：

• ✅ 容器类组件使用 rounded-2xl（1.5rem）
• ✅ 圆形/胶囊组件使用 rounded-full
• ✅ 毛玻璃效果：backdrop-filter: blur(25px) saturate(180%)
• ✅ 流体动画：cubic-bezier(0.2, 0.8, 0.2, 1)
• ✅ 使用 CSS 变量而非硬编码颜色

详细规范请查看 CONTRIBUTING.md。

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

这意味着您可以自由地：

• ✅ 商业使用
• ✅ 修改源代码
• ✅ 分发副本
• ✅ 私人使用

唯一的要求是在所有副本或重要部分中包含版权声明和许可证声明。

MIT License - Copyright (c) 2025 Kuek Hao Yang

联系方式

• 作者： Kuek Hao Yang
• GitHub： @KuekHaoYang
• 项目地址： https://github.com/KuekHaoYang/kvideo

获取帮助

• 🐛 报告 Bug： 提交 Issue
• 💡 功能建议： 发起讨论
• 🤝 贡献代码： 查看 贡献指南
• 📖 文档问题： 通过 Issues 反馈

---

使用 ❤️ 和 Liquid Glass 设计系统打造
让每一帧画面都如同触摸玻璃般流畅