KVideo

一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言，提供流畅的视觉体验和强大的视频搜索功能。

📖 项目简介

KVideo 是一个高性能、现代化的视频聚合与播放应用，专注于提供极致的用户体验和视觉设计。本项目利用 Next.js 16 的最新特性，结合 React 19 和 Tailwind CSS v4，打造了一个既美观又强大的视频浏览平台。

核心设计理念：Liquid Glass（液态玻璃）

项目的视觉设计基于 "Liquid Glass" 设计系统，这是一套融合了以下特性的现代化 UI 设计语言：

• 玻璃拟态效果：通过 backdrop-filter 实现的磨砂半透明效果，让 UI 元素如同真实的玻璃材质
• 通用柔和度：统一使用 rounded-2xl 和 rounded-full 两种圆角半径，创造和谐的视觉体验
• 光影交互：悬停和聚焦状态下的内发光效果，模拟光线被"捕获"的物理现象
• 流畅动画：基于物理的 cubic-bezier 曲线，实现自然的加速和减速过渡
• 深度层级：清晰的 z-axis 层次结构，增强空间感和交互反馈

✨ 核心功能

🎥 智能视频播放

• HLS 流媒体支持：原生支持 HLS (.m3u8) 格式，提供流畅的视频播放体验
• 智能缓存机制：Service Worker 驱动的智能缓存系统，自动预加载和缓存视频片段
• 后台下载：利用观看历史，在后台自动下载历史视频，确保离线也能观看
• 播放控制：完整的播放控制功能，包括进度条、音量控制、播放速度调节、全屏模式等
• 移动端优化：专门为移动设备优化的播放器界面和手势控制

🔍 多源并行搜索

• 聚合搜索引擎：同时在多个视频源中并行搜索（lib/api/search-api.ts），大幅提升搜索速度
• 自定义视频源：支持添加、编辑和管理自定义视频源（lib/store/settings-store.ts）
• 智能解析：统一的解析器系统（lib/api/parsers.ts），自动处理不同源的数据格式
• 搜索历史：自动保存搜索历史，支持快速重新搜索（lib/store/search-history-store.ts）
• 结果排序：支持按评分、时间、相关性等多种方式排序搜索结果

🎬 豆瓣集成

• 详细影视信息：自动获取豆瓣评分、演员阵容、剧情简介等详细信息
• 推荐系统：基于豆瓣数据的相关推荐
• 专业评价：展示豆瓣用户评价和专业影评

💾 观看历史管理

• 自动记录：自动记录观看进度和历史（lib/store/history-store.ts）
• 断点续播：从上次观看位置继续播放
• 历史管理：支持删除单条历史或清空全部历史
• 隐私保护：所有数据存储在本地，不上传到服务器

📱 响应式设计

• 全端适配：完美支持桌面、平板和移动设备
• 移动优先：专门的移动端组件和交互设计
• 触摸优化：针对触摸屏优化的手势和交互

🌙 主题系统

• 深色/浅色模式：支持系统级主题切换
• 动态主题：基于 CSS Variables 的动态主题系统
• 无缝过渡：主题切换时的平滑过渡动画

⌨️ 无障碍设计

• 键盘导航：完整的键盘快捷键支持
• ARIA 标签：符合 WCAG 2.2 标准的无障碍实现
• 语义化 HTML：使用语义化标签提升可访问性
• 高对比度：确保 4.5:1 的文字对比度

🛠 技术栈

前端核心

技术	版本	用途
Next.js	16.0.3	React 框架，使用 App Router
React	19.2.0	UI 组件库
TypeScript	5.x	类型安全的 JavaScript
Tailwind CSS	4.x	实用优先的 CSS 框架
Zustand	5.0.2	轻量级状态管理

开发工具

• ESLint 9：代码质量检查
• PostCSS 8：CSS 处理器
• Vercel Analytics：性能监控和分析

架构特点

• App Router：Next.js 13+ 的新路由系统，支持服务端组件和流式渲染
• API Routes：内置 API 端点，处理豆瓣数据和视频源代理
• Service Worker：离线缓存和智能预加载
• Server Components：优化首屏加载性能
• Client Components：复杂交互和状态管理

🚀 快速开始

环境要求

在开始之前，请确保你的开发环境满足以下要求：

工具	最低版本	推荐版本
Node.js	20.0.0	20.x LTS
npm	9.0.0	10.x
Git	2.30.0	最新版本

安装步骤

1. 克隆仓库

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

2. 安装依赖

npm install

如果你使用其他包管理器：

# 使用 yarn
yarn install

