📌 项目地址：LibreSpark/LibreTV | ⭐ 13,612 颗星 | 🔧 JavaScript | 📜 Apache-2.0
先搞清楚这是什么东西
LibreTV 是一个免费在线视频搜索与观看平台，后端代理多个视频源的 API，把搜索结果和播放流整合到一个前端页面里。你不用注册账号，部署到自己能控制的服务器或免费托管商（Vercel、Netlify、Cloudflare Pages、Render）就能用。项目基于 bestK/tv 重构，目前 13612 个 Star。
入口网站：libretv.is-an.org，你可以先上去看一眼功能，再决定要不要自己搭。
部署方式对比：哪个最省事
README 给了四种部署方式，我把关键区别和踩过的坑列出来。
一键部署（Vercel / Netlify / Render）—— 推荐新手
点一下按钮，连上你的 GitHub 仓库，几秒就能跑起来。三个平台都支持一键部署：
- Vercel：
https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FLibreSpark%2FLibreTV - Netlify：
https://app.netlify.com/start/deploy?repository=https://github.com/LibreSpark/LibreTV - Render：
https://render.com/deploy?repo=https://github.com/LibreSpark/LibreTV
最关键的步骤：部署完成后，一定要在环境变量里加上 PASSWORD。如果在部署面板里没找到环境变量设置入口，等部署完成后再去项目的 Settings → Environment Variables 里添加。不加的话，页面打开只会让你设置密码，什么都看不了。
Cloudflare Pages —— 免费额度很足，但步骤略多
- Fork 仓库到你的 GitHub。
- 登录 Cloudflare Dashboard → Pages → 创建项目 → 连接你的 fork 仓库。
- 构建命令和输出目录都留空（默认根目录），直接部署。
- 必须在 Settings → Environment Variables 里添加
PASSWORD。 - 部署完就能访问。
注意：Cloudflare Pages 默认会给你一个 xxx.pages.dev 的域名，也可以绑自己的域名。免费版每天 500 次构建请求，如果你 fork 后经常自动同步触发构建，可能会耗尽额度。
Docker / Docker Compose —— 适合自己有 VPS 的人
一条命令启动：
docker run -d
--name libretv
--restart unless-stopped
-p 8899:8080
-e PASSWORD=your_password
bestzwei/libretv:latest内部端口是 8080，映射到宿主机 8899。如果你想要其他端口，改 -p 左边就行。
Docker Compose 更清晰，把下面的内容存成 docker-compose.yml：
services:
libretv:
image: bestzwei/libretv:latest
container_name: libretv
ports:
- "8899:8080"
environment:
- PASSWORD=${PASSWORD:-111111}
restart: unless-stopped然后 docker compose up -d 启动，访问 http://localhost:8899。默认密码是 111111，建议改成你自己的。
注意：如果你改了端口映射，比如改成 -p 3000:8080，访问时就用 http://localhost:3000。环境变量优先从宿主机的 PASSWORD 环境变量读取，如果没有才用 111111。
本地开发 —— 不能偷懒用静态服务器
项目包含后端代理功能，视频播放依赖这个代理。如果你图省事，用 python -m http.server 或 npx http-server 启动，视频播放会失败。README 明确写了这一点。
正确的本地开发步骤：
cp .env.example .env # 可选，不复制也能运行
npm install
npm run dev启动后访问 http://localhost:8080。端口可以在 .env 文件里用 PORT 变量修改。npm run dev 是带热重载的，改代码页面自动刷新。
必须设置密码，不是玩笑
所有部署方式都强制要求设 PASSWORD 环境变量。如果你不设置，页面会显示提示让你输入密码——但这个密码是第一次访问时你设置的，实际上代码逻辑里没有设密码就拒绝服务。为什么这么严？README 声明项目只能用于学习和个人使用，不能公开分享。设置密码就是一道门，防止被滥用。你把实例公开了，产生的版权纠纷你自己扛。
同步 fork 仓库的坑
主仓库会持续更新，如果你 fork 了自己的副本，想同步最新代码。README 专门写了一节警告：不要用 Pull Bot。Pull Bot 会反复发送无效 PR 和垃圾邮件，作者可能会拉黑所有用 Pull Bot 的仓库所有者。
推荐的做法有两种：
- 启用自带 GitHub Actions：在你的 fork 仓库里，找到
.github/workflows/sync.yml，这个 workflow 会自动同步主仓库更新。不需要你自己配置，默认是开启的。 - 手动同步：GitHub 官方提供了“Sync fork”按钮，点击后选择更新即可。
如果同步后页面出现报错，先备份设置（在页面设置面板里导出配置），然后清除浏览器 Cookie，再用 Ctrl + F5 强制刷新页面。我遇到过一次，清 Cookie 确实解决了问题。
如何添加自己的视频源
LibreTV 支持苹果 CMS V10 API 格式。如果你有自己的资源站，只要它兼容这个协议，就能接入。
添加路径：打开 LibreTV 页面 → 设置面板 → 选择“自定义接口” → 填写接口地址，比如 https://example.com/api.php/provide/vod。
系统会自动识别两个接口：
- 搜索接口：
https://example.com/api.php/provide/vod/?ac=videolist&wd=关键词 - 详情接口：
https://example.com/api.php/provide/vod/?ac=detail&ids=视频ID
注意：很多公开的 CMS 源不稳定，可能跑几个月就失效了。你可以自己搭建一个 CMS 后端，或者找一些长期维护的公开源。但老实说，公开源的质量参差不齐，卡顿、字幕不对是常事。
播放器快捷键
播放视频时可以用键盘：
- 空格：播放/暂停
- 左右箭头：快退/快进
- 上下箭头：音量增减
- M：静音/取消静音
- F：全屏/退出全屏
- Esc：退出全屏
没有特别之处，算是标准操作。
法律声明不是套话
README 里有一条“重要声明”，写得直接：
- 仅供学习和个人使用
- 不能用于商业或公开服务
- 如果公开分享导致侵权问题，用户自己负责
部署时设密码就是满足“个人使用”的一部分。别想着搭一个公共站给别人用，版权风险是真实的，而且作者已经明确撇清责任了。
技术栈
README 里列了 ` `（空？），实际从代码可以看到前端是用 Vue（或类似框架），后端是 Node.js 代理。但具体版本信息 README 没给，我就不瞎写了。