obsidian-qiniuimage

• chenxuan

在 Obsidian 里粘贴或拖入图片时，自动上传到七牛云对象存储，并在笔记里插入 CDN 链接，而不是把图片存进本地附件目录。

Paste or drop an image in Obsidian and it is uploaded to Qiniu object storage, with the CDN link inserted into the note instead of a local attachment.

作用

• 粘贴截图 → 自动上传到图床 → 笔记里只留一个 ![](http://your-cdn/xxx.png) 链接
• 拖入图片文件同样处理
• 上传中显示占位文字，上传完成后原地替换成链接
• 上传失败时自动退回 Obsidian 的默认行为（存到库里），图片不会丢
• 支持两种上传方式：直连七牛云，或者转发给自建的 qiniuserver

安装

从 release 安装

1. 到 release 页面 下载 main.js、manifest.json、styles.css

2. 在库目录下新建文件夹 .obsidian/plugins/qiniu-image/，把三个文件放进去

3. 重启 Obsidian，在 设置 → 第三方插件 里启用 Qiniu Image

从源码编译

git clone https://github.com/chenxuan520/obsidian-qiniuimage
cd obsidian-qiniuimage
npm install
npm run build

编译产物 main.js 和 manifest.json、styles.css 一起复制到 .obsidian/plugins/qiniu-image/ 即可。

参数说明

打开 设置 → Qiniu Image，填入下面的参数，最后点 Run test 验证。

参数	说明
Upload mode	Direct to Qiniu 直连七牛；Relay through qiniuserver 转发给自建服务
Access key / Secret key	七牛云密钥，在这里获取
Bucket	存储空间名字，在这里获取
Region	存储区域，选 Auto detect 会自动向七牛查询
Custom upload host	可选，私有云或代理时覆盖上面的区域
CDN domain	绑定的加速域名，例如 http://cdn.example.com
Upload path	空间内的路径前缀，例如 test，留空表示根目录
File name template	文件名模板，见下
URL suffix	追加到链接后面，例如 ?imageslim 走七牛的图片处理
Server URL / Server password	只在转发模式下使用，对应 qiniuserver 的地址和 host.password

文件名模板

和 qiniuserver 的 file_name 保持一致：

占位符	含义
%d	时间戳，格式 YYYYMMDDHHmmss
%f	原文件名（空格会替换成下划线）
%r	6 位随机字符串
%e	扩展名，例如 .png

默认 %d%f，即 20260830170509image.png。留空表示保持原文件名。

其他选项

选项	默认	说明
Upload on paste	开	粘贴时上传
Upload on drop	开	拖入时上传
Upload non-image files too	关	打开后 PDF、压缩包等附件也上传
Maximum file size (MB)	20	超过大小的文件留在本地库，0 表示不限制
Save to the vault when upload fails	开	上传失败时退回本地保存，避免丢图

实现细节

• 上传凭证用 WebCrypto 的 HMAC-SHA1 在本地签发，桌面端和移动端都能用，不依赖 Node
• 上传令牌的 scope 只包含 bucket，因此是「只允许新增」，不会覆盖空间里已有的文件；万一文件名撞车（返回 614），会自动加一个随机后缀重试一次
• 网络请求走 Obsidian 的 requestUrl，不受浏览器 CORS 限制
• 密钥保存在 .obsidian/plugins/qiniu-image/data.json 里。如果你的库会同步或提交到公开仓库，请确认 .obsidian 已被忽略，或者改用转发模式，把密钥留在自建服务端

开发

npm install
npm run dev        # 监听编译
npm test           # 单元测试 + mock 服务器 + 构建产物冒烟测试
npm run typecheck

真机联调（会向真实空间上传一个 1x1 的图片并在结束时删除）：

QINIU_E2E=1 \
QINIU_ACCESS_KEY=xxx QINIU_SECRET_KEY=xxx QINIU_BUCKET=xxx \
QINIU_DOMAIN=http://cdn.example.com QINIU_UPLOAD_PATH=test QINIU_ZONE=z2 \
node --test test/e2e-qiniu.test.ts

也可以直接复用 qiniuserver 的配置文件：

QINIU_E2E=1 QINIU_CONFIG_PATH=/path/to/qiniuserver/config/config.json node --test test/e2e-qiniu.test.ts

License

MIT