# 使用 pnpm
pnpm install

3. 启动开发服务器

npm run dev

开发服务器将在 http://localhost:3000 启动。

4. 构建生产版本

# 构建
npm run build

# 启动生产服务器
npm start

📂 项目结构

KVideo/
├── app/                          # Next.js App Router
│   ├── api/                      # API 路由
│   │   ├── douban/               # 豆瓣 API 代理
│   │   │   └── route.ts          # 豆瓣数据获取端点
│   │   ├── play/                 # 视频播放代理
│   │   │   └── [...segments]/    # HLS 片段代理
│   │   └── proxy/                # 通用代理端点
│   ├── player/                   # 播放器页面
│   │   └── page.tsx              # 视频播放页面
│   ├── settings/                 # 设置页面
│   │   └── page.tsx              # 应用设置界面
│   ├── styles/                   # 全局样式
│   │   ├── accordion.css         # 手风琴组件样式
│   │   ├── badge.css             # 徽章组件样式
│   │   ├── button.css            # 按钮组件样式
│   │   ├── glass.css             # Liquid Glass 核心样式
│   │   ├── input.css             # 输入框组件样式
│   │   ├── modal.css             # 模态框组件样式
│   │   └── tabs.css              # 标签页组件样式
│   ├── globals.css               # 全局 CSS 入口
│   ├── layout.tsx                # 根布局组件
│   ├── page.tsx                  # 首页（搜索页面）
│   └── scroll-optimization.css   # 滚动优化样式
│
├── components/                   # React 组件
│   ├── history/                  # 观看历史相关组件
│   │   ├── ClearHistoryButton.tsx
│   │   ├── HistoryDownloadManager.tsx
│   │   ├── HistoryItem.tsx
│   │   ├── HistoryModal.tsx
│   │   ├── HistoryScrollArea.tsx
│   │   ├── HistorySectionHeader.tsx
│   │   └── WatchHistorySidebar.tsx
│   ├── home/                     # 首页相关组件
│   │   ├── HomeEpisodeList.tsx
│   │   ├── HomeHeader.tsx
│   │   ├── HomeLayout.tsx
│   │   ├── HomeSearchResults.tsx
│   │   ├── HomeVideoActions.tsx
│   │   ├── HomeVideoCard.tsx
│   │   └── HomeVideoGrid.tsx
│   ├── layout/                   # 布局组件
│   │   └── SidebarLayout.tsx
│   ├── player/                   # 播放器组件（53 个子组件）
│   │   ├── DesktopPlayer.tsx     # 桌面播放器
│   │   ├── MobilePlayer.tsx      # 移动端播放器
│   │   ├── PlaybackControls.tsx  # 播放控制
│   │   ├── ProgressBar.tsx       # 进度条
│   │   ├── VolumeControl.tsx     # 音量控制
│   │   └── ...                   # 其他播放器组件
│   ├── search/                   # 搜索相关组件
│   │   ├── SearchBar.tsx         # 搜索栏
│   │   ├── SearchFilters.tsx     # 搜索过滤器
│   │   ├── SearchHistory.tsx     # 搜索历史
│   │   ├── SearchResults.tsx     # 搜索结果
│   │   └── ...                   # 其他搜索组件
│   ├── settings/                 # 设置相关组件
│   │   ├── SettingsLayout.tsx    # 设置页面布局
│   │   ├── SourceManagement.tsx  # 视频源管理
│   │   ├── ThemeSettings.tsx     # 主题设置
│   │   └── ...                   # 其他设置组件
│   ├── ui/                       # 通用 UI 组件
│   │   ├── Accordion.tsx         # 手风琴组件
│   │   ├── Badge.tsx             # 徽章组件
│   │   ├── Button.tsx            # 按钮组件
│   │   ├── Input.tsx             # 输入框组件
│   │   ├── Modal.tsx             # 模态框组件
│   │   ├── ModalHeader.tsx       # 模态框头部
│   │   ├── ScrollArea.tsx        # 滚动区域
│   │   ├── Tabs.tsx              # 标签页组件
│   │   └── ...                   # 其他基础组件
│   ├── SearchLoadingAnimation.tsx
│   ├── ServiceWorkerRegister.tsx # Service Worker 注册
│   ├── ThemeProvider.tsx         # 主题提供者
│   └── ThemeSwitcher.tsx         # 主题切换器
│
├── lib/                          # 核心逻辑和工具函数
│   ├── accessibility/            # 无障碍功能
│   │   └── keyboard-shortcuts.ts # 键盘快捷键
│   ├── api/                      # API 客户端
│   │   ├── client.ts             # HTTP 客户端
│   │   ├── default-sources.ts    # 默认视频源配置
│   │   ├── detail-api.ts         # 视频详情 API
│   │   ├── http-utils.ts         # HTTP 工具函数
│   │   ├── parsers.ts            # 数据解析器
│   │   ├── search-api.ts         # 搜索 API（并行搜索）
│   │   └── video-sources.ts      # 视频源类型定义
│   ├── hooks/                    # React Hooks
│   │   ├── mobile/               # 移动端专用 hooks
│   │   │   ├── useMobileGestures.ts
│   │   │   ├── useMobilePlaybackControls.ts
│   │   │   └── useMobileTouchControls.ts
│   │   ├── useHistoryDownloader.ts    # 历史视频下载
│   │   ├── useHomePage.ts             # 首页逻辑
│   │   ├── useInfiniteScroll.ts       # 无限滚动
│   │   ├── useKeyboardNavigation.ts   # 键盘导航
│   │   ├── useMobilePlayer.ts         # 移动端播放器
│   │   ├── useParallelSearch.ts       # 并行搜索
│   │   ├── useSearchAction.ts         # 搜索操作
│   │   ├── useSearchCache.ts          # 搜索缓存
│   │   ├── useSearchHistory.ts        # 搜索历史
│   │   ├── useSearchState.ts          # 搜索状态
│   │   ├── useSourceBadges.ts         # 来源徽章
│   │   ├── useTypeBadges.ts           # 类型徽章
│   │   └── useVideoPlayer.ts          # 视频播放器
│   ├── store/                    # Zustand 状态管理
│   │   ├── history-store.ts      # 观看历史状态
│   │   ├── search-history-store.ts    # 搜索历史状态
│   │   ├── settings-helpers.ts   # 设置辅助函数
│   │   └── settings-store.ts     # 应用设置状态
│   ├── types/                    # TypeScript 类型定义
│   │   └── video.ts              # 视频相关类型
│   └── utils/                    # 工具函数
│       ├── cache-utils.ts        # 缓存工具
│       ├── date-utils.ts         # 日期工具
│       ├── dom-utils.ts          # DOM 工具
│       ├── image-utils.ts        # 图片工具
│       ├── player-utils.ts       # 播放器工具
│       ├── scroll-utils.ts       # 滚动工具
│       ├── storage-utils.ts      # 存储工具
│       ├── theme-utils.ts        # 主题工具
│       ├── url-utils.ts          # URL 工具
│       └── video-utils.ts        # 视频工具
│
├── public/                       # 静态资源
│   ├── icon.png                  # 应用图标
│   └── service-worker.js         # Service Worker（缓存和离线支持）
│
├── .github/                      # GitHub 配置
│   └── workflows/                # GitHub Actions
├── .gitignore                    # Git 忽略文件
├── CODE_OF_CONDUCT.md            # 行为准则
├── CONTRIBUTING.md               # 贡献指南
├── LICENSE                       # MIT 许可证
├── README.md                     # 项目说明（本文件）
├── SECURITY.md                   # 安全政策
├── eslint.config.mjs             # ESLint 配置
├── next-env.d.ts                 # Next.js 类型定义
├── next.config.ts                # Next.js 配置
├── package.json                  # 项目依赖
├── postcss.config.mjs            # PostCSS 配置
└── tsconfig.json                 # TypeScript 配置

