FriendsOfFlarum Upload —— 智能文件附件扩展

admin · 2026-05-13T14:12:16+00:00

FriendsOfFlarum 出品的 Upload 扩展一个智能处理论坛文件上传的扩展。功能特性图片方面：自动添加水印。自动调整尺寸。 MIME 类型到上传适配器的映射。 MIME 类型白名单。支持不同的存储服务（例如本地、Imgur、AWS S3）。拖放上传。一次上传多...

Silvestrus

Silvestrus 好了，现在可以了。

页脚自定义 JavaScript：

<script>
(function() {
    /**
     * Flarum 是单页应用（SPA），所以我们需要 MutationObserver
     * 来检测无需页面刷新即可加载新帖子的情况。
     */
    const observer = new MutationObserver((mutations) => {
        // 查找帖子正文中错误指向 .mp4 文件的图片
        const mp4Images = document.querySelectorAll('.Post-body img[src$=".mp4"]');
        
        mp4Images.forEach(img => {
            const link = img.closest('a');
            
            // 如果链接不存在或已处理过，则跳过
            if (!link || link.dataset.videoProcessed) return;

            const videoUrl = img.src;
            const videoPreview = document.createElement('video');
            
            /**
             * 在 URL 中添加 "#t=0.5" 强制浏览器跳转到 0.5 秒位置，
             * 从而生成视觉预览帧（缩略图）。
             */
            videoPreview.src = videoUrl + "#t=0.5";
            videoPreview.muted = true;
            videoPreview.preload = "metadata";
            videoPreview.playsinline = true; // 移动端浏览器必需
            videoPreview.style.width = "100%";
            videoPreview.style.display = "block";
            
            // 标记为已处理，防止 DOM 突变时无限循环
            link.dataset.videoProcessed = "true";
            
            // 用功能完整的 <video> 预览替换损坏的 <img> 标签
            link.replaceChild(videoPreview, img);
        });
    });

    // 开始监听文档 body 中新增的节点（新帖子/讨论）
    observer.observe(document.body, {
        childList: true,
        subtree: true
    });
})();
</script>

自定义 CSS：

/**
 * 确保 Fancybox 容器有固定高度。
 * 否则在某些 Flarum 布局中容器可能会折叠为 0 像素高度。
 */
.Post-body a.fancybox-ready[href$=".mp4"] {
    display: block !important;
    width: 100% !important;
    max-width: 640px;
    min-height: 360px; /* 在视频元数据加载前强制可见 */
    background: #000;
    position: relative;
    margin: 10px 0;
    border-radius: 4px;
    overflow: hidden;
}

/* 确保生成的 video 标签填满可用空间 */
.Post-body a.fancybox-ready video {
    width: 100% !important;
    height: auto !important;
    min-height: 360px;
    object-fit: cover;
}

/* 视觉提示：覆盖一个'播放'图标告知用户这是视频 */
.Post-body a.fancybox-ready[href$=".mp4"]::after {
    content: '▶';
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    background: rgba(0, 0, 0, 0.6);
    color: #fff;
    width: 60px;
    height: 60px;
    line-height: 60px;
    text-align: center;
    border-radius: 50%;
    font-size: 24px;
    pointer-events: none; /* 允许点击穿透到链接/视频 */
    z-index: 5;
}

Tutrix

Silvestrus

对我来说不需要自定义 JavaScript 和 CSS 也能工作。

图片+视频上传

Silvestrus

Tutrix 那样的话对我来说（现在）也能工作。我的意思是在编辑器下方点击"上传"按钮时。

mafesa

我注意到我有很多孤立的附件，遗憾的是已经没有方法可以映射和删除它们了。
FriendsOfFlarum/upload#446

我该如何释放空间并删除未使用的附件？

huoxin

mafesa 恐怕你得手动操作了，这个功能存在一些 bug FriendsOfFlarum/upload#374

mafesa

huoxin 我有很多附件，没有 --map 是不可能完成的。
至少应该恢复这个命令。一旦映射完成，我可以手动删除它们。

meihuak

为什么我在上传扩展中找不到 S3 的选项？

KBExit

meihuak 你需要安装 S3 适配器扩展。

meihuak

KBExit 明白了，谢谢兄弟

Shortik

请问有没有办法压缩图片或将它们转换为 webp/avif 格式？

Shortik

还有一个问题——有没有办法创建自定义模板来打开文件？我需要让图片显示为链接加缩略图。但我的论坛用户不太擅长使用电脑，所以我需要这个模板的"全自动生成器"。或者你能把这个模板添加到 fof/upload 中？
大概是这样的效果：

