> 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.

# Trakt 同步到 Notion

NotionHub 可以根据 Trakt 中已记录的观看历史，在 Notion 中建立电影、剧集和单集资料库，并关联已经看过的单集与所属剧集。

## 可以同步什么

| 内容         | 在 Notion 中查看                    |
| ---------- | ------------------------------- |
| 电影观看历史中的作品 | 电影标题、年份和 Trakt 链接               |
| 剧集观看历史中的单集 | 单集标题、季数、集数、播放日期和 Trakt 链接       |
| 单集所属剧集     | 剧集页面，以及剧集与单集的关联                 |
| 可获取的影视补充资料 | 来自 TMDB 的中文标题、海报、简介、类型、片长及相关链接等 |

同步范围是 Trakt 已有的电影和单集观看历史，不包含待看清单、收藏清单、自定义列表或个人评分。只在其它播放器看过、但尚未记录到 Trakt 的内容，也不会自动进入 Notion。

当前按电影或单集识别已有页面，不会为每次重看分别建页。单集页可写入一个「播放日期」；电影页当前保存作品资料，不写入电影观看日期，因此不能把整份模板当作逐次观看日志。

## 使用前准备

- 安装最新版 [NotionHub 浏览器插件](https://www.notionhub.app/docs/install.md)，并登录 NotionHub。
- 准备能正常登录 [Trakt](https://trakt.tv/) 的账号，并确认需要同步的内容已经出现在观看历史中。
- 准备自己的 Notion 工作区，使用插件提供的 Trakt 模板。
- 按插件提示连接 GitHub，用于运行同步任务，参见 [GitHub Action 同步](https://www.notionhub.app/docs/github-action.md)。
- 确认服务有可用的体验次数或已激活，具体范围以插件显示为准，参见 [免费体验与激活](https://www.notionhub.app/docs/free-trial.md)。

Trakt 使用账号授权连接。只在网页中登录还不够，还需要同意 NotionHub 的授权请求；无需自行创建开发者应用或手动填写访问令牌。

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

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

如果插件提示提交链接，请打开自己工作区里的模板，复制页面链接后提交。不要提交官方模板预览链接。

请保留电影、剧集、单集数据库，以及单集与剧集之间的关系。调整视图不影响使用，但删除数据库或修改必要字段的类型可能导致同步失败，参见 [Notion 模板与授权](https://www.notionhub.app/docs/notion-template.md)。

## 第二步：授权 Trakt

1. 在 Trakt 账号卡片点击「去授权」。
2. 在打开的 Trakt 授权页面登录目标账号，并同意授权请求。
3. 授权完成后返回插件，等待显示账号信息和「已登录」。

请在安装插件的同一个浏览器中完成授权，并核对显示的账号。正常流程会自动处理授权回调，无需复制回调地址或手动提交授权码。

如果授权页已完成但插件没有连接成功，确认浏览器允许插件访问回调页面，再从账号卡片重新发起授权。

## 第三步：检查同步设置

首次使用可以保持默认设置。Trakt 同步会依次处理电影历史和单集历史，当前没有分别选择电影、剧集的范围开关，也不提供影视视频下载。

热力图和通知可按「同步设置」中的可用选项调整。它们不会扩大采集范围，也不会把重复观看变成独立的 Notion 记录。

普通增量同步分别检查最近最多 100 条电影历史和 100 条单集历史，体验同步还会受额度限制。如果有较早的观看历史，或两次同步之间新增记录很多，可以在权益允许时使用服务页面的「全量同步」。全量同步会继续读取可用历史分页，并更新已有作品资料。

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

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

同步启动后，通过插件运行记录或对应的 GitHub Action 查看进度。任务未结束时，避免重复点击。运行完成后，打开模板分别检查：

- **电影库**：观看历史中的电影及可获取的作品资料。
- **剧集库**：已同步单集所属的剧集。
- **单集库**：具体的季、集、播放日期，以及与剧集的关联。

普通同步主要新增尚不存在的电影和单集，已存在的记录可能不会重新更新。修改过历史或需要补充影视资料时，可以尝试全量同步。

在 Trakt 中删除历史，不会自动删除 Notion 中已有页面；在 Notion 中修改作品信息或播放日期，也不会回写 Trakt。

## 常见问题

### 已登录 Trakt 网页，为什么还需要授权？

网页登录和允许 NotionHub 读取账号数据是两个步骤。请从插件的 Trakt 账号卡片完成授权，直到插件显示账号信息。授权失效时，点击「重新登录」并重新同意授权请求。

### 为什么没有待看清单、评分，或整部剧的全部单集？

当前读取观看历史，只同步已记录为看过的电影与单集。加入待看清单不等于产生观看历史；看过一集也不会自动导入整部剧的所有单集。个人评分不在当前同步范围内。

### 为什么旧历史或最近修改的记录没有更新？

先检查运行是否完成、账号是否正确，以及是否受到体验限制。普通同步读取最近的一段历史，并跳过已有作品；更早的内容或已存在页面的资料更新可尝试全量同步。

### 重看同一部电影或同一集会产生多条记录吗？

不会。当前按作品或单集复用页面，不能完整保留每次重看的日期和次数。电影页不写入观看日期；单集页仅有一个播放日期，全量同步也不会生成逐次观看明细。

### 为什么有的海报、中文标题或简介缺失？

这些属于补充资料，取决于 TMDB 是否有对应信息及当次能否获取。缺少补充资料时，Trakt 的基础作品信息仍可写入；不要仅凭海报缺失判断整个同步失败。可在后续尝试全量同步补充。

仍有问题时，查看 [运行状态与排错](https://www.notionhub.app/docs/sync-status.md) 或联系 [技术支持](https://www.notionhub.app/docs/support.md)。