Cobalt 视频下载：自建无广告下载器完整实操指南-平芜编程栈

Cobalt 视频下载：自建无广告下载器完整实操指南

【免费下载链接】cobaltbest way to save what you love项目地址: https://gitcode.com/GitHub_Trending/cob/cobalt

想存一条 4K 的 YouTube 视频，通常要在十几个第三方站点之间换来换去，还躲不开广告和限速。Cobalt 是一个可自托管的视频下载工具：无广告、无追踪、无付费墙，支持 YouTube、TikTok、B 站等 20 多个平台。部署到自己的服务器上，下载行为完全由你说了算。

🚀 3 条命令启动自己的 Cobalt 实例

前提只有一条：机器上装好 Docker 和 Docker Compose。拿到仓库后直接跑：

git clone https://gitcode.com/GitHub_Trending/cob/cobalt cd cobalt docker compose up -d

compose 文件照抄 docs/examples/docker-compose.example.yml，唯一必须改的是API_URL和WEB_URL两个默认地址——不换自己的域名，前端请求会打到别人的实例上。Docker 包内置 watchtower，容器自动拉新版本，你不用管升级。手动安装只留给本地开发：Node.js 18 以上，npm run setup选角色，npm start跑起来。支持需要登录内容的平台时，在实例目录放一个cookies.json（样例见 docs/examples/cookies.example.json），用COOKIE_PATH指向它。完整清单在 docs/run-an-instance.md。

🎛️ 参数速查：改一个值，换一种下载行为

下载分三个互斥模式：默认"视频+音频"，加isAudioOnly: true只下音频，加isAudioMuted: true去掉音轨。核心请求参数就下面这些：

取值	作用	备注
`vQuality`: 144–2160 /`max`	视频分辨率	默认 720，手机端建议 720
`vCodec`:`h264`/`av1`/`vp9`	YouTube 编码	默认`h264`，手机兼容性最好
`aFormat`:`mp3`/`ogg`/`wav`/`opus`/`best`	音频格式	默认`mp3`，仅音频模式生效
`isAudioOnly`/`isAudioMuted`	切音频或视频模式	默认都是`false`，即原片

平台专属开关和文件名模板：

取值	作用	备注
`isTTFullAudio: true`	TikTok 原始完整音源	拿视频用的 BGM 原曲
`tiktokH265: true`	优先 1080p HEVC 版	TikTok 专属
`twitterGif: true`	Twitter GIF 转成 .gif 文件	默认直接下动图
`filenamePattern`:`classic`/`pretty`/`basic`/`nerdy`	文件名风格	默认`classic`，如`youtube_ID_1920x1080_h264.mp4`；`nerdy`会把视频 ID 和平台名塞进文件名，归档最好用

文件名怎么拼的看 src/modules/processing/createFilename.js，标题、分辨率、编码、音轨语言都保留，素材入库后不用二次重命名。

📚 三个真实场景的参数组合

做课件的老师：网课链接贴进网页，isAudioOnly: true加aFormat: opus，只拿音频。文件小，教室里反复播放不占空间，省掉下载整段视频的功夫。

运营做素材备份：品牌官号每条 Reel 过一遍 Cobalt，filenamePattern: nerdy，文件名自带视频 ID 和平台来源，按项目文件夹进网盘，盘点素材不用再回网站翻历史。

剪片的人存参考：YouTube 剪辑教程用vQuality: 2160拉满画质收藏，TikTok 转场片段加isTTFullAudio: true把背景音乐整段存下来，后面找原曲一步到位。

🔌 脚本直接调 API：接口与环境变量

整个服务就是一个 REST 接口，前端和 API 分离部署，所以任何脚本都能直连，最精简的调用长这样：

const res = await fetch('http://localhost:9000/api/json', { method: 'POST', headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://www.youtube.com/watch?v=xxxxx', vQuality: '2160' }) })

成功时返回status: success和一条带签名、有时效的直接下载链接，拿来即用。全字段说明见 docs/api.md，20 多个平台的处理逻辑各占一个文件，集中在 src/modules/processing/services/。实例要暴露公网时，重点配这几个环境变量：

API_PORT=9000 WEB_PORT=9001 API_URL=https://api.example.com/ WEB_URL=https://example.com/ RATELIMIT_WINDOW=60 RATELIMIT_MAX=20 CORS_WILDCARD=0 CORS_URL=https://example.com

RATELIMIT_WINDOW和RATELIMIT_MAX定义每个 IP 在多少秒内最多请求多少次，超了直接 429，这是防滥用的第一道闸；CORS_WILDCARD=0后只有CORS_URL里的域名能调你的 API。外面再套一层 nginx 反向代理，实例就稳了。