抖剧TV Windows 桌面影视客户Duan开源

fengshao1231

# 抖剧TV 源码与部署说明


## 项目概览


抖剧TV 是一个 Windows 桌面影视客户端，使用 AppleCMS/MacCMS 的公开 VOD API 获取片库数据，并通过网站账户体系完成登录和收藏。主界面由 Electron + React 构建，播放使用独立的 mpv.net/libmpv 原生播放器。


当前应用版本以根目录 `package.json` 的 `version` 字段为准，当前为 `1.0.5`。自动更新只会向低于服务器清单版本的客户端推送更新。


## 技术栈


| 范围 | 技术 | 用途 |
| --- | --- | --- |
| 桌面运行时 | Electron 37 | 窗口、IPC、Cookie 会话、下载和自动更新安装 |
| 前端 | React 19 + TypeScript | 主界面、状态管理和交互 |
| 构建 | Vite 7 | 将 `src/` 编译到 `dist/` |
| 图标 | Lucide React | 界面图标 |
| Web 兼容播放器 | hls.js | 非 Electron 环境的 HLS 预览兜底 |
| 原生播放器 | mpv.net + libmpv | HLS/直链播放、硬解、缓存、全屏和原生窗口 |
| 播放器界面 | uosc + Lua | 原生播放器控制栏、剧集列表和鼠标交互 |
| 更新服务 | PHP + JSON + ZIP | 版本检查、更新包下载与 SHA-256 校验 |


## 目录结构


```text
DOUJU/
├─ app.config.json                  统一配置：接口、域名、超时、播放器和默认设置
├─ assets/                          应用图标
├─ electron/
│  ├─ main.cjs                      Electron 主进程：接口代理、账户、播放器、更新
│  └─ preload.cjs                   受控 IPC 桥接层
├─ src/
│  ├─ App.tsx                       React 主界面与业务状态
│  ├─ main.tsx                      React 入口
│  ├─ styles.css                    全部界面样式
│  └─ vite-env.d.ts                 IPC 类型声明
├─ vendor/mpvnet/                   mpv.net、libmpv、uosc 和播放器配置
│  ├─ mpv.conf                      硬解和网络缓存配置
│  ├─ script-opts/uosc.conf         uosc 控制栏配置
│  ├─ scripts/uosc/                 uosc 脚本
│  ├─ douju-click.lua               单击、双击、Esc 等交互
│  └─ DoujuMpvNetWindowStyle.exe    Win10/Win11 播放器圆角辅助程序
├─ native/MpvNetWindowStyle.cs      圆角辅助程序源码
├─ scripts/build-update-package.ps1 自动更新 ZIP 与清单生成脚本
├─ update-server/                   部署到网站的自动更新服务
│  ├─ update.php                    更新检查接口
│  ├─ releases.json                 最新更新清单
│  └─ releases/                     更新 ZIP 存放目录
├─ release/抖剧TV/                  可直接运行的 Windows 发布目录
├─ dist/                            Vite 构建产物，不手工编辑
├─ package.json                     版本、依赖与 Electron Builder 配置
└─ 源码说明.md                      本文档
```


## 统一配置


所有需要按站点调整的地址和默认参数集中在根目录 [app.config.json](./app.config.json)。Electron 主进程和 React 前端都从该文件读取配置；正式打包时 Electron Builder 会自动将其放入 `resources/app/`。


| 配置位置 | 内容 |
| --- | --- |
| `app.siteOrigin` | 站点根地址，同时用于 Cookie 清理和更新 URL 域名校验 |
| `app.userAgentName` | 所有站点请求使用的 User-Agent 名称 |
| `endpoints.vodApi` | MacCMS VOD API，例如 `.../api.php/provide/vod/` |
| `endpoints.homepage` | 首页轮播图抓取地址 |
| `endpoints.logo` | 客户端 Logo 地址 |
| `endpoints.playerConfig` | 网站播放器名称配置地址 |
| `endpoints.login` / `register` | 登录、注册路径 |
| `endpoints.favoriteApi` / `favoriteDelete` | 收藏查询、收藏、取消收藏接口 |
| `endpoints.update` | 自动更新检查接口 |
| `network` | API、站点、更新请求超时与更新包大小上限 |
| `player` | mpv.net 初始窗口比例与自动适配比例 |
| `ui` | 轮播间隔、自动下一集、默认音量和自动检查更新默认值 |
| `development.viteUrl` | 本地开发服务地址 |


