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

# 微信读书 Pro 版配置教程

<iframe src="https://player.bilibili.com/player.html?bvid=BV1MW8w6hEsT&page=1&high_quality=1&danmaku=0&autoplay=0" scrolling="no" frameborder="0" allowfullscreen style="width: 100%; aspect-ratio: 16 / 9; border: 0; border-radius: 8px;"></iframe>

如果播放器无法加载，可以[前往 B 站观看微信读书 Pro 版配置教程](https://www.bilibili.com/video/BV1MW8w6hEsT/)。

::: tip 还没有安装 NotionHub？
如果浏览器中还没有安装 NotionHub 插件，请先点击[安装文档](https://www.notionhub.app/docs/install.md)，根据你使用的 Chrome、Edge 或 Firefox 完成安装，再返回本页继续配置。
:::

微信读书 Pro 版可以将书架、读过或做过笔记的书籍、划线、想法、阅读时长和阅读热力图同步到 Notion，并支持全量更新、数据修复和自动同步。

## 开始前准备

开始配置前，请确认：

- 已安装并打开 NotionHub 浏览器插件。
- 浏览器中可以正常登录 Notion。
- 手机微信可以扫描微信读书登录二维码。
- 已有 GitHub 账号，或者可以使用 Google / Apple 账号登录 GitHub。

::: tip 只需要免费版？
如果你只需要同步书架中的书籍，可以在插件的微信读书页面切换到「免费版」。免费版基于开源 [WeRead2Notion](https://www.notionhub.app/docs/weread2notion.md)，不需要自行编写 GitHub Actions。本文后续步骤介绍的是功能更完整的「Pro 版」。
:::

## 1. 打开微信读书 Pro 版

1. 点击浏览器工具栏中的 NotionHub 插件图标。
2. 在同步服务列表中找到「微信读书」，点击进入。
3. 在微信读书配置页顶部选择「Pro 版」。

如果插件没有显示在工具栏中，可以先打开浏览器的扩展程序菜单，将 NotionHub 固定到工具栏后再操作。

## 2. 登录并授权 Notion

第一次进入微信读书配置页时，插件会提示先登录 Notion。

1. 点击 Notion 登录入口，浏览器会打开 Notion 授权页面。
2. 选择要使用的 Notion 工作区，然后点击「下一步」。
3. 检查授权范围，选择「使用开发人员提供的模板」。
4. 点击「允许访问」，等待页面返回 NotionHub 插件。

完成后，配置页中的 Notion 账号会显示为已连接状态。

## 3. 复制并连接微信读书模板

登录 Notion 后，需要复制 NotionHub 提供的微信读书模板。

1. 在配置页找到 Notion 模板区域，点击「去复制」。
2. 在确认弹窗中继续点击「去复制」，打开 Notion 模板页面。
3. 选择要保存模板的 Notion 工作区。
4. 选择「使用开发人员提供的模板」，然后点击「下一步」。
5. 点击「允许访问」，完成模板复制和授权。
6. 关闭授权页面并返回 NotionHub 插件。

请使用开发者提供的模板，不要改为自己的数据库或其他模板。其他模板的数据库名称和属性可能不一致，会导致同步失败。

## 4. 连接微信读书账号 (API Key 或扫码登录)

模板连接完成后，继续绑定微信读书账号。NotionHub Pro 版支持 **API Key 登录（推荐）** 与 **微信扫码登录** 两种方式，两者还可以同时并存。

### 登录方式对比与选择

| 登录方式                | 凭据有效期             | 支持的数据范围                                             | 推荐场景                            |
| :------------------ | :---------------- | :-------------------------------------------------- | :------------------------------ |
| **API Key 登录 (推荐)** | **长期有效**，无需重复续期   | 书架、书籍元数据、单书进度与时长、划线高亮、个人想法/书评、年度/月度阅读统计、阅读热力图       | 绝大多数日常阅读同步用户，追求后台定时静默同步、不希望频繁扫码 |
| **微信扫码登录**          | 网页凭据有有效期，失效后需重新扫码 | 上述全部核心数据 + **我的书单/收藏书单** + **微信公众号文章收藏** + **折角书签** | 需要同步书单或公众号文章的深度用户               |
| **双模并存 (两者都连)**     | 核心长效，扩展增强         | 全部数据完整同步，核心流走 API Key 保障长效稳定，扩展流走扫码凭据               | 既要长效免维护，又要书单和公众号同步的用户           |

***

### 方式一：API Key 登录 (推荐)

API Key 是微信读书官方开放的网关凭据，一次配置即可长期静默运行，不会因网页凭据过期而中断同步。

1. 在配置页找到「微信读书」账号区域，点击登录按钮打开连接弹窗。
2. 弹窗默认选中 **「API Key 登录」**。
3. 点击输入框右上方的 **[获取官方 Key](https://weread.qq.com/r/weread-skills)**，或直接在浏览器中打开 `https://weread.qq.com/r/weread-skills`。
4. 登录你的微信读书账号，点击「复制 Key」获取你的官方 API Key（通常以 `wrk-` 开头）。
5. 将 API Key 粘贴到弹窗输入框中，点击「验证并连接」。
6. 验证成功后，弹窗自动关闭，账号状态显示为已连接。

![微信读书 API Key 获取示例](https://cdn.notionhub.app/notionhub/weread2notion-open-source/weread-api-key-guide.webp)

***

### 方式二：微信扫码登录

如果需要同步**书单**或**公众号文章**，可以使用微信扫码登录。

1. 在配置页点击登录按钮打开连接弹窗。
2. 在弹窗顶部切换到 **「微信扫码登录」** 标签页。
3. 页面会自动生成登录二维码，使用手机微信扫描该二维码。
4. 在手机微信上确认登录。
5. 返回插件页面，等待提示连接成功。

::: tip 网页凭据时效提示
网页扫码登录凭据由于微信安全机制可能会在数天至数周后过期。若后续同步提示凭据失效，只需重新打开插件扫码一次即可。如需长期无需维护的后台定时同步，建议优先使用 **API Key 登录**。
:::

***

### 进阶：双模并存（长效免维护 + 书单/公众号同步）

你可以先输入 **API Key** 完成绑定，随后再次打开登录弹窗，切换到 **「微信扫码登录」** 扫码一次。

系统会自动识别为双模状态：

- 核心的书籍、阅读时长、划线笔记、热力图始终使用稳定的 API Key 执行，绝不因扫码过期中断；
- 扩展的书单和公众号文章自动调用扫码直连凭据；即使后续直连凭据过期，扩展流也会平滑跳过并发出提示，不影响核心阅读数据的正常归档。

## 5. 连接 GitHub

NotionHub 使用 GitHub Actions 执行同步任务。第一次开始同步时，需要先完成 GitHub 授权。

1. 点击配置页底部的「开始同步」。
2. 出现 GitHub 授权提示后，点击「登录 GitHub」。
3. 已有 GitHub 账号时，直接登录并完成授权。
4. 没有 GitHub 账号时，可以选择使用 Google 或 Apple 账号登录 GitHub。
5. 页面显示「GitHub 授权成功」后，关闭授权页面并返回 NotionHub 插件。

返回配置页后，插件会自动完成 GitHub Runner 的连接和同步配置。首次初始化可能需要等待一小段时间。

## 6. 开始第一次同步

确认 Notion、微信读书和 GitHub 都已经连接后：

1. 点击「开始同步微信读书」。
2. 等待插件成功创建 GitHub Actions 任务。
3. 点击运行记录，打开 GitHub Actions 页面。
4. 在任务详情中可以查看当前状态和正在执行的步骤。

微信读书任务会依次同步书籍、阅读时长、书单、公众号收藏等已启用内容。第一次同步的数据较多，通常会比后续增量同步耗时更长。任务进入 GitHub Actions 后，即使关闭插件页面，同步也会继续运行。

## 7. 在 Notion 中查看同步结果

同步完成后，可以从配置页打开微信读书 Notion 模板，检查数据是否已经写入。

模板首页会展示阅读概览和阅读热力图。进入书籍数据库后，可以继续查看：

- 书架、读过和做过笔记的书籍。
- 单本书的作者、分类、阅读进度和阅读时长。
- 按章节整理的划线和想法。
- 最近阅读、年度统计和阅读热力图。

如果 GitHub Actions 已经成功，但 Notion 暂时还没有显示全部内容，可以等待一两分钟后刷新 Notion 页面。

## 8. 激活 Pro 版

未激活用户可以先使用免费体验次数。需要继续同步或使用自动同步、通知等完整功能时，可以购买并输入 Pro 激活码。

1. 在微信读书 Pro 版配置页打开激活入口。
2. 按页面提示购买激活码。
3. 将收到的激活码粘贴到输入框中。
4. 点击「激活」。
5. 页面提示激活成功，并显示 Pro 状态后，即可继续同步。

激活码属于个人授权信息，请不要发布到截图、公开文档或聊天记录中。

## 常见问题

### 为什么配置了 API Key 之后，书单和公众号文章没有同步？

微信读书官方开放网关目前开放了书架图书、阅读时长、划线高亮与个人想法等核心数据接口，但**尚未开放「书单」与「公众号文章」端点**。

如果你需要同步书单或公众号文章，只需在登录弹窗中切换到「微信扫码登录」补充扫码授权一次即可。系统会自动启用「双模并存」：核心数据由 API Key 保障长期免维护，扩展数据自动由扫码凭据同步。

### API Key 模式是如何进行增量同步的？

API Key 模式下，系统通过比对微信读书返回的阅读更新时间戳（`readUpdateTime`）、读完状态标记（`finishReading`）、书架分类（`archive`）以及笔记修改时间（`Sort`）来精准识别变动书籍。

只有发生变动的书籍才会进一步拉取单书详细进度并写入 Notion，既保证了变动能被立即同步，又避免了频繁请求导致的接口限频或同步超时。

### 用 iPhone 快捷指令触发同步

完成上述配置后，可以使用 iOS 快捷指令随时手动触发微信读书同步，也可以配合自动化实现关闭微信读书 App 后自动同步，详见 [iOS 快捷指令教程](https://www.notionhub.app/docs/ios-shortcuts.md)。

### Notion 授权后仍然显示未连接

返回插件刷新页面后重试。如果仍然未连接，请重新进入 Notion 授权流程，并确认授权的是刚才复制模板所在的工作区。

### 微信读书二维码无法使用

先确认二维码没有过期，再点击刷新二维码重新扫描。扫码后还需要在手机上完成确认。

### 点击同步后没有立即看到数据

先打开运行记录，检查 GitHub Actions 是否仍在执行。第一次同步的数据量通常较大，请等待任务完成后再刷新 Notion。

### GitHub Actions 执行失败

打开失败的运行记录，展开带有错误标记的步骤查看原因。仍无法解决时，可以前往[常见问题](https://www.notionhub.app/docs/faq.md)或[联系支持](https://www.notionhub.app/docs/support.md)。
