基于两双筷子原版插件优化，在保持稳定性的基础上增加存储路径自定义功能

之前有过一篇又拍云的，大家可以去看看：

📦 核心改进：存储路径的自定义化

1. 从预设模式到动态配置

原版插件提供了两种固定路径格式，但在实际使用中，站长们有更多样化的存储需求：

• 统一管理多个网站资源：一个多吉云账号管理多个网站
• 符合现有CDN配置规则：适应已有的CDN缓存策略
• 保持与旧系统的路径兼容：从其他平台迁移时保持路径结构
• 按内容类型分类存储：图片、文档、视频分开存放

优化后：

• ✅ 完全可配置的存储根目录
• ✅ 支持任意自定义路径结构
• ✅ 自动兼容原有配置模式
• ✅ 提供平滑的迁移路径
• ✅ 智能路径格式化处理

2. 🌟 实际应用场景

🏠 个人博客    → 使用 /uploads 简洁明了
🏢 企业网站   → 使用 /static 分类清晰
🔧 多站点管理 → 使用 /site1/uploads /site2/uploads 隔离管理
🔄 迁移用户   → 使用 /typecho/uploads 保持原路径
📊 内容平台   → 使用 /images /videos /docs 按类型分类

🔧 技术实现亮点

1. 可配置的存储目录

// 🎯 原版：固定两种模式（二选一）
if ($pluginConfig['path_style'] == 'typecho') {
    $uploadPath = self::getUploadDir().$uploadPath;
}
// 只能选择：Typecho风格 或 极简风格

// ✨ 新版：动态配置（自由定义）
$customDir = $pluginConfig['custom_dir'] ?? '/files';
$uploadPath = $customDir . '/' . $date->year . '/' . $date->month . '/' . $date->day;
// 可以填写：/uploads、/static、/typecho/uploads 等任意路径

2. 严格的输入验证

public static function configCheck($settings) {
    // 🔒 必填项检查
    if (empty($settings['custom_dir'])) {
        throw new Exception('存储目录不能为空');
    }
  
    // 📝 格式验证
    if (!str_starts_with($settings['custom_dir'], '/')) {
        throw new Exception('存储目录必须以斜杠(/)开头');
    }
  
    // 🛡️ 安全字符检查
    if (preg_match('/[<>:"|?*]/', $settings['custom_dir'])) {
        throw new Exception('存储目录包含非法字符');
    }
  
    // 📊 路径深度限制（防止过深路径）
    $depth = substr_count($settings['custom_dir'], '/') - 1;
    if ($depth > 5) {
        throw new Exception('存储目录层级过深，建议不超过5级');
    }
}

3. 📋 配置示例

# 配置：/uploads
# 实际路径：/uploads/2026/01/22/filename.jpg
# 适合：个人博客、简单站点

# 配置：/typecho/uploads  
# 实际路径：/typecho/uploads/2026/01/22/filename.jpg
# 适合：从原版升级、保持路径一致

# 配置：/static/images
# 实际路径：/static/images/2026/01/22/filename.jpg
# 适合：企业网站、资源分类

# 配置：/site/blog/uploads
# 实际路径：/site/blog/uploads/2026/01/22/filename.jpg
# 适合：多站点、子站点管理

# 配置：/
# 实际路径：/2026/01/22/filename.jpg
# 适合：极简主义、根目录存储

📂 存储路径命名指南

1. 推荐命名方案

📁 个人博客推荐：/uploads
📁 企业网站推荐：/static
📁 多站点推荐：/site/[id]/uploads
📁 Typecho老用户：/typecho/uploads
📁 资源分类推荐：/images、/docs、/videos
📁 日期优先推荐：/2026/uploads

2. ✅ 命名最佳实践

1. 使用小写字母：避免大小写敏感问题（Linux/Windows差异）
2. 使用连字符而非下划线：/my-files比 /my_files更友好
3. 保持简洁：建议不超过3级深度，便于管理
4. 语义明确：路径名能反映内容类型，便于识别
5. 避免保留字：不要使用系统保留目录名
6. 英文优先：中文路径可能在某些系统上有兼容性问题