修改站点时，优先只改 `app.config.json`。其中 `siteOrigin` 必须与登录、收藏、更新包所在域名保持一致；自动更新只接受与该域名相同的 HTTPS 下载地址。


`package.json` 的 `version` 是客户端实际版本号，不能只改 `app.config.json`。每次发布新版本都要提高 `package.json` 的版本号，例如从 `1.0.5` 改为 `1.0.6`。


## 业务接口


以下地址均由 `app.config.json` 管理，除公开 VOD API 外，账户和收藏请求由 Electron 主进程发出，因此不会受浏览器跨域限制，并会携带 Electron 会话 Cookie。


| 功能 | 方法 | 地址/参数 |
| --- | --- | --- |
| 片库、分类、搜索 | GET | `vodApi`，附加 `at=json`；常用参数：`ac`、`pg`、`t`、`wd`、`ids` |
| 首页轮播 | GET | `homepage`，读取网站幻灯片 9 内容 |
| 播放器名称 | GET | `playerConfig`，读取线路显示名称 |
| 登录 | POST | `login`，字段：`user_name`、`user_pwd` |
| 注册 | POST | `register`，字段：`user_name`、`user_pwd`、`user_pwd2` |
| 收藏列表 | GET | `favoriteApi?ac=list&mid=1&id=0&type=2&page=1&limit=500` |
| 添加收藏 | GET | `favoriteApi?ac=set&mid=1&id=<vodId>&type=2&_=<13位时间戳>` |
| 取消收藏 | GET | `favoriteDelete?ids=<ulogId>&type=2&all=0` |
| 更新检查 | GET | `update?action=check&version=<版本>&platform=win32&arch=x64` |


收藏列表的 `ulog_rid` 是影片 ID；取消收藏必须传入收藏记录 ID `ulog_id`，不能传影片 ID。


## 本地开发


### 环境要求


- Windows 10 或 Windows 11
- Node.js 20 或更高版本
- npm 10 或更高版本
- 用于更新服务的 PHP 7.4+ 与 HTTPS 网站环境
- 已准备可用的 MacCMS API、登录和收藏接口


### 初始化与运行


```powershell
npm install
npm run dev
```


`npm run dev` 会启动 Vite 开发服务，再启动 Electron。开发时播放器仍从 `vendor/mpvnet/` 启动，因此该目录必须保留完整的 mpv.net 运行文件。


只构建前端：


```powershell
npm run build
```


构建结果写入 `dist/`。该目录每次都会重新生成，不能直接修改其中的压缩 JS 文件。


## 发布桌面客户端


完整打包命令：


```powershell
npm run package:win
```


Electron Builder 会将 `dist/`、`electron/`、`assets/`、`app.config.json`、`package.json` 和 `vendor/mpvnet/` 打入 Windows 发布包。程序不是单文件应用，`mpvnet/` 与 `resources/` 必须和 `抖剧TV.exe` 位于同一发布目录。


项目中已有的可运行目录为：


```text
release/抖剧TV/抖剧TV.exe
```


### 手动同步现有发布目录


开发期间如果只修改源文件而不重新执行完整打包，需要同步对应文件到 `release/抖剧TV/`：


```powershell
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
```


如果修改了 `vendor/mpvnet/` 中的 `mpv.conf`、uosc 配置、Lua 脚本或圆角辅助程序，也要同步同名文件到：


```text
release/抖剧TV/mpvnet/
```


构建后的 `index.html` 会引用带哈希的 JS/CSS 文件。同步前端时必须同时复制 `dist/index.html` 和 `dist/assets/`，否则可能出现应用启动黑屏。


## 播放器说明


主进程启动 `mpvnet.exe` 并使用命名管道发送 mpv IPC 命令。播放当前影片时，先以 `replace` 清空旧播放列表，再追加当前播放源的全部剧集，因此 uosc 剧集列表只显示当前影片。


