PicGo结构化路径上传实践

💡 核心哲学：System > Willpower。
一个优秀的图床系统不应依赖于人的记忆去分类，而应通过规则引擎自动实现资产的归档。本指南旨在记录一套经过实战验证的、基于 PicGo 3.0+ 的结构化图片上传体系，确保即使在重装系统后，也能通过本手册在 10 分钟内复刻出这套“截图即归档”的低摩擦环境。

1. 架构设计：SSOT (Single Source of Truth)

为了确保资产管理不混乱，我们必须坚持“配置收口”原则。

维度	配置中心	核心逻辑说明
版本要求	PicGo 3.0.2+	强制性要求。新版本修复了插件钩子冲突，并增强了对 Server 模式的响应速度。
存储底座	七牛云 OSS	负责物理存储，Bucket 需配置为公有读取，建议开启 HTTPS。
路径生成	custom-path 插件	核心大脑。负责解析日期变量，将扁平上传转化为 `kb/YYYY/MM/` 结构。
鉴权中心	PicGo 客户端	唯一存放 AccessKey/SecretKey 的地方，Typora 等仅通过 API 调用。
写作入口	Typora (推荐)	生产力工具，通过本地 36677 端口与 PicGo 守护进程通信。

2. 落地实施：从零搭建结构化体系

2.1 七牛云 OSS 基础准备

Bucket 命名：建议使用 blog-assets 或类似名称。
自定义域名：绑定 blogimg.hongjy.cn。
SSL 证书：确保证书有效（注意 3 个月续期问题，详见《七牛云SSL自动续期方案》）。

2.2 PicGo 客户端深度配置

基础设置：
- 填入七牛云 AK/SK。
- ⚠️ 核心红线：将 “存储路径 (path)” 彻底留空。如果填了任何内容，会与插件路径产生冲突。
开启 Server 模式：
- 进入 PicGo 设置 -> 设置 Server。
- 开启 Server，端口设为 36677。这是 Typora 识别 PicGo 的“通讯天线”。
安装 custom-path 插件 (关键解法)：
- 在插件市场搜索 custom-path (作者：mscsterts)。
- 配置规则：在插件配置界面，为 qiniu 设置格式：kb/$year/$month/$fileName。
- 注意：该插件使用 $ 符号作为占位符（与原生 PicGo 的 {} 不同）。

2.3 Typora 联动闭环

偏好设置：图像 -> 上传服务 选择 PicGo (app)。
路径指向：选择你安装的 PicGo.exe 路径。
测试验证：点击“验证图片上传”，若返回的 URL 包含 kb/2026/09/ 结构，则配置成功。

3. 灾备 SOP：重装系统恢复流程

为了防止重复踩坑，重装系统后请按以下顺序恢复：

环境准备：
- 安装最新版 PicGo。
- 安装 Typora。
配置恢复：
- 方法 A (手动)：参考本手册第 2 章快速填入 AK/SK。
- 方法 B (快照)：如果你备份了 %APPDATA%/picgo/data.json，可以直接覆盖。
插件热补丁：
- 重新安装 custom-path 插件。
- 检查 data.json 中是否包含 picgo-plugin-custom-path 的配置块。
路径验证：
- 随意截一张图，在 Typora 中粘贴。
- 登录七牛云控制台，检查 kb/ 目录下是否生成了当月的文件夹。

4. 避坑指南：踩坑实录 (Critical Lessons Learned)

4.1 弃用的“无效插件”记录

在探索过程中，以下插件已被证明无法满足需求或存在严重缺陷，请勿再次尝试：

❌ super-prefix：在 PicGo 3.0+ 环境下安装困难，经常报错导致客户端闪退。已彻底弃用。
❌ addpath：原生版本不支持日期占位符（如 {y}/{m}），只会将其识别为静态文件夹名字。虽曾尝试手动补丁，但维护成本过高，现已由 custom-path 完美替代。

4.2 原生功能局限性警告

⚠️ PicGo 自带 path 设置：PicGo 设置界面里的 path 字段仅支持静态字符串，不支持 {year}/{month} 占位符。直接填写占位符会导致图片 404。必须依赖 custom-path 插件。

4.3 常见故障排查

路径“叠罗汉”：图片链接变成 .../kb/kb/2026/...。根因是七牛图床配置和插件配置同时写了 kb/。对策：七牛云设置里的 path 必须为空。
路径原样输出：链接变成 .../$year/$month/...。根因是 PicGo 客户端未重启或插件版本不兼容。对策：强制退出并重启 PicGo；确保使用最新版 custom-path。

5. 资产保护与可靠性

定期冷备份：建议每月执行一次 Rclone sync，将云端 kb/ 目录同步到本地硬盘或 OneDrive。
CDN 刷新：如果修改了同名图片，记得去七牛云后台刷新 URL 缓存。
防盗链配置：建议在七牛云开启 Referer 白名单，只允许自己的博客域名和本地开发环境访问图片。