🎨 Liquid Glass 设计系统

设计原则

Liquid Glass 设计系统是本项目的视觉核心，遵循以下原则：

1. 玻璃效果（数字元材质）

/* 核心玻璃效果实现 */
.glass {
  backdrop-filter: blur(20px) saturate(180%) brightness(110%);
  background: rgba(255, 255, 255, 0.1);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

2. 统一圆角

• 容器类组件：使用 rounded-2xl（较大的圆角）
  • 按钮、输入框、卡片、模态框等
• 小型元素：使用 rounded-full（完全圆形/药丸形）
  • 头像、徽章、滑块拇指等

3. 光影交互

• 悬停状态：内发光效果
• 焦点状态：增强的边框高亮
• 动态阴影：根据交互状态调整

4. 流畅动画

/* 标准过渡曲线 */
transition: all 0.3s cubic-bezier(0.4, 0.0, 0.2, 1);

组件库

项目包含完整的 Liquid Glass 组件库：

• Accordion：手风琴折叠面板
• Badge：状态徽章和标签
• Button：多种样式的按钮
• Input：输入框和文本区域
• Modal：模态对话框
• Tabs：标签页切换
• ScrollArea：自定义滚动区域
• 更多组件位于 components/ui/

🏗 架构设计

状态管理

使用 Zustand 进行状态管理，主要的 store 包括：

1. Settings Store（lib/store/settings-store.ts）

   • 主题设置
   • 视频源管理
   • 搜索排序偏好
   • 播放器设置

2. History Store（lib/store/history-store.ts）

   • 观看历史记录
   • 播放进度
   • 历史管理操作

3. Search History Store（lib/store/search-history-store.ts）

   • 搜索历史
   • 快速搜索建议

API 架构

并行搜索引擎

// lib/api/search-api.ts
// 同时在多个视频源中搜索，返回聚合结果
export async function parallelSearch(query: string): Promise<SearchResult[]>

豆瓣集成

// app/api/douban/route.ts
// 代理豆瓣 API，避免 CORS 问题

视频代理

// app/api/play/[...segments]/route.ts
// 代理视频请求，处理跨域和防盗链

缓存策略

Service Worker 缓存

• HLS 清单文件：缓存 m3u8 播放列表
• 视频片段：智能缓存 .ts 视频片段
• 静态资源：缓存图片、CSS、JS 文件

历史视频预加载

• 后台自动下载历史视频
• 优先级队列管理
• 存储空间管理

性能优化

1. 服务端组件：首屏快速加载
2. 代码分割：按路由自动分割
3. 图片优化：渐进式加载
4. 虚拟滚动：大列表性能优化
5. 缓存策略：多层缓存机制

🧑‍💻 开发指南

代码规范

文件长度限制

Important

所有项目文件必须保持在 150 行以内（除系统文件外）

这是项目的硬性规则。在提交代码前，请运行以下命令检查：

find . -type f -not -path "*/node_modules/*" -not -path "*/.next/*" -not -path "*/.git/*" -not -name "package-lock.json" -not -name "*.png" -not -name "*.md" | xargs wc -l | awk '$1 > 150 && $2 != "total" {print $2 " - " $1 "行"}'

如果有文件超过 150 行，请重构代码：

1. 提取组件：将大组件拆分为多个小组件
2. 提取 Hook：将复杂逻辑提取到自定义 Hook
3. 提取工具函数：将通用函数移至 lib/utils/
4. 模块化：按功能拆分文件

TypeScript 规范

• 避免使用 any，使用具体类型或 unknown
• 为所有函数添加返回类型
• 使用接口（interface）定义对象类型
• 合理使用泛型提高代码复用性

组件规范

• 使用函数组件和 Hooks
• 遵循单一职责原则
• Props 类型必须明确定义
• 复用 components/ui/ 下的基础组件

样式规范

• 优先使用 Tailwind 类名
• 复杂样式使用 CSS Modules 或专用 CSS 文件
• 遵循 Liquid Glass 设计系统
• 确保响应式设计

Git 工作流

1. 从 main 分支创建功能分支
2. 使用语义化的分支名（feat/、fix/、docs/ 等）
3. 编写清晰的提交信息
4. 提交 PR 前确保通过所有检查

测试

运行代码检查：

npm run lint

调试技巧

1. React DevTools：检查组件状态和 props
2. Console 日志：使用分组和样式化日志
3. Network 面板：监控 API 请求和缓存
4. Performance 面板：分析性能瓶颈

🚢 部署

Vercel 部署（推荐）

1. 连接 GitHub 仓库
2. Vercel 会自动检测 Next.js 项目
3. 点击 "Deploy" 即可

静态导出

# next.config.ts 中添加
export default {
  output: 'export'
}

# 构建
npm run build
# 输出到 out/ 目录

🤝 贡献

我们非常欢迎各种形式的贡献！请查看 CONTRIBUTING.md 了解详细的贡献指南。

快速贡献

1. 报告 Bug：使用 GitHub Issues
2. 功能建议：在 Issues 中提出
3. 代码贡献：Fork → Branch → PR
4. 文档改进：直接提交 PR

📄 许可证

本项目基于 MIT 许可证 开源。

🙏 致谢

感谢以下开源项目：

• Next.js - React 框架
• Tailwind CSS - CSS 框架
• Zustand - 状态管理
• React - UI 库

📞 联系方式

• 作者：KuekHaoYang
• 项目主页：https://github.com/KuekHaoYang/KVideo
• 问题反馈：GitHub Issues

---

Made with ❤️ by KuekHaoYang
如果这个项目对你有帮助，请考虑给一个 ⭐️