ZSCGR/KVideo
1
0
Fork 0
mirror of https://github.com/KuekHaoYang/KVideo.git synced 2026-08-16 01:03:42 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
bfb0db341b549e7d8fdce15cc2bcaaaca53e745b
KVideo/README.md
T

602 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# KVideo
![KVideo Banner](public/icon.png)
> 一个基于 Next.js 16 构建的现代化视频聚合播放平台。采用独特的 "Liquid Glass" 设计语言，提供流畅的视觉体验和强大的视频搜索功能。
[![Next.js](https://img.shields.io/badge/Next.js-16.0-black?style=for-the-badge&logo=next.js)](https://nextjs.org/)
[![React](https://img.shields.io/badge/React-19.2-blue?style=for-the-badge&logo=react)](https://react.dev/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4.0-38B2AC?style=for-the-badge&logo=tailwind-css)](https://tailwindcss.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
## 📖 项目简介
**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 的文字对比度
## 🔒 隐藏模式
本项目包含一个隐藏的"成人模式"，仅通过特定操作激活：
1. 在首页点击"管理标签"
2. 在输入框中输入 **"色情"** 并添加
3. 点击新添加的 **"色情"** 标签
4. 系统将自动跳转至隐藏模式页面
> **注意**：隐藏模式下的内容源与主页完全隔离，互不干扰。
## 🛠 技术栈
### 前端核心
| 技术 | 版本 | 用途 |
|------|------|------|
| **[Next.js](https://nextjs.org/)** | 16.0.3 | React 框架，使用 App Router |
| **[React](https://react.dev/)** | 19.2.0 | UI 组件库 |
| **[TypeScript](https://www.typescriptlang.org/)** | 5.x | 类型安全的 JavaScript |
| **[Tailwind CSS](https://tailwindcss.com/)** | 4.x | 实用优先的 CSS 框架 |
| **[Zustand](https://github.com/pmndrs/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. 克隆仓库
```bash
git clone https://github.com/KuekHaoYang/KVideo.git
cd KVideo
```
#### 2. 安装依赖
```bash
npm install
```
如果你使用其他包管理器：
```bash
yarn install
pnpm install
```
#### 3. 启动开发服务器
```bash
npm run dev
```
开发服务器将在 `http://localhost:3000` 启动。
#### 4. 构建生产版本
```bash
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. 玻璃效果（数字元材质）
```css
/* 核心玻璃效果实现 */
.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. 流畅动画
```css
/* 标准过渡曲线 */
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 架构
#### 并行搜索引擎
```typescript
// lib/api/search-api.ts
// 同时在多个视频源中搜索，返回聚合结果
export async function parallelSearch(query: string): Promise<SearchResult[]>
```
#### 豆瓣集成
```typescript
// app/api/douban/route.ts
// 代理豆瓣 API，避免 CORS 问题
```
#### 视频代理
```typescript
// app/api/play/[...segments]/route.ts
// 代理视频请求，处理跨域和防盗链
```
### 缓存策略
#### Service Worker 缓存
- **HLS 清单文件**：缓存 m3u8 播放列表
- **视频片段**：智能缓存 .ts 视频片段
- **静态资源**：缓存图片、CSS、JS 文件
#### 历史视频预加载
- 后台自动下载历史视频
- 优先级队列管理
- 存储空间管理
### 性能优化
1. **服务端组件**：首屏快速加载
2. **代码分割**：按路由自动分割
3. **图片优化**：渐进式加载
4. **虚拟滚动**：大列表性能优化
5. **缓存策略**：多层缓存机制
## 🧑‍💻 开发指南
### 代码规范
#### 文件长度限制
> [!IMPORTANT]
> **所有项目文件必须保持在 150 行以内（除系统文件外）**
这是项目的硬性规则。在提交代码前，请运行以下命令检查：
```bash
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 前确保通过所有检查
### 测试
运行代码检查：
```bash
npm run lint
```
### 调试技巧
1. **React DevTools**：检查组件状态和 props
2. **Console 日志**：使用分组和样式化日志
3. **Network 面板**：监控 API 请求和缓存
4. **Performance 面板**：分析性能瓶颈
## 🚢 部署
### Vercel 部署（推荐）
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/KuekHaoYang/KVideo)
1. 连接 GitHub 仓库
2. Vercel 会自动检测 Next.js 项目
3. 点击 "Deploy" 即可
### 静态导出
```bash
# next.config.ts 中添加
export default {
output: 'export'
}
# 构建
npm run build
# 输出到 out/ 目录
```
### 🐳 Docker 部署
#### 1. 获取代码
```bash
git clone https://github.com/KuekHaoYang/KVideo.git
cd KVideo
```
#### 2. 构建镜像
```bash
docker build -t kvideo .
```
#### 3. 运行容器
```bash
docker-compose up -d
```
应用将在 `http://localhost:3000` 启动。
#### 3. 使用 Docker Hub 安装
如果你不想自己构建镜像，可以直接从 Docker Hub 拉取：
```bash
docker pull kuekhaoyang/kvideo:latest
docker run -d -p 3000:3000 --name kvideo kuekhaoyang/kvideo:latest
```
#### 4. 如何更新镜像
当有新版本发布时，可以通过以下命令更新：
```bash
docker stop kvideo
docker rm kvideo
docker pull kuekhaoyang/kvideo:latest
docker run -d -p 3000:3000 --name kvideo kuekhaoyang/kvideo:latest
```
## 🤝 贡献
我们非常欢迎各种形式的贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细的贡献指南。
### 快速贡献
1. **报告 Bug**：使用 GitHub Issues
2. **功能建议**：在 Issues 中提出
3. **代码贡献**：Fork → Branch → PR
4. **文档改进**：直接提交 PR
## 📄 许可证
本项目基于 [MIT 许可证](LICENSE) 开源。
## 🙏 致谢
感谢以下开源项目：
- [Next.js](https://nextjs.org/) - React 框架
- [Tailwind CSS](https://tailwindcss.com/) - CSS 框架
- [Zustand](https://github.com/pmndrs/zustand) - 状态管理
- [React](https://react.dev/) - UI 库
## 📞 联系方式
- **作者**：[KuekHaoYang](https://github.com/KuekHaoYang)
- **项目主页**：[https://github.com/KuekHaoYang/KVideo](https://github.com/KuekHaoYang/KVideo)
- **问题反馈**：[GitHub Issues](https://github.com/KuekHaoYang/KVideo/issues)
---
<div align="center">
Made with ❤️ by <a href="https://github.com/KuekHaoYang">KuekHaoYang</a>
<br>
如果这个项目对你有帮助，请考虑给一个 ⭐️
</div>
Reference in New Issue View Git Blame Copy Permalink