关键运行参数从 `app.config.json` 的 `player` 读取：


```text
--geometry=<player.geometry>
--autofit=<player.autofit>
--autofit-larger=<player.autofitLarger>
```


播放器性能参数位于 `vendor/mpvnet/mpv.conf`：D3D11 `gpu-next` 渲染、安全硬解、30 秒缓存和解复用缓冲。uosc 控制栏配置位于 `vendor/mpvnet/script-opts/uosc.conf`；不要删除 `scripts/uosc/`、字体文件或 `ziggy-windows.exe`。


## 自动更新服务部署


### 服务器目录


将整个 `update-server/` 上传到网站根目录的 `/update/`，最终结构如下：


```text
/update/
├─ update.php
├─ releases.json
└─ releases/
   └─ douju-tv-1.0.5.zip
```


客户端访问的检查地址必须与 `app.config.json` 中的 `endpoints.update` 一致，例如：


```text
https://www.douju.tv/update/update.php
```


服务器需支持 PHP 执行和 HTTPS 文件下载。`update.php` 读取 `releases.json`，仅在服务器版本大于客户端请求版本时返回更新 URL、文件大小、SHA-256、说明和发布时间。


### 发布新版本流程


以发布 `1.0.6` 为例：


1. 修改 `package.json` 中的版本号为 `1.0.6`。
2. 修改代码或 `app.config.json` 后，执行 `npm run build`。
3. 使用 `npm run package:win` 生成新的发布目录，或完整同步 `release/抖剧TV/`。
4. 在根目录生成更新包：


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


5. 脚本会生成 `update-server/releases/douju-tv-1.0.6.zip` 并重写 `update-server/releases.json`。
6. 校验 ZIP 的 SHA-256 与 JSON 中的 `sha256` 完全一致。
7. 上传 `update.php`、`releases.json` 与对应 ZIP 到服务器 `/update/`。
8. 用低于 `1.0.6` 的客户端打开设置页检查更新，确认可以下载、校验、重启和覆盖安装。


当前更新包可用以下命令重新生成：


```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-update-package.ps1 -Version 1.0.5 -Notes '更新说明'
```


同版本 ZIP 只能用于重新分发或修复服务器文件；已经是 `1.0.5` 的客户端不会提示更新。要让 `1.0.5` 客户端获取后续修复，必须发布 `1.0.6` 或更高版本。


## 验证清单


每次发布前执行：


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


并确认：


- `release/抖剧TV/resources/app/app.config.json` 存在且与根目录配置一致。
- `release/抖剧TV/resources/app/dist/index.html` 引用的 JS/CSS 文件都实际存在。
- `release/抖剧TV/mpvnet/` 包含 `mpvnet.exe`、`libmpv-2.dll`、`mpv.conf`、`douju-click.lua`、`scripts/uosc/` 和 `script-opts/uosc.conf`。
- 自动更新 ZIP 的文件大小和 SHA-256 与 `releases.json` 一致。
- 更新服务器、账户接口与 API 均使用 HTTPS，且域名与 `siteOrigin` 一致。


## 常见问题


### 应用启动黑屏


检查发布目录中 `resources/app/dist/index.html` 引用的带哈希 JS/CSS 文件是否存在。不要只复制一个旧 JS 文件；应同步整个 `dist/` 内容。


### 播放器无法启动或没有圆角


确认 `mpvnet/` 目录和 EXE 同级，且没有丢失 `mpvnet.exe`、`libmpv-2.dll`、`DoujuMpvNetWindowStyle.exe`、uosc 脚本及字体。修改 `player` 窗口比例后需完全关闭旧播放器进程再重新播放。


### 登录成功但收藏为空


确认请求携带网站 Cookie；收藏列表需要 `favoriteApi` 返回的 `ulog_rid` 再通过 VOD API 补全影片信息。取消收藏传 `ulog_id`，不是影片 ID。


### 自动更新不提示


确认服务器 `releases.json` 的版本高于客户端 `package.json` 版本，更新包 URL 是同域 HTTPS，文件大小和 SHA-256 正确，且客户端设置中“自动检查更新”未关闭。

游客，如果您要查看本帖隐藏内容请回复