WeChat Collector — Obsidian Plugin

将微信公众号文章同步到 Obsidian vault，自动转换为 Markdown，按日期归档，图片下载到本地。

本插件是 WeChat Obsidian Sync 项目的一部分，需要配合后端服务器使用。

工作原理

微信公众号文章 → 微信小程序提交 → 后端服务器抓取/转换 → 本插件轮询拉取 → Obsidian vault

1. 用户在微信中阅读公众号文章，复制链接
2. 通过微信小程序将链接提交到后端服务器
3. 服务器抓取文章 HTML、解析正文、转换为 Markdown、下载图片
4. 本插件定时轮询服务器，增量拉取新文章并保存到 vault

功能特性

• ✅ 增量同步 — 基于时间戳轮询，只拉取新文章
• ✅ 按日期归档 — 文章自动按 YYYY-MM 归档到指定目录
• ✅ 图片本地化 — 微信 CDN 图片会过期，插件自动下载到 vault 本地
• ✅ 跨平台 — 同时支持桌面端和移动端（使用 requestUrl API）
• ✅ 自动同步 — 可配置轮询间隔，启动时自动开始
• ✅ 手动同步 — 状态栏点击、Ribbon 图标、命令面板均可触发

技术栈

• 语言: TypeScript
• 构建: esbuild（Obsidian 官方推荐）
• API: Obsidian API（requestUrl, vault.create, vault.createBinary）

目录结构

src/
├── main.ts          # 插件入口
├── settings.ts      # 设置面板
├── syncService.ts   # 同步服务（定时轮询 + 增量拉取）
├── apiClient.ts     # 后端 API 客户端
├── fileManager.ts   # 文件创建与图片下载
├── types.ts         # 类型定义
└── logger.ts        # 日志工具

安装

前置条件

需要部署 后端服务器 并获取 API Token。

手动安装

1. 从 Releases 下载最新版本
2. 将 main.js、manifest.json、styles.css 复制到 vault 的 .obsidian/plugins/wechat-collector/ 目录
3. 在 Obsidian 设置 → 第三方插件中启用「WeChat Collector」
4. 配置服务器地址与 API Token

# 或从源码构建
git clone https://github.com/Lizhen0628/obsidian-wechat-sync.git
cd obsidian-wechat-sync
npm install
npm run build

VAULT="<你的 vault 路径>"
mkdir -p "$VAULT/.obsidian/plugins/wechat-collector"
cp main.js manifest.json styles.css "$VAULT/.obsidian/plugins/wechat-collector/"

插件设置

设置项	说明	默认值
服务器地址	后端服务器的根 URL	—
API Token	与服务器一致的鉴权密钥	—
自动同步	启动时自动按间隔轮询	开启
轮询间隔	单位：分钟，0 则禁用	5
保存目录	文章保存的基础目录	Inbox/WeChat
日期归档格式	子目录的日期格式	YYYY-MM
下载图片	将文章图片下载到 vault 本地	开启
图片目录名	图片存储的子目录名	attachments

归档结构

Inbox/
└── WeChat/
    └── 2024-01/
        ├── 文章标题.md
        └── attachments/
            ├── img_001.png
            └── img_002.jpg

开发

npm install
npm run dev     # esbuild watch 模式
npm run build   # 类型检查 + 生产构建

建议使用 Hot-Reload 插件实现开发时自动重载，并在测试 vault（非主力 vault）中开发。

验证图片 URL 替换

npx tsx scripts/test-replace.ts

发布新版本

使用 npm version 命令（自动同步 package.json、manifest.json、versions.json，并创建无 v 前缀的 tag）：

# 1. bump 版本号（自动更新三个文件 + 创建纯版本号 tag，如 0.2.0 而非 v0.2.0）
npm version patch    # 0.1.2 → 0.1.3
npm version minor    # 0.1.2 → 0.2.0
npm version major    # 0.1.2 → 1.0.0

# 2. 推送代码和标签（会自动触发 GitHub Actions 构建 + 创建草稿 Release）
git push && git push --tags

⚠️ Obsidian 要求 Release tag 不带 v 前缀（0.2.0 而非 v0.2.0），postversion 钩子会自动处理。

推送标签后，GitHub Actions 会自动构建并创建草稿 Release（包含 main.js、manifest.json、styles.css）。前往 Releases 审核后手动发布。

相关项目

• wechat-obsidian-sync — 完整项目（后端服务器 + 小程序 + 插件）
• wechat-clipper — 微信小程序「收藏助手」

提交到 Obsidian 社区插件市场

1. 前往 community.obsidian.md 登录并关联 GitHub 账号
2. 进入 Plugins → New plugin，填写仓库地址 Lizhen0628/obsidian-wechat-sync
3. 同意开发者政策并提交
4. 通过自动审核后，插件将出现在 Obsidian 社区市场中

首次提交后，后续版本更新无需再次提交——Obsidian 会自动从 GitHub Release 拉取新版本。

License

MIT