抖剧TV 源码详解与完整部署教程

生成摘要

AI 生成，仅供参考

文章来源于精易【fengshao1231】打包完成直接可用的APP和exe文件在下载内容中…

软件界面：

一、项目概览

抖剧TV是一款基于Windows平台的桌面影视客户端，依托AppleCMS/MacCMS公开VOD影视接口获取全网片库资源，搭配专属网站账号体系，实现用户登录、影片收藏、个人资源管理等核心功能。

客户端整体采用Electron+React跨端方案搭建桌面交互界面，摒弃传统网页播放器短板，集成mpv.net原生播放器内核，支持高清解码、硬件加速、本地缓存、全屏播放等专业影视播放能力，观影体验远超普通网页播放器。

项目版本以根目录 package.json 文件中的version字段为唯一标准，当前稳定版本为 1.0.5。客户端搭载智能自动更新机制，仅对低于服务器最新版本的设备推送升级更新，保证版本统一、运行稳定。

二、核心技术栈

项目采用主流前端+桌面端技术组合，兼顾开发效率、运行性能和用户体验，各模块技术选型及用途如下：

技术范围	所用技术	核心用途
桌面运行内核	Electron 37	负责客户端窗口渲染、IPC进程通信、Cookie会话存储、文件下载、全自动更新安装等基础核心能力
React 19 + TypeScript	搭建客户端所有UI界面，实现全局状态管理、用户交互响应、页面路由切换等业务功能
Vite 7	高效编译src源码目录文件，输出dist静态构建产物，提升开发和打包效率
Lucide React	提供轻量化、简约统一的客户端功能图标，适配各类界面场景
hls.js	作为非Electron环境的播放兜底方案，适配HLS格式视频流预览播放
mpv.net + libmpv	支撑HLS视频流、影视直链播放，支持硬件解码、智能缓存、全屏播放、原生窗口适配等专业播放功能
uosc + Lua	定制原生播放器控制栏、剧集切换列表，优化鼠标、键盘交互逻辑，打造沉浸式播放体验
PHP + JSON + ZIP	实现客户端版本检测、更新包在线下载、SHA-256哈希校验、版本迭代管理等更新服务

三、项目完整目录结构

项目目录分工清晰、模块独立，便于二次开发、功能修改和部署维护，完整结构如下：

DOUJU/
├─ app.config.json                  全局统一配置文件（接口、域名、播放器、系统默认参数）
├─ assets/                          客户端图标等静态资源文件
├─ electron/                        Electron主进程核心目录
│  ├─ main.cjs                      主进程文件（接口代理、账号体系、播放器、更新核心逻辑）
│  └─ preload.cjs                   安全IPC通信桥接层，隔离前后端权限
├─ src/                             前端源码目录
│  ├─ App.tsx                       客户端主界面与全局业务状态管理
│  ├─ main.tsx                      React项目入口文件
│  ├─ styles.css                    全局界面样式文件
│  └─ vite-env.d.ts                 IPC通信类型声明文件
├─ vendor/mpvnet/                   原生播放器核心资源目录
│  ├─ mpv.conf                      播放器硬解、网络缓存核心配置
│  ├─ script-opts/uosc.conf         播放器控制栏自定义配置
│  ├─ scripts/uosc/                 uosc播放器核心脚本文件
│  ├─ douju-click.lua               播放器点击、双击、ESC快捷键交互逻辑
│  └─ DoujuMpvNetWindowStyle.exe    适配Win10/Win11的播放器圆角美化工具
├─ native/MpvNetWindowStyle.cs      播放器圆角辅助工具源码
├─ scripts/build-update-package.ps1 自动更新包生成、版本清单生成脚本
├─ update-server/                   服务端自动更新部署目录
│  ├─ update.php                    版本检测接口文件
│  ├─ releases.json                 最新版本更新清单配置
│  └─ releases/                     版本更新压缩包存储目录
├─ release/抖剧TV/                  可直接运行的Windows客户端发布目录
├─ dist/                            Vite自动构建产物（无需手动编辑）
├─ package.json                     项目版本、依赖库、打包配置核心文件
└─ 源码说明.md                      项目官方说明文档

四、全局统一配置说明

项目所有域名接口、功能参数、系统配置均统一收纳在根目录 app.config.json 文件中，Electron主进程、React前端会统一读取该配置，实现全局参数统一管理。项目打包时，工具会自动将该配置文件植入程序运行目录，无需手动调整。

核心配置参数说明：