3. ❌ 避免这样写

/files/uploads           # 重复了"uploads"，冗余
/my uploads             # 包含空格，可能引发问题
/uploads/               # 末尾不要加斜杠
/../../etc              # 危险路径，安全风险
/CONFIG                 # 全大写，不美观
/2026-01-22/files       # 包含特殊字符

🔄 从原版升级

1. 配置对应关系

如果你正在使用原版插件，升级时只需对应填写：

2. 📋 升级步骤

# 第一步：备份
1. 备份当前插件配置（截图或记录）
2. 备份重要上传文件（以防万一）

# 第二步：安装新版
1. 下载新版插件文件
2. 上传到 /usr/plugins/DogeUpload/
3. 覆盖原有文件（保留配置）

# 第三步：修改配置
1. 进入Typecho后台 → 插件管理
2. 找到DogeUpload插件，点击"设置"
3. 根据原配置填写"存储目录"
   - 原Typecho风格 → 填写：/typecho/uploads
   - 原极简风格 → 填写：/
4. 其他配置保持不变
5. 点击"保存"

# 第四步：验证测试
1. 上传一个测试文件
2. 检查文件是否出现在正确路径
3. 查看文章中图片显示是否正常

⚠️ 重要提醒

1. 已上传文件不受影响：修改存储目录仅对新上传文件生效，已存在的文件保持原路径
2. 手动迁移需要：如需统一所有文件路径，需要手动迁移并更新数据库引用
3. CDN配置同步：如果使用CDN，确保CDN回源配置支持新路径
4. 测试环境先行：建议在测试环境验证无误后再应用到生产环境
5. 路径一旦确定：尽量避免频繁修改，以免造成路径混乱

❓ 常见问题

Q：改了存储目录，旧文章的图片会失效吗？

A：不会失效。插件会保持旧图片的原始路径，只有新上传的图片使用新路径。

Q：可以随时修改存储目录吗？

A：技术上可以，但建议在访问量低时修改，修改后立即测试上传功能。

Q：填写的路径在存储桶中不存在怎么办？

A：插件会自动创建所需的目录结构，无需手动在多吉云创建。

Q：支持中文目录名吗？

A：技术上支持，但强烈建议使用英文路径，兼容性更好，不易出问题。

Q：如何查看当前文件的实际存储路径？

A：上传文件后，可以在 Typecho 后台的 "附件管理" 中查看文件路径。

Q：修改后上传失败怎么办？

A：检查：① 路径是否以/开头；② 是否包含非法字符；③ 多吉云 API 配置是否正确。

Q：可以设置多级目录吗？比如 /year/month/category/****？

A：目前插件自动添加年月日三级，你可以在配置中设置基础目录，如 /blog/images，最终路径会是 /blog/images/2026/01/22/。

🎯 总结

这次优化虽然改动不大，但解决了一个很实际的问题：让存储结构适应你的需求，而不是让你去适应固定的结构。

优化带来的好处：

• 对新手友好：默认/files开箱即用，无需复杂配置
• 对老用户兼容：支持原版配置无缝迁移，零学习成本
• 对专业用户灵活：完全自定义存储层级，适应各种架构
• 对未来可扩展：为更多存储策略和功能扩展打下基础

设计理念：

1. 简洁至上：一个配置项解决路径问题
2. 稳定优先：不影响已有功能，不破坏现有数据
3. 智能辅助：自动格式化路径，减少配置错误
4. 开放灵活：不限制用户的使用方式

优化虽小，但实用性强。这个改进来源于实际使用中的需求，希望能让大家的 Typecho 多吉云存储体验更加顺畅、灵活！

插件信息：

• 基于版本：两双筷子原版 DogeUpload
• 优化重点：存储路径自定义
• 兼容性：完全兼容原版配置和数据
• 适用场景：所有使用多吉云存储的Typecho用户

如果你在使用中遇到任何问题，或者有改进建议，欢迎交流讨论。希望这个优化能帮助到更多 Typecho 站长！ 🚀