Skill: YouTube 热门视频爬虫
基本信息
- ID: youtube-crawler
- 类型: data-collection
- 版本: 1.0.0
- 状态: training
- 目标分数: 95/100
功能描述
从 YouTube 获取当日最热门视频列表,支持 API 和降级方案。
输入参数
| 参数 |
类型 |
必填 |
默认值 |
说明 |
| regionCode |
string |
否 |
"US" |
地区代码 (ISO 3166-1 alpha-2) |
| videoCategoryId |
string |
否 |
null |
视频分类 ID |
| maxResults |
integer |
否 |
10 |
返回数量 (1-50) |
| useApi |
boolean |
否 |
true |
优先使用 API |
输出字段
| 字段 |
类型 |
说明 |
| videoId |
string |
YouTube 视频 ID |
| url |
string |
完整视频链接 |
| title |
string |
视频标题 |
| channelTitle |
string |
频道名称 |
| viewCount |
integer |
播放次数 |
| thumbnail |
string |
高清封面 URL |
| publishedAt |
string |
发布时间 (ISO 8601) |
实现方案
方案 1: YouTube Data API v3 (推荐)
async function getTrendingVideosAPI({ regionCode = 'US', maxResults = 10, apiKey }) {
const url = 'https://www.googleapis.com/youtube/v3/videos';
const params = new URLSearchParams({
part: 'snippet,statistics',
chart: 'mostPopular',
regionCode,
maxResults: Math.min(Math.max(1, maxResults), 50),
key: apiKey
});
const response = await fetch(`${url}?${params}`);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
return data.items.map(item => ({
videoId: item.id,
url: `https://youtube.com/watch?v=${item.id}`,
title: item.snippet.title,
channelTitle: item.snippet.channelTitle,
viewCount: parseInt(item.statistics.viewCount, 10),
thumbnail: item.snippet.thumbnails.high?.url || item.snippet.thumbnails.default?.url,
publishedAt: item.snippet.publishedAt
}));
}
方案 2: yt-dlp (降级)
async function getTrendingVideosYTDLP({ regionCode = 'US', maxResults = 10 }) {
// 使用 yt-dlp 命令行
const { execSync } = require('child_process');
const url = regionCode === 'US'
? 'https://www.youtube.com/feed/trending'
: `https://www.youtube.com/feed/trending?gl=${regionCode}`;
const cmd = `yt-dlp --flat-playlist --playlist-end ${maxResults} -J "${url}"`;
const output = execSync(cmd, { encoding: 'utf-8', timeout: 30000 });
const data = JSON.parse(output);
return data.entries.map(entry => ({
videoId: entry.id,
url: entry.webpage_url || `https://youtube.com/watch?v=${entry.id}`,
title: entry.title,
channelTitle: entry.uploader,
viewCount: entry.view_count || 0,
thumbnail: entry.thumbnail,
publishedAt: entry.upload_date
? `${entry.upload_date.slice(0,4)}-${entry.upload_date.slice(4,6)}-${entry.upload_date.slice(6,8)}T00:00:00Z`
: null
}));
}
统一入口
async function getTrendingVideos(options) {
const { useApi = true, apiKey, ...rest } = options;
if (useApi && apiKey) {
try {
return await getTrendingVideosAPI({ ...rest, apiKey });
} catch (error) {
console.warn('API failed, falling back to yt-dlp:', error.message);
}
}
return await getTrendingVideosYTDLP(rest);
}
错误处理
| 错误码 |
场景 |
处理策略 |
| 400 |
请求参数错误 |
返回 validation error |
| 401/403 |
API Key 无效 |
自动降级到 yt-dlp |
| 429 |
配额超限 |
自动降级到 yt-dlp |
| 500+ |
服务器错误 |
重试 3 次后降级 |
| timeout |
请求超时 |
切换方案重试 |
配置示例
{
"youtube-crawler": {
"apiKey": "${YOUTUBE_API_KEY}",
"defaultRegion": "US",
"maxResults": 10,
"cacheMinutes": 15
}
}
依赖
- Node.js ≥ 16
- yt-dlp (可选,用于降级方案)
- YOUTUBE_API_KEY 环境变量 (可选)
评分历史
| 版本 |
分数 |
日期 |
主要改进 |
| v1.0 |
TBD |
2026-04-01 |
初始版本 |