前言

距离上次发布 v1.1 版本已经过去了三个月，Typecho 官方也发布了备受期待的 1.3.0 版本。这次大版本更新带来了许多底层架构的改进，但也导致了不少插件出现兼容性问题。

Typecho 又拍云文件管理插件修改版使用指南：新增自定义目录结构功能

昨天我更新了新版本遇到的问题：升级 Typecho 1.3.0 后，又拍云插件在后台文件管理页面报错，无法正常显示已有文件的 URL。于是更新了 UpyunFile v1.2 版本，这个版本不仅彻底解决了 Typecho 1.3.0 的兼容性问题，还进一步简化了配置流程，让插件使用更加便捷。

1、核心修复：Typecho 1.3.0 兼容性适配

问题现象

升级 Typecho 1.3.0 后，你可能会遇到以下问题：

• 后台文件管理页面报错：附件 URL 显示异常或页面报错

TypeError: UpyunFile_Plugin::attachmentHandle(): 
Argument #1 ($content) must be of type array, Typecho\Config given
...

• 文章中的附件链接失效：图片、文件无法正常加载

https://cdn.example.com/  ← 路径缺失！

解决方案

v1.2 版本采用了多重兼容策略，确保在不同 Typecho 版本下都能正常工作：

public static function attachmentHandle(Typecho\Config $content) {
    // 1. 优先检查新版本的 Config 对象结构
    if (isset($content->attachment) && isset($content->attachment->path)) {
        $path = $content->attachment->path;
    } 
    // 2. 其次检查直接 path 属性
    else if (isset($content->path)) {
        $path = $content->path;
    } 
    // 3. 最后尝试从 text 字段反序列化（兼容旧数据）
    else if (isset($content->text)) {
        $attachment = @unserialize($content->text);
        if (is_array($attachment) && isset($attachment['path'])) {
            $path = $attachment['path'];
        }
    }
    // 构建完整 URL
    return Typecho_Common::url($path, $domain);
}

2、资源泄漏修复

在代码审查中发现了一个潜在的资源管理问题：

修复前（存在资源泄漏风险）：

$fh = fopen($uploadfile, 'rb');
$upyun->write($path, $fh);
// 如果 write() 抛出异常，fclose 不会执行
if (is_resource($fh)) {
    fclose($fh);
}

修复后（确保资源释放）：

$fh = fopen($uploadfile, 'rb');
try {
    $upyun->write($path, $fh);
} finally {
    // 无论是否异常，都会执行
    if (is_resource($fh)) {
        fclose($fh);
    }
}

3、配置简化：移除目录结构选择

为什么要简化？

在 v1.1 版本中，我提供了三种目录结构模式：

1. 自定义结构 - /files/年/月/文件名
2. Typecho结构 - /typecho/usr/uploads/年/月/文件名
3. 精简结构 - /年/月/文件名

但在实际使用中，我发现：

• 90% 的用户只使用自定义结构
• 三种模式增加了代码复杂度
• 配置界面不够直观

新的设计

v1.2 版本移除了目录结构模式选择，只保留一个自定义路径输入框：

自定义路径：/files  （默认为 /files）

最终文件路径格式固定为：

{自定义路径}/{年}/{月}/{文件名}
例如：/files/2026/04/example.jpg

好处

• 🎨 界面更简洁 - 减少用户选择负担
• 🔧 配置更简单 - 只需填写一个路径
• 🚀 代码更精简 - 减少潜在 bug
• 📚 逻辑更清晰 - 统一的行为预期

📋 版本更新记录

v1.2 (2026-04-02)

🐛 修复

• 修复 Typecho 1.3.0 兼容性问题
• 修复后台文件管理 URL 不完整问题
• 修复文件句柄资源泄漏风险

✨ 优化

• 简化目录结构配置，移除模式选择
• 自定义路径默认值改为 /files
• 完善代码注释，提升可维护性

v1.1 (2026-01-09)

• ✅ 新增自定义目录结构功能
• ✅ 优化后台配置界面用户体验

🚀 安装与使用指南

系统要求

• Typecho 1.1+ 版本（推荐 1.3.0+）
• PHP 7.0+ 运行环境
• 有效的又拍云服务账号

升级步骤（从 v1.1 升级）

1. 备份数据 - 建议先备份数据库和现有插件配置
2. 下载新版本 - 获取 v1.2 版本插件包
3. 替换文件 - 覆盖原有插件文件（保留配置）
4. 检查配置 - 进入插件设置，确认自定义路径正确
5. 测试验证 - 上传测试文件，检查 URL 生成是否正常

或者你直接获取 GitHub 上 Plugin.php 的代码覆盖一下呗，😂

全新安装步骤

1. 下载插件压缩包

2. 解压至 Typecho 的 usr/plugins 目录，文件夹命名为 UpyunFile

3. 在 Typecho 后台「控制台」->「插件」中启用插件

4. 进入插件设置页面，配置以下参数：

   • 绑定域名 - 又拍云服务绑定的域名（如 https://cdn.example.com）
   • 自定义路径 - 文件上传路径（默认为 /files）
   • 服务名称 - 又拍云服务名称
   • 操作员 - 又拍云操作员账号
   • 密码 - 又拍云操作员密码

5. 保存设置，完成安装

⚙️ 配置详解

基本配置

高级配置（可选）

又拍云图片处理

需要在又拍云控制台创建缩略图版本，然后将版本名称填入插件配置。

• 缩略图版本名称 - 如 thumb、small 等
• 转码输出格式 - 如 jpg、png、webp

⚠️ 注意：带有 _nothumb 后缀的图片不会被处理（如 example_nothumb.png）

Token 防盗链

1. 在又拍云控制台启用 Token 防盗链功能
2. 将密钥填入插件配置
3. 设置签名过期时间（单位：秒）

📥 下载与反馈

项目地址

• GitHub Releases：https://github.com/NoEggEgg/UpyunFile

问题反馈

如果您在使用过程中遇到任何问题，欢迎通过以下方式反馈：

• 在 GitHub 提交 Issue
• 在本文评论区留言

参与贡献

欢迎提交 Pull Request 或提出改进建议！

🙏 致谢

• 原版插件：https://github.com/codesee/UpyunFile
• 二改版本：https://github.com/ShadowySpirits/UpyunFile
• 三改版本：https://github.com/liuran001/UpyunFile
• Typecho 官方：https://typecho.org
• 又拍云官方：https://www.upyun.com