项目：EgalitarianMonkey/hometube（AGPL-3.0，1.3k stars，75 commits，仍在活跃维护）
一句话：一个网页版的下载工具，把 YouTube 等网站的单个视频或整个播放列表，自动下载成画质最好、没有广告、命名规范的文件，文件位置就是你家媒体服务器（Plex / Jellyfin / Emby）盯着的目录，下载完就能看。
一、它解决什么问题
假设你是这样一个人：
- 家里有一台跑着的服务器（"HomeLab"），上面装了 Jellyfin 或 Plex，专门存电影、剧集、自己的视频
- 你在 YouTube 上看到不错的视频，想留在本地长期看（离线、不被删、画质稳定）
- 手动下载的老办法是：找个下载网站/工具 → 输入链接 → 挑画质 → 下载 → 改文件名 → 找到媒体库的文件夹 → 把文件拖进去 → 等服务器识别
这套流程问题很多：画质的坑（下载工具默认给你低码率，或下载失败）、文件名乱七八糟（媒体服务器认不出谁是谁）、YouTube 更新后旧方法失效、看视频带广告和赞助。
HomeTube 干的就是：你只做一步（贴链接），剩下的全自动。
二、日常用法（小白视角）
打开网页（本机 8501 端口），在输入框粘贴：
https://www.youtube.com/watch?v=xxxxx回车。之后：
- 自动分析这个视频有哪些画质和编码格式，挑出一档「当前最好的」（比如 4K + 高效率编码 + 高质量音轨）；网络不稳定或格式缺失时自动降一档重试
- 下载完成后，把 YouTube 里的赞助广告段落标记/剪掉（SponsorBlock 社区数据库）
- 视频自动保存且改名，类似
TechInterview - 2026-08，放进你配置的目录 - 发你的媒体库会自动扫到这个视频，打开电视就能看
也可以粘贴整个播放列表。它会记住每个视频的 ID（标题改了不影响），只下载新增的，列表里删掉的视频你可以选择「删除」或「移动到一个叫 Archives 的归档文件夹」。
三、能下载哪些网站
底层用的是 yt-dlp（一个成熟的开源项目），所以支持的平台绝大多数：1800+ 种。常见的都行：YouTube、Twitch、Vimeo、TikTok、Instagram、Bilibi、Coursera 课程等。
但注意：不同平台对下载的限制不同。YouTube 是主要目标，也特别复杂（见下方「坑」）。其他站能用不等于一直能用，取决于对方反爬。
四、怎么部署
主要方式 Docker，一条命令。需要准备三个目录（后面都会用到）：
| 你需要提供的 | 是什么 | 例子 |
|---|---|---|
| 视频保存目录 | 媒体服务器生成的文件夹 | /mnt/media/videos |
| 临时下载目录 | 下载先落到这里、处理完毕再移走 | /mnt/hometube/tmp |
| 浏览器 Cookie 文件 | 让下载器装成你，绕开反爬（详见「坑」） | /opt/cookies/youtube.txt |
Docker 命令：
docker run -p 8501:8501 \
-e VIDEOS_FOLDER=/data/videos \
-e TMP_DOWNLOAD_FOLDER=/data/tmp \
-e YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt \
-v /mnt/media/videos:/data/videos \
-v /tmp/hometube:/data/tmp \
-v /opt/cookies:/config \
ghcr.io/egalitarianmonkey/hometube:latest访问 http://你服务器的IP:8501 即可使用。配置都用环境变量管理，UI 里也有常用的设置项（分辨率上限、首选语言、字幕开关等），高级用户还可输自定义 yt-dlp 参数（代理、文件大小限制等）。
官方还提供 Docker Compose、Portainer（可视面板管理轻量级）、或直接本地跑 Python 三种方式。系统要求不高：512MB 内存、2GB 磁盘就能跑动。
五、先知道的坑（客观说）
- 浏览器 Cookie 是必需品，不是可选项。YouTube 这几年加了反爬和「签名加密」（n-sig），不提供 Cookie 时经常下载失败，即使公开视频也不例外。Cookie 的意思：从浏览器挑一个导出来，或填一个文件路径，让下载器「以你的身份」访问。网页版（UI）能配置，但 Docker 部署下只能用一个现成的 Cookie 文件，导出的过程需要手动操作一次。第一次部署就准备好，否则一直卡在坑里。
- Docker 里不能用
COOKIES_FROM_BROWSER（文档明确标注 "Not working natively in Docker"），必须挂文件。
- Docker 里不能用
- 默认没有登录/密码。网页界面上线即可用，假定你在局域网里跑。想从外部访问需要自己加反向代理 + 认证。注意安全。
- 界面语言只有英文和法文。中文界面没有，主用中文的用户「小白可读性」有限，核心功能处有图解可以勉强用。文件名、字幕语言不受影响。
- 播放列表删除策略要留意。同步时源列表里删掉的视频，默认会删掉本地文件，不是移到存档。要存先把
PLAYLIST_KEEP_OLD_VIDEOS=true打开。 - 文件保护默认开启：
ALLOW_OVERWRITE_EXISTING_VIDEO=false，同名旧文件不会被覆盖。 - 本项目高频更新（yt-dlp 频繁变化，上游 YouTube 反爬也在变），建议用 Docker 镜像定期
docker pull升级，手动跑 Python 需要手动更新。
六、适合谁 / 不适合谁
- 适合：已经跑着 Plex / Jellyfin 的家庭服务器玩家；想在本地保留 YouTube 高质量视频；想把自己爱看的系列（教程、播客视频版）自动同步的。
- 不适合：只是偶尔下载一两个视频的人（yt-dlp 命令行 10 秒搞定的事，用 HomeTube 是大炮打蚊子）；想下付费网站 / 网飞等正经流媒体内容（技术上多数不可能，也不该做）；不想折腾服务器的。
七、总结
HomeTube 不是第一个下载工具，也不是功能最全的优点在于——面向的不是「下载文件」而是「把视频放进自家媒体库」这个完整流程：画质挑到最优、广告剪掉、命名规范、播放列表可持续同步、下载完媒体服务器自动识别。代价是：需要 Docker（或不复杂）、必须准备 Cookie 文件、中文界面缺失。
对已经搭好家庭影音库的用户：值得试一试，半小时内能跑通。（装不上的问题请反馈：GitHub Issues / r/HomeTube 社区）
八、同类工具对比（怎么选）
| 工具 | 一句话定位 | 与 HomeTube 的关键差异 |
|---|---|---|
| HomeTube | 单视频 + 播放列表，下载后直接进媒体库自动整理 | 画质最优方案自动降级、SponsorBlock 去广告、播放列表按视频 ID 同步 |
| MeTube | 最主流的 yt-dlp 网页界面（约 14k stars，AGPL-3.0） | 更成熟、UI 更简单；不做画质智能选择/剪广告/媒体库整理，文件命名靠 yt-dlp 模板 |
| TubeSync | 面向 Plex/Jellyfin 的「频道订阅机」：自动抓频道新视频 | 擅长持续订阅和媒体库整合；单次临时下载不如 HomeTube 顺滑 |
| ytdl-sub | 把 YouTube 订阅当成「剧集」组织（季/集命名、刮削友好） | 配置式（YAML），对 Plex/Jellyfin 最友好；学习成本高，不说小白向 |
| yt-dlp 命令行 | 上面所有工具共同的地基 | 最强、最灵活、全部手动：命名模板、去广告参数、续传都需自己写 |
选择建议：
- 想「贴链接 → 自动挑最优画质 → 去广告 → 进媒体库」→ HomeTube
- 想要成熟稳定、订阅了频道自动抓 → MeTube
- 想「关注频道永不手动，自动入库并被媒体服务器识别」→ TubeSync
- 想在媒体服务器里把订阅整理成「剧集」结构、并接受 YAML 配置 → ytdl-sub
- 自己是命令行人、不想维护图形界面 → 直接用 yt-dlp
参考
- 项目 README、官方文档 docs/usage.md、docs/deployment.md（github.com/EgalitarianMonkey/hometube）
- MeTube：github.com/alexta69/metube
- yt-dlp：github.com/yt-dlp/yt-dlp