> For AI agents: the complete documentation index is available at https://www.notionhub.app/llms.txt, the full documentation bundle is available at https://www.notionhub.app/llms-full.txt.

# YouTube 同步到 Notion

NotionHub 可以将 YouTube 账号中的播放列表、赞过的视频和自己上传的视频资料整理到 Notion，并关联视频所属频道。需要保存视频文件时，可以另行选择上传范围。

## 可以同步什么

| 内容           | 在 Notion 中查看              |
| ------------ | ------------------------- |
| 自己的频道及视频所属频道 | 名称、头像、简介、频道链接及可获取的统计信息    |
| 自己的播放列表      | 列表名称、链接、视频数，以及与视频的关联      |
| 播放列表中的视频     | 标题、封面、来源链接、描述、时长及可获取的统计信息 |
| 赞过的视频        | 视频资料、「点赞」来源，以及「赞过的视频」列表关联 |
| 自己上传的视频      | 视频资料及「上传」来源               |
| 视频文件（可选）     | 为选中范围内、可下载的视频补充文件与播放内容    |

频道库会收录自己的频道及上述视频对应的频道，不会自动备份订阅频道列表或订阅频道的全部视频。当前也不专门采集观看历史、观看进度、评论正文、字幕或「稍后再看」。只保存了别人的播放列表，不保证该列表会作为自己的播放列表返回。

视频的发布时间、加入列表时间和收藏时间含义不同。赞过的视频没有可用的加入时间时，收藏时间会使用视频发布时间，不能据此判断真实点赞时间或观看时间。

## 使用前准备

