我最早被图片管理恶心到，是在连续写了三个月的技术笔记之后。Typora 里贴的截图越来越多，图床目录乱成一锅粥——今天上传的图片叫image-20240115-093021.png，明天的叫image-20240116-102233.png，全部平铺在一个文件夹里。想找某篇文章对应的原图？只能靠眼睛硬翻，后来实在受不了，花了一个周末研究 PicGo 插件机制，把图片上传路径改成了「日期 + MD 文件名」的自动分类结构。现在每写一篇 Markdown，配图自动落位到图床根目录/2024/01/15/这篇文章的标题/下面，素材规整、复用方便、备份清晰。这篇文章就把这套方案的完整思路、插件代码和踩坑记录都摊开讲，适合被图片管理折腾过、想彻底理顺 Typora + PicGo 工作流的同学。
1. 方案设计与选型思路
1.1 痛点分析：图片平铺到底带来哪些麻烦
很多人的 Typora 配图流程是：Typora 里粘贴截图 → 自动上传到图床 → 本地留一个链接。PicGo 默认的上传路径往往是固定的，比如img/或者干脆就是图床根目录。短时间用没问题，一旦文章数量超过几十篇，问题就全冒出来了。
首先是定位困难。你想找某篇文章里用过的某张原图，得先回忆起大概的日期和文件名，然后在图床的图片列表里一页页翻。如果图床还开了 CDN 缓存，删改图片之后刷新不及时，写文章时配图出现旧版本，排查起来更头大。
其次是备份和迁移困难。零散平铺的图片没法按文章粒度打包，你如果想迁移某几篇文章到新博客，得手动筛选对应图片，漏一张就导致文章里的图裂掉。我自己就栽过：从 WordPress 迁到 Hugo 的时候，大量图片链接失效，回图床翻原图翻到怀疑人生。
第三是命名冲突和覆盖风险。PicGo 默认在文件名重复时可能追加时间戳或直接覆盖。多篇文章都引用同一张image-2024.png时，后期维护根本分不清谁是谁。基于这些真实的痛点，我决定给 PicGo 写一个自定义上传插件，让文件路径带足上下文信息：日期 + 源 Markdown 文件名。
1.2 为什么选 PicGo 自定义插件而非其他方案
市面上处理 Typora 图片上传的方案不少。有人用 uPic，有人用 iPic，也有人直接写脚本监听文件夹。但对我来说 PicGo 有四个不可替代的优势：跨平台支持好，Windows 和 macOS 下表现一致；插件机制成熟，官方预留了自定义插件入口，改造成本低；Typora 对 PicGo 有原生联动，设置里填好 PicGo 的监听端口就能无缝对接；社区活跃，遇到问题搜得到解决方案。
也有人会问：为什么不直接在 Typora 里设置图片保存路径规则？Typora 确实支持诸如./${filename}/之类的路径变量，但那只是把图片存到本地，最终还是要手动上传到图床。我的需求是“上传时就自动分类”，所以必须在上传环节做文章，PicGo 自定义插件正好卡在这个关键点上。
1.3 目录分类规则：为什么用「日期 + MD 文件名」
先看一下我最终采用的目录结构：
https://your-cdn.com/ └── 2024/ └── 01/ └── 15/ ├── 用-PicGo-插件实现-Typora-图片自动分类/ │ ├── image-20240115-093021.png │ └── image-20240115-113042.png └── 从零搭建个人博客的完整指南/ └── image-20240115-153012.png根目录按年分，年下面按月，月下面按日，日下面再按文章名分图片。这个结构有几个很直观的好处：按时间线回溯素材时，能快速锁定期望的月份和日期范围；按文章维度整理时，打开对应日期的文件夹就能看到当天所有文章的资源；配合图床目录 API 或对象存储生命周期规则，还能自动做冷热数据分层——比如超过一年的图片自动转低频存储。
有人可能觉得按日期分太细，做到“年/月/文章名”就够了。我实际体验下来，三层日期其实不累赘，因为云存储目录层级对访问速度几乎没有影响，而更细的层级换来了更强的归档能力。这里按个人偏好选择就好，但“日期 + MD 文件名”这个组合是必需的——两者分别对应“时间维度”和“内容维度”，交叉定位独一无二。
2. 环境准备与前置条件
2.1 Typora 图片上传设置解析
在开始写插件之前，先把 Typora 的图片上传行为搞清楚。Typora 的偏好设置里有一项「图像」，核心配置是「上传图片」的行为选项：可以设置为“上传图片”“上传图片并应用 URL”“上传图片并导出”等。我们通常选择“上传图片”，这样粘贴截图后 Typora 会自动调用配置的上传服务。
Typora 支持的上传服务包括 PicGo.app、uPic、自定义命令等。这里选 PicGo.app，配置方式很简单：上传服务选 PicGo.app，PicGo 路径填你安装的 PicGo 可执行文件位置，Typora 会自动检测 PicGo 是否在监听端口。PicGo 默认监听127.0.0.1:36677，这个端口号在后面的自定义脚本里会用到，先记下来。
还有一个容易被忽略的细节：Typora 里插入的图片如果是本地相对路径，上传时 PicGo 需要能访问到这个文件。如果文件被移动过、路径失效，上传就会失败。建议在写文章之前先把图片保存到本地一个统一目录（比如./assets），用相对路径引用，Typora 和 PicGo 两边都不会出问题。
2.2 PicGo 自定义插件开发基础
PicGo 的插件机制基于 Node.js，插件本质上就是一个 npm 包，需要实现固定的接口。PicGo 在启动时会扫描~/.picgo/目录下的配置文件，插件一般安装在~/.picgo/下的某个子目录，或者通过 npm 全局安装。新版 PicGo 支持从「插件设置」里直接搜索安装，也支持手动放置插件文件夹到指定位置。
自定义插件的最小结构如下：
custom-uploader/ ├── package.json ├── index.js └── README.mdpackage.json里要声明插件名称、版本、主入口等字段，index.js里通过module.exports导出一个对象，PicGo 会调用这个对象的upload方法。方法接收一个ctx（上下文）参数，包含待上传的文件信息、PicGo 的配置项、日志工具等，最终把上传后的 URL 数组返回给调用方。
module.exports = (ctx) => { return { uploader: 'custom-uploader', upload: async (input) => { // input 是待上传的文件信息数组 // 返回上传后的 URL 数组 } } }这个接口设计得非常轻量，核心逻辑就集中在upload方法里。接下来要做的，就是在upload方法里读取当前 Markdown 文件信息、构造目标路径、调用对象存储 SDK 完成上传。
2.3 图床与对象存储的选型建议
PicGo 支持的图床种类很多，包括腾讯云 COS、阿里云 OSS、又拍云、GitHub、七牛云等。我的方案对图床选型不敏感，因为自定义插件里调用的上传接口是统一的，你只需根据自己用的图床替换 SDK 即可。
给新手一个建议：优先选带有“目录前缀”或“自定义路径”功能的图床。比如腾讯云 COS 在上传对象时可以指定Key（即对象键），这个值通俗理解就是云端的完整路径，正好满足我们自定义路径的需求。如果用的是 GitHub 图床，就要注意仓库体积限制和加速问题，GitHub 不适合存放大量图片素材，超出 1GB 仓库限制后会很麻烦。
我个人目前主力用腾讯云 COS，原因有几点：上传/下载速度快、CDN 加速配置简单、对象键规则灵活、生命周期管理完善。但这不代表其他图床不行，关键是理解“对象键 = 云端路径”这个等价关系，后面的核心逻辑无论换什么图床都成立。
3. 核心实现：动态获取 MD 文件名与日期
3.1 方案一：通过 Typora 自定义命令传入文档路径（推荐）
PicGo 插件运行在 PicGo 进程里，本身不知道 Typora 当前打开的是哪个 Markdown 文件。要拿到 MD 文件名，得让 Typora 在调用上传时主动把文档路径传给 PicGo。最可靠的办法是绕开 PicGo.app 而使用 Typora 的「自定义命令」上传模式。
Typora 的「图像」设置里有「自定义命令」选项，它允许你指定一个命令行工具，Typora 会把待上传的图片路径列表作为参数传给这个命令。借助这个机制，我可以写一个 Node.js 脚本，它做三件事：接收 Typora 传入的图片路径列表；读取当前 Typora 文档路径（通过 Typora 注入的环境变量）；把图片路径和文档路径一起转发给 PicGo 的 CLI 上传，或直接调用图床 SDK 上传。
Typora 自定义命令的调用约定：脚本会收到图片文件的绝对路径参数，同时环境变量里会有TYPOpora_DOC_PATH（具体名称视版本而定）。实测里我是通过这种方式拿到文档路径的。这个方法最大的优点：完全可控，不依赖 PicGo 端口通信。
3.2 方案二：在 PicGo 插件内读取配置文件（备选）
如果你不想用自定义命令，也可以让 PicGo 插件去读一个“当前文档路径”的中间文件。比如在 Typora 的「偏好设置 → 导出」里，或者在编辑文章时手动运行一个快捷键脚本，把当前文档路径写到一个临时文件~/.picgo/current-md-path，PicGo 插件在上传时读取这个文件就能拿到 MD 文件名。
这个方法适合不太想改 Typora 上传设置的同学，但有个明显缺陷：如果你开了多个 Typora 窗口，或者 PicGo 上传速度很快、几次上传之间文档路径有变化，临时文件里的路径可能就是过期的。我的实测体验是：单窗口场景下基本稳定，多窗口偶尔会串台。所以最终主力方案还是推荐自定义命令。
3.3 日期格式化与目录拼接规范
拿到 MD 文件名后，下一步就是把日期拼进路径。日期用 JavaScript 的Date对象处理，格式化成YYYY/MM/DD。不要用什么复杂的日期库，原生方法几行就够：
function formatDate(date) { const y = date.getFullYear() const m = String(date.getMonth() + 1).padStart(2, '0') const d = String(date.getDate()).padStart(2, '0') return `${y}/${m}/${d}` }MD 文件名也要做一次清洗：去掉.md后缀，把空格替换成短横线（避免 URL 中出现空格被转义成%20），过滤掉 Windows/Unix 路径里的非法字符/ \ : * ? " < > |。这一步不能省，否则某些云存储 API 会直接拒绝请求，或者生成的链接里带着乱七八糟的转义符。
function cleanFileName(name) { return name .replace(/\.md$/i, '') .replace(/\s+/g, '-') .replace(/[\\/:*?"<>|]/g, '-') }拼接最终对象键时，我建议用数组join而不是字符串相加，比如[year, month, day, cleanName, imgName].filter(Boolean).join('/')，这样能避免多个斜杠叠在一起产生的路径卫生问题。
4. 实战：插件代码编写与调试
4.1 完整插件代码展示（基于腾讯云 COS）
下面这个代码是我实际在用的版本，基于腾讯云 COS SDK。先通过 Typora 自定义命令脚本拿到文档路径，写入环境变量MD_FILE_PATH，然后在 PicGo 插件里读取这个环境变量来构造云端路径。
// ~/.picgo/custom-uploader/index.js const COS = require('cos-nodejs-sdk-v5') const path = require('path') let cosInstance = null function getCOSInstance() { if (cosInstance) return cosInstance cosInstance = new COS({ SecretId: process.env.COS_SECRET_ID, SecretKey: process.env.COS_SECRET_KEY }) return cosInstance } function formatDate(date) { const y = date.getFullYear() const m = String(date.getMonth() + 1).padStart(2, '0') const d = String(date.getDate()).padStart(2, '0') return `${y}/${m}/${d}` } function cleanFileName(name) { return name .replace(/\.md$/i, '') .replace(/\s+/g, '-') .replace(/[\\/:*?"<>|]/g, '-') } module.exports = (ctx) => { return { uploader: 'custom-uploader', upload: async (input) => { const cos = getCOSInstance() const bucket = ctx.getConfig('picBed.custom-uploader.bucket') const region = ctx.getConfig('picBed.custom-uploader.region') const baseFolder = ctx.getConfig('picBed.custom-uploader.baseFolder') || '' const mdFilePath = process.env.MD_FILE_PATH || '' const mdFileName = mdFilePath ? path.basename(mdFilePath, '.md') : '未命名文档' const dateFolder = formatDate(new Date()) const cleanName = cleanFileName(mdFileName) const resultUrls = [] for (const item of input) { const imgName = path.basename(item.fileName || item.path) const objectKey = [baseFolder, dateFolder, cleanName, imgName].filter(Boolean).join('/') try { await cos.putObject({ Bucket: bucket, Region: region, Key: objectKey, Body: fs.createReadStream(item.path), ContentType: 'image/' + path.extname(imgName).slice(1) }) const url = `https://${bucket}.cos.${region}.myqcloud.com/${objectKey}` resultUrls.push(url) } catch (err) { ctx.log.error('上传失败', err) resultUrls.push('') } } return resultUrls } } }这段代码里值得注意的小细节有几个。fs模块需要在文件顶部引入，我写的时候漏过一次，导致插件一上传就报fs is not defined；ContentType一定要显式设置，否则 CDN 可能返回错误的 MIME 类型，图片在浏览器里无法预览；ctx.log.error是 PicGo 注入的日志工具，调试时非常有用，不要自己console.log，否则输出不一定能在 PicGo 的日志面板里看见。
4.2 Typora 自定义命令脚本的编写
Typora 自定义命令的入口我用的是一个 Python 脚本（Node 也可以，看个人习惯），放在~/.typora-uploader/upload.py：
#!/usr/bin/env python3 import os import subprocess import sys # Typora 会以「图片路径列表」作为参数调用此脚本 img_paths = sys.argv[1:] # 读取环境变量中的当前 Markdown 文档路径 md_path = os.environ.get('TYPORA_DOC_PATH', '') # 通过环境变量传给 PicGo 插件 env = os.environ.copy() env['MD_FILE_PATH'] = md_path # 调用 picgo 的命令行上传 cmd = ['picgo', 'upload'] + img_paths subprocess.run(cmd, env=env)然后回 Typora 设置里，把上传服务改成「自定义命令」，命令填python3 ~/.typora-uploader/upload.py。这里有个很关键的点：Typora 自定义命令模式下，传给脚本的参数是图片文件的绝对路径，而 PicGo CLI 的upload命令接受的也是图片路径列表，所以我直接在脚本里把参数原样透传，没有做二次处理。
验证环境变量是否能正确传入，可以写一个临时脚本把所有环境变量打印出来，在 Typora 里插入一张图片触发上传，再去看日志。我首次配置时发现TYPORA_DOC_PATH并不存在，查了 Typora 的更新日志才发现不同版本注入的变量名不一样，老版本可能是别的名字，务必先做一次环境变量输出测试再写正式逻辑。
4.3 配置文件与密钥管理
PicGo 插件的配置项通过ctx.getConfig('picBed.custom-uploader.bucket')获取，这些配置可以在 PicGo 的「图床设置」里找到自定义插件，然后逐项填写。密钥不建议写在代码里，更不要写死在插件文件夹中，而是放在环境变量里。PicGo 是 GUI 应用，macOS 下可以在启动前在 shell 里 export，Windows 下可以用系统环境变量。
实际项目中我把密钥放在了一个独立的.env文件里，PicGo 启动前用一个小脚本加载。这里没有用 dotenv 库，就是简单的fs.readFileSync加split，避免多引入一个依赖。目的就一个：让插件代码可以安全地提交到 GitHub 仓库做版本管理，而不泄露密钥。
4.4 调试技巧：如何看到插件输出和错误信息
PicGo 的「日志」窗口能显示插件的 console 输出和错误堆栈。插件里任何ctx.log.error的信息都会出现在这里。调试时我习惯在upload方法开头加一行ctx.log.info('当前文档路径:', mdFilePath)，确认环境变量是否传对。
另外 PicGo 提供了一个非常有用的「上传区」功能，可以手动拖拽图片触发上传，而不用每次都从 Typora 里走一遍。调试插件时，我都是先打开 PicGo 窗口，拖几张测试图，观察日志输出，确认路径拼接正确后，再回 Typora 里做端到端验证。这两个环节分开来调，能大幅减少排查时间。
5. 常见问题与排查技巧实录
5.1 问题速查表
| 症状 | 可能原因 | 解决办法 |
|---|---|---|
上传失败，日志显示fs is not defined | 插件文件顶部漏了require('fs') | 补上const fs = require('fs') |
云端路径是全平铺的image-xxx.png，没有分类目录 | MD_FILE_PATH环境变量为空 | 检查 Typora 自定义命令脚本是否正确设置并传递了环境变量 |
图片 URL 带%20或路径里有空格 | 过滤非法字符时漏了空格处理 | 在cleanFileName里加上空格替换 |
| 上传后图片无法预览，Content-Type 是二进制流 | 未设置ContentType字段 | 根据图片扩展名显式设置 MIME 类型 |
| 同一文档多次上传后图片名重复被覆盖 | 图片文件名本身冲突 | 在目标图片名中加入时间戳或随机串后再拼接 |
| 多开 Typora 窗口时，图片传到了另一个文档的目录 | 临时文件方案过期 | 切换到自定义命令 + 环境变量方案 |
这个表是我实际踩坑两天的浓缩。第一行和第二行的问题几乎是每个自定义插件新手都会遇到的，尤其是第二行：Typora 的自定义命令模式和 PicGo.app 模式在参数传递上有差异，没搞清楚之前很容易一头雾水。
5.2 同名图片覆盖问题的最终处理
即使有了分类目录，同一个文档里如果引用了两张不同目录下但文件名相同的图片，仍然可能覆盖。我在cleanFileName之外又加了一个辅助策略：在上传到云端之前，给图片名加上上传时间的时间戳，例如image-20240115-093021-001.png。具体做法是：
const now = Date.now() const finalImgName = `${path.basename(imgName, path.extname(imgName))}-${now}${path.extname(imgName)}`这个措施很大程度上避免了同名文件互相覆盖的隐患，尤其在本地图片文件名高度重复（比如都叫截屏2024-01-15.png）时特别管用。当然也有副作用：图片名变长、可读性下降。折中的办法是只在 PicGo 检测到同名内容时才追加时间戳，但实现复杂度略高。目前我的使用习惯是：分类目录 + 原文件名，因为同一个日期 + 文档名下几乎不会出现同名图片，靠目录隔离基本已经足够了。
5.3 路径中含中文的处理原则
MD 文件名经常是中文，清洗后放到 URL 里会变成百分号编码，比如%E7%94%A8-PicGo...。这其实不会影响图片访问，但我自己看着难受，而且某些博客框架处理中文 URL 时可能有问题。
我的处理原则是：中文保留在对象键里，不强制转拼音或英文。理由有三个：第一，大多数云存储和 CDN 对中文对象键支持良好；第二，文件名的可读性很重要，日后归档整理时一眼能认出文档内容；第三，Typora 生成的本地链接如果是中文名，上传后的 URL 转换逻辑不需要搞两套映射。
如果确实不喜欢中文，也可以在cleanFileName里用拼音库转成拼音，不过这会引入额外依赖，而且多音字问题很麻烦。我个人放弃了这个方向，保持简单。
5.4 关于 Typora 版本差异的提醒
不同 Typora 版本的「图像」设置界面和自定义命令传参行为有差异。旧版本可能不注入TYPORA_DOC_PATH，新版本把这个变量名改了也不是没可能。最稳妥的做法是：升级 Typora 或换电脑后，先跑一次“环境变量探测脚本”，把系统环境和调用参数全部打出来，确认关键变量是否存在、名称是否正确，再继续后续操作。
同一套方案在不同操作系统上的表现也有差异。macOS 下 Python 路径可能是/usr/bin/python3，Windows 下则是C:\Python39\python.exe，PicGo 安装路径也不一样，这些都要按实际环境调整。我在 Windows 机器上配置时，就把自定义命令改成了node C:\typora-uploader\upload.js，原理一致。
6. 扩展与进阶：这套方案还能怎么玩
6.1 自动压缩与格式转换
上传到云端之前，可以先对本地图片做一次压缩处理。图片体积直接关系到页面加载速度和存储费用。我在插件里加了一个可选的压缩步骤：用sharp库把大于 500KB 的图片压到 80% 质量，超过 2000px 宽度的缩小到 2000px。这样既保留了清晰度，又显著降低了成本和加载时间。
但这个操作要谨慎：压缩会增加 CPU 消耗，如果单次上传很多图片，上传速度会降低。我通常会设置一个阈值，只有超过阈值的图片才走压缩流程，小图片直接原图上传。用sharp的话记得在插件文件夹里npm install sharp，PicGo 的插件目录是独立的 Node 环境，不是全局环境。
6.2 给图片打水印
很多博主喜欢给图片加水印防搬运。这个也可以在插件里实现，同样用sharp：在图片右下角合成一个半透明文字水印，或叠加一个小 logo。水印要提前生成好 PNG 素材放在本地，上传时读取并合成，然后把合成后的图片流作为Body上传。
注意水印会永久改变图片内容，万一之后想去掉水印就麻烦了。我的建议是只在“对外发布”的图床上加，在本地保留一份无水印原图，需要重新生成时再走一遍上传逻辑。
6.3 多图床上传与自动切换
如果你的项目需要同时使用多家 CDN 或者图床，可以在这个插件基础上做一个分发逻辑：根据图片用途选择上传到 COS 还是 OSS，或者在主图床不可用时自动切换备用图床。这个场景适用于对稳定性要求较高的正式项目，但代码复杂度会成倍增加，普通个人博客必要性不大。
我的建议是先用一个图床跑顺畅，观察一段时间的稳定性和成本，再决定是不是要引入多图床方案。过早优化往往会带来不必要的维护负担，图片管理这件事尤其如此。
6.4 与 Obsidian 等其他 Markdown 编辑器的配合
很多读者是从 Obsidian 转过来的，或者 Typora 和 Obsidian 混用。Obsidian 的图片上传机制跟 Typora 不太一样，但自定义命令的思路是通用的：Obsidian 也支持在设置里配置图片上传命令，传递当前笔记路径的方式略有不同，但最终效果差不多。
如果你在 Obsidian 里也想用这套分类规则，大致思路是：写一个适配 Obsidian 的脚本，读取当前笔记文件名，把它写入环境变量，再调用picgo upload。核心代码可以完全复用，只需要改传参那一段。我自己在 Obsidian 里验证过，目录分类效果一致，只是要注意 Obsidian 传递的路径可能是 URI 编码格式，需要先解码再用。
写在最后
整套方案跑通之后，我再也没有因为“找不到某篇文章的配图”而烦躁过。写文章时图片自动落到带日期和文档名的目录里，翻图床就像翻自己电脑的文件夹一样有迹可循。最后再分享一个我个人的使用习惯：每月月底花十分钟，把当月图床目录和本地笔记本对照一遍，清理掉不再引用的孤儿图片，顺便核对有没有上传失败的漏网之鱼。这个小习惯把这套自动化方案的收益又放大了一圈。如果你也在被 Typora 图片管理困扰，照着上面的思路和代码改一版适合自己的，大概率能彻底解决这个老问题。