KBExit

Shortik 也许这种东西更适合你？https://discuss.flarum.org/d/29102-fancybox-v5-lightbox-and-galleries

Shortik

KBExit 我没有 Fancy UI 的许可证，也不想买。😇

RelicSystem

我个人在使用 https://discuss.flarum.org/d/30295。它没有做到我想要的点击缩略图弹出预览之类的效果，但它确实能自动处理整个画廊功能（以整洁的方式展示图片），我的用户们挺喜欢的。

Shortik

现在我用了这个配置：

FoF\Upload 设置为"仅限链接"
FoF\Formatting 启用 AutoImage
"在新标签页中打开外部链接"

这就是我需要的全部配置——图片链接技术上只是链接，但 FoF\Formatting 会像普通图片加链接一样显示。"在新标签页中打开外部链接" 会在新标签页中打开我的图片，因为我的 CDN 域名和论坛不同。如果能用一个扩展就实现所有这些功能就好了，不过目前的组合方案效果也不错。🙂

帖子画廊（ Relic System ）扩展也不错，谢谢。

编辑：我最后需要的是压缩图片或将其转换为 webp 格式。😃

FoFBot

🚀 新版本发布：1.8.9

作者： @IanM
发布地址： FriendsOfFlarum/upload 发布 1.8.9

更新日志

变更内容

[1.x] 修复：正确映射和清理所有上传模板的文件 by @IanM in FriendsOfFlarum/upload#460

完整更新日志：FriendsOfFlarum/upload 1.8.8 → 1.8.9

FoFBot

🚀 新版本发布：2.0.0-beta.1

作者： @IanM
发布地址： FriendsOfFlarum/upload 发布 2.0.0-beta.1

更新日志

FoF Upload 2.0.0-beta.1

这是 FoF Upload 针对 Flarum 2.0 的首个 Beta 版本。这是一个重要更新——除了 Flarum 2.0 兼容性工作外，还增加了几个期待已久的功能，并修复了大量 Bug。

Flarum 2.0 兼容性

整个扩展已更新以在 Flarum 2.0 上运行。底层关键变化：

Flysystem 3.x——文件存储层已更新为新的 League Flysystem API，这改变了适配器的构建方式和错误处理方式
JSON:API 重写——Flarum 2.0 用新的实现替换了 Tobscure JSON:API；所有 API 控制器和序列化器都已相应更新
PHPUnit 11——测试套件已从 PHPUnit 9 迁移到 PHPUnit 11，包括数据库测试迁移到模型工厂
LESS 变量——现在全面使用 CSS 变量；亮色或暗色模式变量名已更新以匹配 Flarum 2.0 规范
前端基础设施——所有 JS/TS 已根据 Flarum 2.0 的前端变更进行了更新

新功能

WebP 缩略图生成（#465）

图片现在在上传时会自动缩小为缩略图。缩略图在图片预览模板中内联显示；点击后会打开新标签页查看原始全分辨率文件。这可以显著减少图片密集型论坛的带宽消耗。

缩略图默认编码为 WebP 格式（同等质量下比 JPEG 小 30%），管理员可选择使用原始格式
缩略图最大宽度可配置（默认：1000 像素）；小于限制的图片不会被放大
缩略图路径存储在数据库中，但完整 URL 在渲染时从实时存储主机名派生——因此 CDN 域名变更会自动反映，无需重新处理
Imgur 和私有共享上传被排除（Imgur 管理自己的缩略图）
新增控制台命令——php flarum fof:upload:backfill-thumbnails——为在启用该功能之前已存在的上传生成缩略图。支持 --dry-run 和 --chunk 选项，可安全多次运行

按 MIME 类型的上传权限（#461）

MIME 类型映射现在可以有一个可选的权限标签（例如"图片"、"视频"）。设置后，Flarum 权限网格中会出现一个专门的权限条目，允许你限制哪些用户组可以上传该特定文件类型——除了始终需要的"上传文件"基础权限之外。

这完全向后兼容：没有标签的现有映射继续像以前一样运行，仅受基础上传权限控制。

图片尺寸存储与 CLS 预防（#464）

JPEG、PNG 和 GIF 上传的宽度和高度现在存储在数据库中。这些信息作为 width 和 height 属性注入到图片预览模板的 <img> 标签中，允许浏览器在图片加载前预留正确的空间——防止累积布局偏移（CLS）。

控制台命令——php flarum fof:upload:backfill-dimensions——为现有图片回填尺寸信息。

水印改进（#462）

