跳转到内容

编写你的第一个 Connector

这一页从一个空目录开始,写一个能把外部视频地址解析为可播放流的 Connector,并在本地调试后装进 Obsidian。全程只需要 JavaScript 和一个可访问的接口地址,不需要修改插件源码。

TIP

可以让 AI 帮你写 Connector 的接口很小。把这一页和 API 参考 一起交给 AI,说明你要接入的站点与取流方式,让它生成 main.js,再用本地调试器验证即可。

一个 Connector 就是一个目录、两个文件:

my-connector/
├── manifest.json
└── main.js

目录名就是 Connector 的 id,必须与 manifest.json 里的 id 一致。

{
"id": "my-connector",
"name": "My Connector",
"version": "1.0.0",
"apiVersion": "0.4",
"type": "video-source",
"description": "解析 watch.example.com 的视频地址",
"author": "your-name",
"homepage": "https://github.com/you/my-connector"
}
字段必填说明
id是唯一标识,必须与目录名一致;只允许小写字母、数字、-、_
name是展示名
version是Connector 自己的版本号
apiVersion是目标契约版本。宿主当前为 0.4,只看第一段数字是否一致
type是video-source、audio-source 或 agent-session
description / author / homepage否展示与溯源信息

main.js 是单文件 CommonJS,导出一个 create(ctx) 工厂函数:

module.exports = {
create(ctx) {
return {
// 宿主会对每个外部地址同步调用它,必须廉价
match(url) {
return /^https?:\/\/watch\.example\.com\/video\//i.test(url);
},
async resolve(url, onProgress) {
onProgress?.('正在解析播放地址…');
// 走宿主通道请求,不受浏览器 CORS 限制
const resp = await ctx.request({
url: `https://api.example.com/resolve?url=${encodeURIComponent(url)}`,
});
if (resp.status !== 200) {
throw new Error(`解析接口返回 HTTP ${resp.status}`);
}
const data = resp.json;
if (!data.playUrl) {
throw new Error(data.message || '解析结果里没有 playUrl');
}
return {
url: data.playUrl,
urlType: 'm3u8-list',
mediaType: 'hls',
coverUrl: data.cover,
mediaInfo: [{
url: data.playUrl,
width: data.width ?? 0,
height: data.height ?? 0,
resolution: data.quality ?? '自动',
}],
};
},
// 可选:重新加载或停用插件时清理定时器、连接等
dispose() {},
};
},
};

几个关键点:

  • match 要保守:它决定这个地址是否完全交给你的 Connector。不要匹配所有 http(s) 地址,否则会把普通网页条目也劫持成视频。匹配后同步返回,不要在里面发请求。
  • resolve 失败就抛错:宿主不会回落到内置解析,也不会再问其他 Connector;错误信息会直接展示给用户并写入日志。不要用「返回空流」掩盖失败。
  • 返回的 url 要能被再次解析:切换分集或地址过期时,宿主会拿原始地址再次调用 resolve,所以实现要可重复调用,不要在实例上累积一次性状态。
  • HLS 不要用 resolution: '原画':「原画」在播放器里有特殊含义,会按直链处理;HLS 用 自动 或清晰度名称即可。

完整字段说明见 Connector API 参考。

不用打开 Obsidian,直接用 SDK 的 mock 跑一遍「加载 → match → resolve」:

Terminal window
npx sync-vault-connector-mock ./my-connector "https://watch.example.com/video/123"

mock 的 manifest 校验、main.js 求值方式与宿主一致,能提前发现字段缺失、ESM 语法、require 之类的问题。差异只有两处:ctx.request 走 Node 的 fetch(没有 CORS 限制),ctx.dir 是本地绝对路径。

如果报错,先修到命令能打印出解析结果,再装进 Obsidian。

在仪表盘工作台添加 Connector 管理 卡片,点 安装:

  • 粘贴 manifest.json 的地址(GitHub 页面链接会自动转成 raw),或
  • 点 选择文件,同时选中 manifest.json 与 main.js。

