核心用法
weread-import 是一款专为微信读书（WeRead）用户设计的笔记同步 CLI 工具，核心功能是将云端书籍、划线及笔记导出为结构化 Markdown 文件。推荐通过 scripts/run.sh 执行，首次运行自动安装 Node.js 依赖并启动 Chrome 远程调试（CDP）会话。
主要执行模式：
- API 模式（
--mode api）：完整获取 author、bookId、highlightCount 等元数据，推荐日常使用 - 浏览器 Cookie 提取（
--cookie-from browser）：利用 Chrome CDP 自动获取/刷新登录态，避免硬编码 Cookie 过期问题 - 手动 Cookie（
--cookie或WEREAD_COOKIE）：无浏览器环境时的降级方案
典型工作流：
1. 单书导入：--book "书名"
2. 全库同步：--all
3. 模板变更后重渲染：加 --force 跳过增量检查
4. 验证阶段：先输出到临时目录，确认无误后再写入正式目录
显著优点
- 智能增量机制：自动检测书籍更新状态，仅同步变更内容，大幅节省 API 调用与本地 I/O
- 登录态自动维护：通过 CDP 实时监控浏览器 Cookie，过期自动刷新，无需人工干预
- 数据完整性保障：删除的条目归档至
## 已删除章节而非永久丢失，支持回溯 - 元数据分离设计：书籍信息存于 YAML frontmatter，正文纯净可读，完美适配 Obsidian 等双向链接工具
- 防 CDN 缓存策略：API 请求自动附加时间戳，减少鉴权失败
潜在缺点与局限性
- 环境依赖较重：需 Node.js + Playwright + Chrome，首次安装耗时较长
- 浏览器强依赖：
--cookie-from browser模式要求 Chrome 146+ 及特定启动参数，CDP 端口冲突时需手动排查 - 登录态单点故障：CDP 未运行或微信读书网页版登出时，命令以非零码退出，需用户重新登录
- 定时任务限制：自动化场景下禁止加
--force、禁止硬编码 Cookie，灵活性受限 - 平台局限：仅支持微信读书，无其他阅读平台适配计划
适合人群
- Obsidian/Logseq 等本地优先笔记软件的深度用户
- 需要定期归档、二次加工读书笔记的学术/知识工作者
- 追求「数据自主可控」、不愿笔记仅存于云端的隐私敏感型用户
- 具备基础 CLI 操作能力、能接受 Node.js 环境配置的进阶用户
常规风险
| 风险类别 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| **鉴权失效** | CDP 获取的 Cookie 过期或微信读书网页版登出 | 运行前确认浏览器已登录；失败时按提示重新扫码 |
| **数据覆盖** | `--force` 误用导致自定义编辑内容丢失 | 强制重渲染前备份；利用 Git 管理 Reading 目录 |
| **环境漂移** | Node/Playwright/Chrome 版本不兼容 | 锁定 `package.json` 版本；使用提供的 `run.sh` 封装 |
| **隐私泄露** | Cookie 被写入日志或环境变量历史 | 优先使用 `--cookie-from browser`；避免 `export WEREAD_COOKIE` |
| **增量误判** | 书籍元数据变更未触发更新 | 定期（如每月）手动执行 `--force` 全量刷新 |
来源可信度
开源项目托管于 GitHub（gnixner/weread-import），代码可审计，无闭源服务端依赖。