水印系统已显著改进：

按比例调整大小——水印大小现在设置为图片宽度的百分比（例如 20%），因此可以在不同图片尺寸下正确缩放，而不是固定像素大小
透明度控制——可配置 0–100%
边距——可配置距离图片边缘的像素距离
所有设置均可从管理面板调整；动画 GIF 被排除在水印处理之外

Bug 修复

为第三方适配器存储正确的适配器键（#466）

第三方适配器使用自定义键注册（例如 'blomstra'），但 upload_method 是从类名派生的（例如 'blomstraobjectstorage'）。这种不匹配导致每次后续查找都出现 ValidationException——URL 生成、文件清理、GDPR 导出和缩略图回填都会因受影响的适配器而失败。修复方法是在实例化时直接将规范注册键标记在适配器实例上。

所有模板的文件-帖子映射已修复（#459）

某些上传模板的文件到帖子的关联创建或清理不正确。这影响了特定模板类型的媒体管理器、GDPR 导出和孤立文件清理功能。

图片预览模板中的替代文本 Bug（#463）

{TEXT?} 占位符被一字不差地存储在旧帖子的帖子 XML 中。格式化程序现在会清理此值，并在无法获取时回退到文件的基本名称，与预期行为一致。

PHP fileinfo 扩展现在为可选（#467）

如果没有 fileinfo PHP 扩展，mime_content_type() 会抛出未捕获的异常，导致所有上传都以通用错误失败。MIME 检测器现在在调用前检查 fileinfo 是否加载。当缺失时，上传继续使用基于魔数的 SoftCreatR\MimeDetector 库工作。管理员会在设置页面上看到一个警告横幅，说明 MIME 交叉验证层已禁用，以及如何重新启用。

升级说明

升级前请完整阅读 2.x 分支上的 README。 它详细介绍了存储配置、所有可用设置和环境变量支持。

需要 Flarum 2.0。 此版本不支持 Flarum 1.x；Flarum 1.x 安装请继续使用 1.x 分支。
升级后运行迁移：php flarum migrate

S3 或兼容存储用户： 底层 Flysystem AWS S3 适配器已从 v1 更新到 v3。你必须在项目中升级包：

    composer require league/flysystem-aws-s3-v3:"^3.0"

v1 包（league/flysystem-aws-s3-v3:^1）不再与此版本兼容。

可选：为现有内容运行回填命令：
- php flarum fof:upload:backfill-dimensions——添加存储的图片尺寸
- php flarum fof:upload:backfill-thumbnails——为现有图片生成缩略图（大型论坛可能需要一些时间；建议先使用 --dry-run）
第三方上传适配器扩展（例如 blomstra/object-storage）需要更新以兼容 Flarum 2.0 / Flysystem 3.x，然后才能与此版本一起使用。

变更内容

refactor: 为 2.0 升级 by @IanM in FriendsOfFlarum/upload#458
[2.x] fix: 正确映射和清理所有上传模板的文件 by @IanM in FriendsOfFlarum/upload#459
[2.x] feat: 按 MIME 类型的权限范围管控 by @IanM in FriendsOfFlarum/upload#461
[2.x] feat: 按比例缩放的水印、透明度和边距控制 by @IanM in FriendsOfFlarum/upload#462
[2.x] test: 为所有模板添加单元测试；修复图片预览替代文本 Bug by @IanM in FriendsOfFlarum/upload#463
[2.x] feat: 存储图片尺寸以防止懒加载图片的布局偏移 by @IanM in FriendsOfFlarum/upload#464
[2.x] feat: 上传时生成 WebP 缩略图以减少带宽 by @IanM in FriendsOfFlarum/upload#465
[2.x] fix: 为第三方适配器在 upload_method 中存储正确的适配器键 by @IanM in FriendsOfFlarum/upload#466
[2.x] fix: 当 PHP fileinfo 扩展缺失时优雅降级；显示管理警告 by @IanM in FriendsOfFlarum/upload#467

完整更新日志：FriendsOfFlarum/upload 1.8.8 → 2.0.0-beta.1

KBExit

FoF Bot 伟大的进步。谢谢你 @IanM 🙂

huoxin

@IanM 像按比例缩放的水印和 WebP 缩略图这些新功能，只能是 2.x 版本才有吗？还是也会移植回 1.x？

IanM

huoxin 遗憾的是我目前没有时间将这些功能移植回去，可能权限功能如果有时间的话可以考虑。

如果任何人愿意研究移植的事情，我们会逐案考虑相关的 PR，至少在我们仍正式支持 1.x 期间。