也可以把整个目录拷到 <vault>/.obsidian/plugins/sync-vault-ce/connectors/my-connector/,再执行命令 重新加载用户 Connectors。

然后在笔记里用 cloudvideo 代码块写入地址:

```cloudvideo
https://watch.example.com/video/123 | 我的视频
```

切换回阅读模式即可播放。清晰度切换、播放进度、时间戳标注等能力与内置视频源一致,不需要额外适配。

需要 token、Cookie 之类的配置时,用 ctx.getSettings() 读取本 Connector 目录下的 settings.json:

const settings = await ctx.getSettings();
const token = settings?.token;
if (!token) {
throw new Error('请先在 settings.json 中配置 token');
}

用户也可以直接编辑这个文件。它是 vault 里的普通 JSON,明文存储,会随 vault 一起同步;不要把长期密钥硬编码进 main.js。

多分P、多集的视频可以返回 parts,宿主会在播放器侧栏展示选集,并在播完一集后自动续播下一集:

return {
url: current.playUrl,
urlType: 'm3u8-list',
mediaType: 'hls',
mediaInfo: [{ url: current.playUrl, width: 0, height: 0, resolution: '自动' }],
parts: [
{ name: 'P1 开场', url: 'https://watch.example.com/video/123?part=1' },
{ name: 'P2 正片', url: 'https://watch.example.com/video/123?part=2' },
],
currentPartIndex: 0,
};
  • 至少 2 项时才会展示选集。
  • 每个 parts[].url 都必须能被你的 match / resolve 正常处理——宿主切换分集时会拿它再次调用 resolve。
  • 分集在宿主内是独立条目,各自记录播放进度与标注。

把 manifest.type 改成 audio-source,方法形状完全不变。注意:

  • 音频没有分辨率,mediaInfo 每项填 width: 0、height: 0,resolution 用 原画 或展示名。
  • 音频地址过期后宿主不会自动重取,请返回时效足够长的地址。
  • 返回 parts 时宿主按顺序连播;选集列表在播放器侧栏展示,内嵌播放器本身没有选集按钮。

可以直接参考 SDK 里的 web-audio(直链 / HLS)和 rss-podcast(RSS 播客)示例。

  • 不用 Node / Electron API:fs、path、http 都不可用;需要随机数或摘要时用 Web 标准的 crypto.subtle。
  • 文件读写只走 ctx:vault 内用 getSettings / saveSettings;vault 外的本机路径只有 agent-session 可以用,且只能走桌面端的 ctx.desktop。
  • 依赖防盗链头的地址:proxy: true 的本地代理只在桌面端有效,移动端会退化成直连、headers 不生效。请主动判断并报错,而不是让用户看到莫名其妙的播放失败:
if (ctx.platform.isMobile) {
throw new Error('该地址需要防盗链头,暂仅支持桌面端播放');
}
  • 直链视频需要跨域:播放器以 <video crossorigin="anonymous"> 直接加载直链,源站必须返回 Access-Control-Allow-Origin,否则会以 MEDIA_ELEMENT_ERROR: Format error 失败。桌面端可以用 proxy: true 让本地代理补上跨域头;移动端没有代理。

把目录推到 GitHub(只带 manifest.json 与 main.js,不要带 settings.json 和 .disabled),别人在安装框里粘贴 manifest.json 的 GitHub 页面链接即可。后续更新时保持 id 不变、递增 version,同 id 覆盖安装会保留用户的 settings.json。

现象常见原因
加载失败:manifest.id(...) 必须与目录名(...)一致目录名和 id 不一致
加载失败:提示不能用 ESM 的 import / export用了 ESM 语法,改成 module.exports
加载失败:main.js 必须导出 create(ctx)忘了导出工厂函数
播放器提示 Unsupported file type没有 Connector 命中,检查 match 是否过窄
播放 403 / Format error防盗链头或跨域问题,检查 proxy / headers 与移动端差异
解析失败但不知道哪一步在日志里搜索 [connector.my-connector]

更多字段与生命周期细节见 Connector API 参考。