Obsidian 图床实践笔记：从 PicGo 到 obsidian-image-upload-toolkit

L小智
3 阅读10分钟

Obsidian 图床实践笔记：从 PicGo 到 obsidian-image-upload-toolkit

obsidian-image-upload-toolkit

🎯 核心要点

  • 传统方案局限：PicGo + image auto upload 适合实时上传，但不适合批量处理和静态站点发布
  • 新方案优势：obsidian-image-upload-toolkit 提供一键批量上传、保留原文件、支持9种图床
  • 核心价值：实现"一次写作，多处发布"的工作流
  • 图床选择：腾讯云 COS（国内）、Cloudflare R2（国际）、GitHub（免费）

📚 正文

背景与问题

在 Obsidian 中文论坛的热门讨论《在Obsidian中使用图床实现"一次上传、多次搬运"》中，社区用户分享的主流方案是：PicGo + image auto upload 插件。

这个方案的核心逻辑是：

  • 在 Obsidian 中插入图片时，插件自动上传到图床
  • 图片链接实时替换为网络地址
  • 实现了"插入即上传"的实时体验

但这个方案存在几个明显问题：

  1. 修改原文件：直接修改本地 markdown 文件，一旦上传错误难以回滚
  2. 无法批量处理：需要逐个上传，效率低下
  3. 图床绑定：切换图床需要重新配置所有图片
  4. 平台兼容性：SM.MS 等免费图床在国内平台（如微信公众号）无法加载
  5. 静态站点不友好：无法配合 Hugo、Jekyll 等静态站点生成器使用

在探索更优解决方案的过程中，我发现了一个更加现代化的插件：obsidian-image-upload-toolkit。

一、obsidian-image-upload-toolkit 是什么？

1.1 核心设计理念

obsidian-image-upload-toolkit 是一个专为静态站点发布设计的 Obsidian 插件，它的核心设计理念与传统方案完全不同：

传统方案（插入时上传）：

写作 → 插入图片 → 自动上传 → 实时替换链接 → 继续写作

新方案（发布时上传）：

写作 → 插入本地图片 → 完成写作 → 一键上传所有图片 → 复制更新后的 markdown → 发布到静态站点

1.2 关键特性

特性说明
一键批量上传通过命令面板一次性上传所有本地图片
保留原文件默认不修改本地 markdown，只复制更新后的内容到剪贴板
可选原地替换如果需要，也可以选择直接修改原文件
支持9种图床Imgur、阿里云 OSS、ImageKit、Amazon S3、腾讯云 COS、七牛云、GitHub、Cloudflare R2、Backblaze B2
自定义路径可配置上传后的目标路径
灵活附件位置支持多种附件保存位置配置

1.3 项目活跃度

  • GitHub：addozhang/obsidian-image-upload-toolkit
  • 最新版本：1.3.0（2025年1月31日）
  • 更新频率：从2025年4月开始，已发布9个版本，近期频繁更新
  • 最新功能：支持 Backblaze B2、网络图片上传、相对路径解析修复

二、支持的图床服务

2.1 国内用户推荐

腾讯云 COS（首选）

优势：

  • 国内访问速度快
  • 免费额度：50GB 存储
  • 费用低：超出后包年约 9-9.8 元/年
  • 微信公众号等国内平台兼容性好

配置参数：

Secret ID: 从腾讯云 CAM 控制台获取
Secret Key: 从腾讯云 CAM 控制台获取
Region: ap-guangzhou（或其他地域）
Bucket Name: 你的存储桶名称
Target Path: assets/images/（自定义路径）
Custom Domain: img.yourdomain.com（可选，推荐配置）
七牛云 Kodo

优势：

  • 老牌图床服务，稳定可靠
  • 免费额度：10GB 存储
  • 提供 CDN 加速
阿里云 OSS

优势：

  • 阿里生态整合好
  • 国内访问速度快
  • 提供免费额度

2.2 国际用户推荐

Cloudflare R2（新兴选择）

优势：

  • 零流量费用：这是最大的优势
  • S3 兼容 API
  • 全球 CDN 加速
  • 提供免费 R2.dev 域名

配置参数：

Access Key ID: 从 R2 控制台创建 API Token
Secret Access Key: 从 R2 控制台创建 API Token
Endpoint: https://<account-id>.r2.cloudflarestorage.com
Bucket Name: 你的存储桶名称
Target Path: images/（自定义路径）
Custom Domain: https://<random-id>.<account-id>.r2.dev（免费）或自定义域名
Amazon S3

优势：

  • 全球最成熟的对象存储
  • 高可用性和可靠性
  • 丰富的生态系统
Backblaze B2（最新支持）