- 安装最新版 [NotionHub 浏览器插件](https://www.notionhub.app/docs/install.md)，并登录 NotionHub。
- 准备可以正常使用 [YouTube](https://www.youtube.com/) 的 Google 账号，并确认能打开 Google 授权页面。
- 准备自己的 Notion 工作区，使用插件提供的 YouTube 模板。
- 按插件提示连接 GitHub，用于运行同步任务，参见 [GitHub Action 同步](https://www.notionhub.app/docs/github-action.md)。
- 确认服务有可用的体验次数或已激活，具体范围以插件显示为准，参见 [免费体验与激活](https://www.notionhub.app/docs/free-trial.md)。

基础资料通过 Google 授权读取，无需手动填写 Token 或自行创建开发者应用。视频下载使用的浏览器登录状态是可选的另一项配置，不能替代 Google 授权。

## 第一步：复制并授权 Notion 模板

1. 打开 NotionHub 插件，在服务列表中选择「YouTube」。
2. 在「Notion 模板」卡片点击「去复制」。
3. 在 Notion 授权页面选择开发者提供的模板，确认工作区并允许访问。
4. 返回插件，等待模板显示已配置，再点击「打开模板」确认页面。

如果插件提示提交链接，请提交自己工作区内复制后的模板链接。请保留视频、频道、播放列表数据库，以及视频的来源、列表关系、文件与上传状态等字段，参见 [Notion 模板与授权](https://www.notionhub.app/docs/notion-template.md)。

## 第二步：通过 Google 连接 YouTube

1. 在 YouTube 账号卡片点击「去连接」。
2. 在打开的 Google 授权页面选择目标账号；出现频道选择时，选择日常使用的频道。
3. 查看并允许所需的账号身份信息和 YouTube 只读权限。
4. 授权成功后回到插件，等待账号卡片显示「已连接」，并核对账号或频道名称。

只登录 YouTube 网页不会自动完成这一步。授权后会读取账号资料，不会把 Notion 中的修改写回 YouTube，也不会向 YouTube 上传视频。

如果 Google 明确提示应用仅向测试用户开放、账号无权访问或被组织管理员阻止，当前账号可能无法完成授权。请根据页面原因联系 [技术支持](https://www.notionhub.app/docs/support.md) 或账号管理员；重新复制 Notion 模板、刷新网页或获取 Cookie 都不能解除 Google 的授权限制。

## 第三步：选择是否上传视频文件

只需要标题、链接、封面和列表关系时，可以不配置视频文件上传，直接开始同步。

如需保存视频文件：

1. 在安装插件的同一个浏览器中登录 YouTube，确认使用的是有权访问目标视频的账号。
2. 回到服务页面，在「YouTube Cookie」卡片点击「获取 Cookie」，按提示允许网站访问权限。如果插件打开了登录页，完成登录后再回来获取。
3. 打开「同步设置」，找到「视频上传范围」。
4. 勾选需要上传视频的播放列表；也可以单独选择「赞过的视频」。设置保存后，在下一次同步时生效。

**这些勾选只控制视频文件下载和上传，不控制基础资料的同步范围。** 全部不选表示关闭全部视频上传，播放列表和点赞等基础资料仍会同步。旧模板中可能保留「上传视频」字段，当前请以插件设置页中的选择为准。

自己的上传视频会同步基础资料，但不会仅因来源为「上传」就自动保存视频文件；需要处于已选择的列表或点赞范围内。已成功保存的文件通常不会重复下载。

视频文件能否成功保存还取决于账号访问权限、地区或年龄限制、YouTube 登录校验，以及 Notion 工作区或所用存储的上传限制。获取 Cookie 或完成 Google 授权都不保证每个视频能够下载，参见 [图片、音频和视频上传](https://www.notionhub.app/docs/media-upload.md)。

## 第四步：开始同步并查看结果

完成模板与 Google 授权后，点击「开始同步」。如果提示连接 GitHub，点击「连接 GitHub」并完成授权，再按提示继续。

通过插件的运行记录或对应的 GitHub Action 查看进度。任务未结束时，避免重复点击。运行完成后，打开 Notion 模板，检查视频、频道、播放列表之间的关联；赞过的视频会关联到「赞过的视频」列表。

视频页面中的 YouTube 播放入口是来源链接的嵌入，不代表视频文件已经保存。开启文件上传后，应另外检查视频文件和上传状态。媒体处理未完成或失败时，基础资料可能已经写入。

后续同步会识别并更新已有记录。普通同步的列表读取有分页范围；历史较多、较早的视频未出现时，可以在权益允许时使用「全量同步」继续读取可用分页。全量同步仍无法恢复 YouTube 不再返回的私密、已删除或不可访问内容，也不会新增当前不支持的观看历史范围。

取消点赞、删除播放列表或移出视频，不会自动删除 Notion 中已经保存的页面。在 Notion 中编辑记录也不会回写 YouTube。

## 常见问题

### Google 已授权，为什么仍然需要「获取 Cookie」？

Google 授权用于读取频道、列表和视频资料；「YouTube Cookie」用于视频下载时的网页登录校验。只同步基础资料可以不获取 Cookie。视频上传提示登录失效时，可先在 YouTube 网页确认登录，再点击「重新获取」。

### 为什么 Google 授权失败或提示权限不足？

先核对选择的账号，并确认同意了 YouTube 只读权限。拒绝权限或授权已失效时，可以点击「重新连接」重新授权。若 Google 明确限制当前账号使用该应用，需按授权页面提示处理，不能通过插件绕过限制。保留错误文字即可，无需向他人发送授权回调地址或凭证。

### 没有自己的 YouTube 频道，还能同步吗？

可以尝试同步赞过的视频。账号没有可访问频道时，会跳过自己的频道、播放列表和上传视频，继续读取点赞内容。如果上传范围列表也读取失败，先保留文件上传关闭，检查基础同步结果，再联系支持。

### 明明取消了某个播放列表的勾选，为什么其中的视频还出现？

该开关控制视频文件上传，不会排除基础资料。若同一视频同时属于另一个已勾选列表或已勾选的「赞过的视频」，它仍可能进入文件上传范围。取消勾选也不会删除已经保存的文件或页面。

### 为什么视频数量与网页不一致？

检查账号或频道是否正确、任务是否完成、体验额度以及普通同步的分页范围。同一视频出现在多个列表或同时被点赞时，会复用同一视频页面；列表条目数不等于独立视频页面数。私密、已删除或授权账号不可访问的视频，也可能无法取得详情。

### 有视频页面，却没有视频文件怎么办？

先检查「视频上传范围」是否选中对应列表或「赞过的视频」，再检查浏览器登录状态和上传结果。YouTube 对下载的限制与资料读取不同，即使基础资料同步成功，也可能无法下载文件。可保留来源链接继续使用，并按 [运行状态与排错](https://www.notionhub.app/docs/sync-status.md) 检查失败原因。

仍有问题时，查看 [第三方平台登录方式](https://www.notionhub.app/docs/service-login.md) 或联系 [技术支持](https://www.notionhub.app/docs/support.md)。