> For AI agents: the site index is available at https://www.juniortree.com/llms.txt; this page is available as Markdown at https://www.juniortree.com/docs/integrations/youtube.md.
> 在 MDX 文章中插入带本地封面的 YouTube 视频卡片

## Page metadata

- **Source URL:** https://www.juniortree.com/docs/integrations/youtube

# YouTube 视频卡片

`YouTube` 组件用于在文章中插入一张 YouTube 视频卡片：展示封面、标题与作者，点击后在新标签页打开 YouTube 观看。

封面图与标题在**构建时**自动抓取并缓存到本地（`public/youtube/`），因此国内读者无需依赖 YouTube CDN 也能看到封面。

## 用法

只需要传入视频 ID（即 `watch?v=` 后面那一段）：

```mdx
import YouTube from '@/components/mdx/YouTube.astro'

<YouTube id='dQw4w9WgXcQ' />
```

**Note:**

  本组件只能在 `.mdx` 文章中使用。如果你的文章目前是 `.md`，需要先把扩展名改成 `.mdx`。

## 属性

| 属性    | 类型     | 说明                                                       |
| ------- | -------- | ---------------------------------------------------------- |
| `id`    | `string` | 必填。YouTube 视频 ID。                                     |
| `title` | `string` | 可选。构建时未能抓到标题时的兜底文本。                     |
| `class` | `string` | 可选。自定义类名。                                         |

## 工作原理

1. 构建脚本 `scripts/cacheYoutube.mjs` 扫描 `src/content/**` 下所有 `<YouTube />` 用法，收集视频 ID。
2. 对每个 ID 下载缩略图到 `public/youtube/<id>.jpg`（优先 `maxresdefault`，失败回退 `hqdefault`），并通过 [oEmbed](https://oembed.com/) 抓取标题与作者。
3. 抓取结果写入 `src/data/youtube-metadata.json`，组件在渲染时读取该文件取本地封面与标题。

该脚本已挂在 `dev`、`build`、`check` 流程前自动执行（与 `paper:sync` 并列）。如需强制刷新所有封面与元数据：

```bash
npm run youtube:sync -- --refresh
```

**tip:**

  如果构建机器无法访问 YouTube，封面会暂时回退到远程 URL，标题回退到 `title` 属性或默认文本。一旦在能访问的环境跑过一次
  `youtube:sync`，缓存就会被提交进仓库，之后任何环境构建都能离线使用本地封面。