优势：

  • 极低的价格：$0.005/GB/月
  • 全球分发
  • 无流量费用（通过 Cloudflare）

2.3 免费方案

GitHub 仓库

优势：

  • 完全免费
  • 版本控制
  • 适合开源项目

缺点：

  • 国内访问速度慢
  • 有文件大小限制（100MB）
  • 访问频率限制
Imgur

优势：

  • 简单易用
  • 免费账户有足够配额

缺点：

  • 国内无法访问
  • 有每日上传限制
  • 不适合正式使用

三、安装与配置

3.1 安装插件

方法一：通过 Obsidian 插件市场

  1. 打开 Obsidian 设置 → 第三方插件
  2. 关闭"安全模式"
  3. 点击"浏览"按钮
  4. 搜索 "image upload toolkit"
  5. 点击"安装"
  6. 安装后点击"启用"

方法二：手动安装

  1. 访问 GitHub Releases 页面
  2. 下载最新版本的 main.js、manifest.json、styles.css
  3. 在 Obsidian vault 中创建 .obsidian/plugins/obsidian-image-upload-toolkit 目录
  4. 将下载的文件复制到该目录
  5. 重启 Obsidian

3.2 配置图床（以腾讯云 COS 为例）

第一步：创建腾讯云 COS 存储桶
  1. 登录腾讯云控制台
  2. 进入"云产品" → "基础存储服务" → "对象存储"
  3. 点击"创建存储桶"
  4. 配置参数：
    • 名称：obsidian-images（自定义）
    • 地域：选择离你最近的区域（如 ap-guangzhou）
    • 访问权限：公有读私有写
  5. 点击"确定"创建
第二步：创建文件夹
  1. 进入刚创建的存储桶
  2. 点击"新建文件夹"
  3. 创建文件夹：assets/images/（或自定义路径）
第三步：配置 API 密钥
  1. 访问腾讯云 CAM 控制台
  2. 进入"访问密钥" → "API 密钥管理"
  3. 点击"新建密钥"
  4. 复制 SecretId 和 SecretKey
第四步：配置插件
  1. 在 Obsidian 中打开插件设置
  2. 找到 "obsidian-image-upload-toolkit"
  3. 配置参数： 
    Image Store: TencentCloud COS
Secret ID: [粘贴你的 Secret ID]
Secret Key: [粘贴你的 Secret Key]
Region: ap-guangzhou
Bucket Name: obsidian-images
Target Path: assets/images/
Custom Domain: img.yourdomain.com（可选）
  4. 保存配置

3.3 测试配置

  1. 在 Obsidian 中创建一个测试笔记
  2. 插入一张本地图片（使用 ![[image.png]] 或 ![alt](path/to/image.png)）
  3. 打开命令面板（Ctrl/Cmd + P）
  4. 输入 "publish page" 并选择命令
  5. 等待上传完成
  6. 检查剪贴板，应该包含更新后的 markdown
  7. 在腾讯云 COS 控制台检查图片是否上传成功

四、与其他方案对比

4.1 设计理念对比

obsidian-image-upload-toolkit：发布时上传

核心理念：

  • 写作时不关心图床，专注内容创作
  • 发布时批量上传，一次性处理所有图片
  • 保留本地引用，提供可选的原地替换

设计哲学：

写作阶段：本地图片，快速预览，零网络依赖
发布阶段：批量上传，更新链接，一键完成

优势：

  • ✅ 写作体验流畅，无网络延迟
  • ✅ 批量处理效率高
  • ✅ 原文件安全（默认不修改）
  • ✅ 适合静态站点工作流

劣势：

  • ❌ 需要手动触发上传
  • ❌ 无法实时预览网络图片
  • ❌ 发布前无法验证图片链接
PicGo + image auto upload：插入时上传

核心理念：

  • 插入图片时立即上传
  • 实时替换为网络链接
  • 即时预览，所见即所得

设计哲学：

插入图片：立即上传，替换链接，实时生效

优势：

  • ✅ 实时上传，自动替换
  • ✅ 即时预览网络图片
  • ✅ 操作简单，学习成本低
  • ✅ 适合日常写作

劣势：

  • ❌ 逐个上传，效率低
  • ❌ 直接修改原文件
  • ❌ 依赖网络，网络差时体验差
  • ❌ 不适合批量处理
Typora + PicGo：编辑器集成上传

核心理念：

  • 利用 Typora 的 Markdown 编辑器功能
  • 通过 PicGo 实现图片上传
  • 编辑器级别的集成

设计哲学：

编辑器：Typora 提供 Markdown 编辑和预览
图床：PicGo 负责图片上传
集成：通过配置实现自动上传