配置字段	功能说明
app.siteOrigin	站点根域名，用于Cookie清理、更新接口域名校验，保障请求安全合规
app.userAgentName	客户端所有网络请求的统一UA标识，规避接口拦截问题
endpoints.vodApi	MacCMS影视资源接口，用于获取片库、分类、搜索等影视数据
endpoints.homepage	客户端首页轮播图资源抓取地址
endpoints.logo	客户端LOGO远程加载地址
endpoints.playerConfig	播放器线路名称配置接口，自定义播放线路展示名称
endpoints.login / register	用户登录、注册接口地址，支撑账号体系功能
endpoints.favoriteApi / favoriteDelete	影视收藏查询、添加收藏、取消收藏接口
endpoints.update	客户端版本检测、自动更新请求接口
network	统一配置接口请求超时时间、更新包大小上限等网络参数
player	配置播放器初始窗口比例、自适应缩放规则等播放参数
ui	设置轮播间隔、自动连播、默认音量、开机自检更新等UI交互参数
development.viteUrl	本地开发环境服务地址，用于本地调试运行

配置修改核心规则：二次开发、更换站点接口时，优先修改 app.config.json 即可，无需改动源码。其中 siteOrigin 域名必须与登录、收藏、更新服务域名保持一致，自动更新仅信任同域名HTTPS下载链接。同时，客户端真实版本号以 package.json 的version为准，版本迭代必须同步修改该字段。

五、核心业务接口详解

项目所有业务接口均由全局配置文件统一管理。账号登录、收藏管理等私密接口均通过Electron主进程发起请求，规避浏览器跨域限制，同时自动携带会话Cookie，保障账号状态持久化。

功能模块	请求方式	接口参数与规则
片库查询/分类/搜索	GET	调用vodApi接口，携带at=json参数，支持分类、分页、关键词搜索、批量查片等功能
首页轮播图加载	GET	读取homepage接口数据，解析网站幻灯片资源展示在客户端首页
播放器线路配置	GET	读取playerConfig接口，自定义播放线路展示名称，适配多线路播放场景
用户登录	POST	提交用户名、密码参数，完成账号登录并保存会话Cookie
用户注册	POST	提交用户名、两次密码校验参数，完成新用户注册
收藏列表查询	GET	固定参数查询用户全部收藏资源，单次最大加载500条收藏记录
添加影片收藏	GET	携带影片ID+13位时间戳参数，提交收藏请求
取消影片收藏	GET	必须传入收藏记录ID（ulog_id），不可直接使用影片ID操作
客户端版本检测	GET	上传当前客户端版本、系统平台、架构信息，校验是否需要更新

六、本地开发调试教程

1、环境依赖要求

- 操作系统：Windows 10 / Windows 11 全系版本

- 运行环境：Node.js 20及以上、npm 10及以上版本

- 服务环境：PHP 7.4+（用于搭建本地更新服务）、HTTPS域名环境

- 资源依赖：已部署完成的MacCMS影视接口、账号登录、收藏接口

2、项目初始化与运行

克隆源码至本地后，执行以下命令安装依赖、启动开发环境：

npm install
npm run dev

执行命令后，会自动启动Vite前端开发服务和Electron客户端。开发模式下，播放器会默认调用 vendor/mpvnet/ 目录内核文件，该目录资源不可缺失，否则播放器无法启动。

仅编译构建前端静态资源，可执行单独构建命令：

npm run build

构建产物自动输出至dist目录，该目录为自动生成文件，禁止手动修改内部压缩代码。

七、Windows客户端打包发布

1、完整打包命令

执行以下命令即可打包生成可直接分发的Windows客户端：

npm run package:win

打包工具会自动整合前端构建产物、Electron主进程、静态资源、配置文件、播放器内核等全部资源，生成完整客户端。项目为多文件运行模式，mpvnet内核目录、resources配置目录必须与exe程序同级存放，缺一不可。

项目自带成品运行目录，可直接使用：release/抖剧TV/抖剧TV.exe

2、增量更新资源同步

日常开发仅修改源码、无需全量打包时，可通过命令同步更新资源至发布目录，提升开发效率：

npm run build
Copy-Item -Path 'dist\*' -Destination 'release\抖剧TV\resources\app\dist' -Recurse -Force
Copy-Item -LiteralPath 'electron\main.cjs' -Destination 'release\抖剧TV\resources\app\electron\main.cjs' -Force
Copy-Item -LiteralPath 'app.config.json' -Destination 'release\抖剧TV\resources\app\app.config.json' -Force

