OuonnkiTV：开源多终端视频播放Web应用源码，基于React打造极致播放体验

源码介绍

想搭建一款适配TV端和移动端的视频播放Web应用？今天我的站长站就给大家分享这个超实用的开源项目——OuonnkiTV，它基于现代前端技术栈构建，核心聚焦视频播放体验优化和交互设计，还采用Apache License 2.0开源协议，不管是学习借鉴还是二次开发都很友好，多终端适配的特性也能满足不同场景的使用需求。

一、OuonnkiTV项目核心技术栈 兼顾性能与可维护性

OuonnkiTV的技术选型都是当下前端领域的主流方案，既保证了开发效率，又能兼顾代码质量和运行性能，核心技术栈特征如下：

前端框架：采用React 19.1.0 + TypeScript组合，TypeScript能保证代码的类型安全，大幅降低后期维护成本；

构建工具：使用Vite 6.3.5，相比传统构建工具，能提供极速的开发热更新和打包构建效率，开发体验拉满；

样式方案：基于TailwindCSS 4.1.8实现原子化CSS开发，不用写冗余的样式代码，样式开发效率更高；

状态管理：选用Zustand 5.0.5，轻量又高效，相比复杂的状态管理库，学习成本低、运行性能更好；

UI组件与图标：集成Radix UI系列组件（包含弹窗、选择器、提示框等），兼顾可访问性和视觉体验，搭配Phosphor/Lucide图标库，UI表现更丰富；

视频播放核心：整合artplayer（5.3.0）、hls.js（1.6.15），不仅能实现基础的视频播放控制，还支持HLS流媒体播放，满足高清视频播放需求；

部署适配：支持Vercel、Netlify、Docker等多平台部署，还内置了Vercel分析/测速插件，方便监控应用运行状态。

二、OuonnkiTV核心功能 覆盖多终端视频播放全需求

1. 多终端适配 交互体验一致

针对TV端和移动端做了专属适配，保证不同设备使用体验统一：

- 移动端通过viewport配置 + 手势拦截禁用缩放，避免误操作，和TV端交互逻辑保持一致；

- 基于react-device-detect做设备类型判断，自动适配不同终端的UI布局和交互逻辑，不用单独开发多套代码。

2. 专业级视频播放能力

核心的视频播放功能满足日常和专业场景需求：

- 依托hls.js支持HLS（m3u8）流媒体播放，适配各类高清视频源；

- 集成artplayer专业播放器，提供完整的播放控制能力，包括播放/暂停、进度调节、音量控制等基础操作，满足日常播放需求。

3. 交互与UI增强 提升使用体验

在交互和视觉层面做了大量优化，让应用使用更流畅：

- 基于dnd-kit实现拖拽排序功能，操作更灵活；

- 采用embla-carousel实现轮播组件，支持自动播放，适配首页推荐等场景；

- 借助framer-motion实现丰富的动画效果，提升交互过程中的视觉体验；

- 集成Radix UI组件库，实现无障碍、高性能的弹窗、下拉菜单、提示框等交互组件，兼顾不同用户的使用需求。

4. 完善的工程化与部署方案

工程化配置齐全，部署方式灵活多样：

- 支持Docker容器化部署，提供docker:build/up/down等脚本，一键构建和启停容器；

- 适配Vercel部署，通过vercel.JSON配置路由重写，完美适配React路由；

- 内置GitHub Actions自动同步上游代码，保证分支代码一致性；

- 集成ESLint、Prettier、TypeScript做代码质量管控，规范开发流程；

- 支持Vitest单元测试，方便验证代码功能，降低bug率。

5. 丰富的附加能力

除了核心功能，还有不少实用的附加能力：

- 集成TMDB接口（tmdb-ts），可对接影视数据，丰富视频内容来源；

- 基于react-hook-form + zod实现表单校验，适配登录、设置等表单场景；

- 支持主题切换（next-themes），满足不同视觉偏好；

- 集成Vercel Analytics/Speed Insights，监控应用性能和用户访问数据，方便优化迭代。

三、OuonnkiTV使用方法 从环境准备到部署全流程

前置条件

首先要满足基础的环境要求，同时完成代码克隆：

- 环境要求：Node.js ≥ 20.0.0、pnpm ≥ 10.15.1（项目指定的包管理器，建议严格匹配版本）；

- 克隆仓库：

git clone https://github.com/Ouonnki/OuonnkiTV.git

- 进入项目目录：

cd OuonnkiTV

核心命令

1. 安装依赖

pnpm install

2. 开发环境运行

pnpm dev

启动后默认监听本机所有IP，可通过 http://localhost:5173 访问（Vite默认端口）。

3. 构建生产包

pnpm build

构建时会先执行@ouonnki/cms-core包的构建，再编译TypeScript并通过Vite构建生产代码，最终输出到dist目录。

4. 预览生产包

pnpm preview

可在本地预览构建后的生产代码，验证打包效果。

5. Docker部署

# 构建Docker镜像
pnpm docker:build

# 启动容器（后台运行）
pnpm docker:up

# 停止容器
pnpm docker:down

# 查看容器日志
pnpm docker:logs

6. 代码质量检查

# ESLint检查
pnpm lint

# 单元测试
pnpm test

部署说明

Vercel部署
1. 将代码推送到GitHub仓库；
2. 在Vercel控制台导入该仓库，Vercel会自动读取vercel.json配置，使用pnpm安装依赖并构建；
3. 部署后自动处理路由重写（所有请求指向index.html），适配React路由。

其他部署方式
- 生产构建后（执行pnpm build），将dist目录部署到任意静态服务器（Nginx/Apache/Netlify等）即可；
- 若需自定义接口dai理，可参考vercel.json中的/proxy路由配置，对接后端接口。

注意事项

1. 项目依赖@ouonnki/cms-core本地包（workspace:*），需确保packages/cms-core目录存在且依赖安装完整；

2. 若修改代码后需同步上游仓库，可手动触发GitHub Actions的Sync Upstream (FORCe Mirror)工作流；

3. 移动端缩放禁用可能影响视力障碍用户的可访问性，若需调整可修改index.html中的viewport配置和gesturestart事件拦截逻辑；

4. 项目使用Apache License 2.0协议，二次开发/分发需遵循协议要求（保留版权声明、LICENSE文件等）。