优势：

  • ✅ Typora 编辑体验优秀
  • ✅ Markdown 预览功能强大
  • ✅ 适合 Mac 用户（Obsidian 插件兼容性问题）

劣势：

  • ❌ 需要额外安装 Typora
  • ❌ 与 Obsidian 生态分离
  • ❌ 无法直接使用 Obsidian 的其他功能

4.2 功能特性深度对比

上传机制
方案上传触发方式上传单位进度显示失败处理
obsidian-image-upload-toolkit手动命令触发批量（当前笔记所有图片）进度弹窗单独失败不影响其他图片
PicGo + image auto upload插入图片时自动触发单张（逐个上传）无进度显示需要手动重试
Typora + PicGo插入图片时自动触发单张（逐个上传）PicGo 界面显示需要手动重试

obsidian-image-upload-toolkit 的优势：

  • 批量上传效率更高
  • 进度弹窗提供清晰反馈
  • 单个图片失败不影响整体流程
  • 支持网络图片上传（1.2.0 版本新增）
文件修改策略
方案原文件修改修改时机可逆性安全性
obsidian-image-upload-toolkit可选（默认不修改）发布时可逆（不修改原文件）高
PicGo + image auto upload强制修改插入时不可逆（除非使用版本控制）中
Typora + PicGo强制修改插入时不可逆（除非使用版本控制）中

obsidian-image-upload-toolkit 的优势：

  • 默认不修改原文件，安全性高
  • 支持可选的原地替换模式
  • 通过剪贴板提供更新后的内容
  • 便于版本控制和回滚
图床支持
方案图床数量图床类型扩展性配置复杂度
obsidian-image-upload-toolkit9种国内外主流云存储高（支持自定义图床）中
PicGo + image auto upload20+种PicGo 支持的所有图床高（PicGo 生态丰富）低
Typora + PicGo20+种PicGo 支持的所有图床高（PicGo 生态丰富）低

详细图床对比：

obsidian-image-upload-toolkit 支持：

  • 国内：腾讯云 COS、阿里云 OSS、七牛云 Kodo
  • 国际：Amazon S3、Cloudflare R2、Backblaze B2、ImageKit
  • 免费：GitHub、Imgur

PicGo 支持的额外图床：

  • 国内：又拍云、SM.MS
  • 国际：MinIO、Upyun
  • 自定义：支持自定义 API

优势对比：

  • PicGo 图床数量更多，生态更丰富
  • obsidian-image-upload-toolkit 支持的图床更现代化（如 Cloudflare R2、Backblaze B2）
  • obsidian-image-upload-toolkit 的配置更规范，文档更完善
路径管理
方案本地路径解析远程路径配置路径模板相对路径支持
obsidian-image-upload-toolkit完善（1.2.1 版本修复）灵活（支持自定义路径）✅ 支持（{{year}}/{{month}} 等）✅ 完善支持
PicGo + image auto upload一般基础❌ 不支持⚠️ 部分支持
Typora + PicGo依赖 Typora依赖 PicGo❌ 不支持⚠️ 部分支持

obsidian-image-upload-toolkit 的路径模板示例：

Target Path: images/{{year}}/{{month}}/
上传结果：https://img.example.com/images/2026/02/screenshot.png

Target Path: {{noteName}}/
上传结果：https://img.example.com/my-article/screenshot.png

Target Path: docs/{{year}}/{{month}}/{{noteName}}/
上传结果：https://img.example.com/docs/2026/02/my-article/screenshot.png

4.3 总结对比表

维度obsidian-image-upload-toolkitPicGo + image auto uploadTypora + PicGo
设计理念发布时上传插入时上传编辑器集成上传
上传方式批量一键逐个自动逐个自动
原文件修改可选（默认不修改）强制修改强制修改
图床数量9种20+种20+种
批量处理✅ 支持❌ 不支持❌ 不支持
网络图片上传✅ 支持❌ 不支持❌ 不支持
路径模板✅ 支持❌ 不支持❌ 不支持
写作体验流畅（本地图片）有延迟（网络图片）流畅（Typora 编辑器）
发布体验优秀（批量处理）一般（需手动复制）一般（需手动复制）
静态站点✅✅✅ 完美支持❌ 一般❌ 一般
多平台分发✅✅✅ 完美支持✅✅ 可行✅ 可行
日常写作✅✅ 可行✅✅✅ 完美支持✅✅✅ 完美支持
技术文档✅✅✅ 完美支持✅✅ 可行❌ 不适合
团队协作✅✅✅ 完美支持✅✅ 可行❌ 不适合
插件费用免费免费Typora 收费（¥89）
学习成本中低低
适用人群发布型用户写作型用户Markdown 爱好者
推荐指数⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐

📎 参考资料

avatar
文章
阅读
粉丝