若修改了播放器配置、Lua脚本、美化工具等资源，需手动同步 vendor/mpvnet/ 目录文件至发布目录对应文件夹，避免播放器功能异常。

注意事项：前端构建后会生成带哈希值的静态资源文件，同步资源时必须完整复制dist目录全部内容，仅替换单个文件会导致客户端启动黑屏、页面加载失败。

八、原生播放器核心说明

客户端核心播放能力依托mpv.net原生播放器实现，主进程通过命名管道与播放器建立IPC通信，精准控制播放逻辑。播放影片时，系统会自动清空原有播放列表，批量导入当前剧集资源，保证播放器列表仅展示对应影片剧集。

播放器窗口比例、自适应规则等基础参数，全部读取自 app.config.json 的player配置项。而硬件解码、网络缓存、缓冲时长等性能参数，统一配置在 vendor/mpvnet/mpv.conf 文件中，默认开启D3D11高性能渲染、安全硬解、30秒预缓存机制，大幅提升高清视频播放流畅度。

播放器控制栏、交互样式由uosc插件定制，核心配置和脚本文件位于对应目录，禁止随意删除字体、脚本、辅助程序文件，否则会导致控制栏失效、播放器闪退、圆角失效等问题。

九、服务端自动更新部署教程

1、服务端目录部署

将项目中 update-server 文件夹内所有文件，上传至网站根目录的 /update/ 文件夹下，最终服务端目录结构如下：

/update/
├─ update.php        版本检测核心接口
├─ releases.json     版本清单、更新参数配置文件
└─ releases/         更新压缩包存储目录
   └─ douju-tv-1.0.5.zip

服务端必须支持PHP脚本运行、HTTPS协议访问，客户端默认更新检测地址为：https://www.douju.tv/update/update.php，可在全局配置文件中自定义修改。

2、新版本发布完整流程

以迭代发布1.0.6版本为例，完整操作流程如下：

1. 修改根目录 package.json 中的version版本号，升级为1.0.6；

1. 完成源码功能修改、参数调整后，执行npm run build 编译前端资源；

1. 执行打包命令生成全新客户端发布包，或同步更新发布目录资源；

1. 运行系统脚本，自动生成对应版本更新压缩包：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-update-package.ps1 -Version 1.0.6 -Notes '填写本次版本更新说明'

1. 脚本自动在更新目录生成新版ZIP压缩包，并重写releases.json版本清单；

1. 手动校验压缩包SHA-256哈希值、文件大小，与清单配置保持一致；

1. 将更新接口文件、版本清单、新版压缩包上传至服务端/update目录；

1. 使用旧版本客户端检测更新，验证下载、校验、自动重启、覆盖安装功能正常。

如需重新生成当前1.0.5版本更新包，可直接执行对应脚本命令即可。

十、版本发布校验清单

每次版本迭代、打包发布前，务必完成以下校验，规避线上BUG：

npm run build
node --check electron\main.cjs

同时逐项核对：

- 发布目录配置文件完整存在，且与根目录配置完全一致；

- 前端index.html引用的所有哈希静态资源文件完整无缺失；

- mpvnet播放器内核目录所有程序、脚本、配置文件齐全；

- 更新包哈希值、文件大小与服务端版本清单完全匹配；

- 所有业务接口、更新服务均为HTTPS同域名请求，配置合规。

十一、常见问题排查方案

1、客户端启动黑屏

核心原因是前端静态资源缺失或不匹配。发布目录中 dist/index.html 引用的带哈希JS、CSS文件缺失会直接导致黑屏。解决方法：完整重新构建dist目录，全量同步静态资源，禁止单独替换单个文件。

2、播放器无法启动/无圆角效果

检查mpvnet目录是否与程序exe同级，确认播放器内核、dll组件、美化辅助程序、uosc脚本、配置文件无缺失。修改播放器窗口参数后，需彻底关闭后台播放器进程，重新启动客户端生效。

3、登录成功但收藏列表为空

排查客户端是否正常携带会话Cookie，确认收藏接口请求参数合规。收藏列表依赖 ulog_rid 字段匹配影片信息，取消收藏必须传入后台返回的收藏记录ID，不可使用影片ID操作。

4、自动更新无版本提示

核对服务端版本号高于客户端本地版本，确认更新包为同域名HTTPS链接、哈希值和文件大小配置无误，同时检查客户端设置中“自动检查更新”功能未手动关闭。