FileBird WordPress媒体库插件深度评测

要点总结

• 虚拟文件夹架构：FileBird 通过数据库行存储文件夹结构，不移动磁盘文件，对海量附件（如 14000+）操作高效，物理路径保持不变。
• 解决大型媒体库痛点：按日期扁平化排列导致文件查找困难，FileBird 实现拖放整理，避免滚动猜测和重复上传，适合多作者场景。
• 核心交互与集成：侧边栏树状拖放、区块编辑器/页面构建器内置文件夹选择器，支持 WooCommerce、Elementor、Bricks 等主流工具。
• 附加实用功能：提供文件夹列排序筛选、动态图库短代码/区块、用户专属文件夹、批量导入迁移工具（兼容 Real Media Library 等），并支持 REST API。

我运营着一个WordPress网站，至今已有八年历史，上传的附件超过14000个。默认的媒体库（它会将所有上传的文件都堆放在一个巨大的、按日期排序的网格中）大约在第三年就变得难以使用了。为了解决这个问题，我尝试了四个不同的文件夹插件。HappyFiles解决了80%的问题，但之后就没了功能。Real Media Library虽然能用，但感觉比实际需要的要臃肿。Premio的Folders插件在小型网站上表现尚可，但在大型网站上就显得力不从心了。在此之前，我花了整整一年时间手动在每个文件名前面2019-blog-加上team-shot-“and”，这种权宜之计虽然在一个月内感觉很巧妙，但一年后就会觉得很尴尬。

所以，当 FileBird 一直出现在我的“差点就选它了”的备选清单里时，我决定坐下来认真使用它一周。不是那种“随便试玩一下”的简单体验，而是一次真正的测试：将生产环境库的一部分导入沙盒，从零开始构建文件夹结构，像正常用户一样拖拽附件，通过一个小型配套插件来控制 FileBird 的操作，并观察它对数据库的实际影响。

这就是我的发现。它的优点和缺点，以及我希望在第一天就知道的事情。

FileBird是什么？

FileBird 是由Ninja Team开发的 WordPress 媒体库插件。免费版在 WordPress.org 官方仓库中拥有超过 10 万次的安装量，而专业版则增加了更多高级功能（例如智能上下文用户文件夹、文章类型文件夹、批量迁移工具、图库区块和页面构建器小工具）。两个版本的核心理念相同：让用户通过拖放文件夹来整理媒体库，而无需触及磁盘上的底层文件。

最后一点很重要，我稍后会详细说明。在 FileBird 中，当你将文件“移动”到某个文件夹时，文件本身并不会移动。服务器上的目录结构仍然完全一样：无论你将其放入“主图”文件夹还是“背景图”文件夹，目录结构/wp-content/uploads/2026/05/hero.jpg都保持不变/wp-content/uploads/2026/05/hero.jpg。这个文件夹是虚拟的，它只存在于 FileBird 的数据库中。

对于大多数使用场景来说，这正是你想要的，因为这意味着你可以随意调整库的顺序一百次，而主题、插件、图片 URL 或备份脚本都不会察觉。但对于少数特殊情况（主要是从实体文件夹迁移到实体文件夹或从实体文件夹迁移回来），了解这一点还是很有必要的。

如果您已经了解文件夹的重要性，请跳过此部分。如果您从未遇到过需要查找两年前的图片，也从未对着五页厚厚的目录发呆的情况，那么请继续阅读。

WordPress 的媒体库是一个扁平化的列表，按上传日期排序，只有一个下拉筛选框（按月份）和一个搜索框，可以搜索标题、替代文本和文件名。几百个附件时，这个功能运行良好。但到了一千个左右，就开始出现问题。两千个附件之后，除了文件最初上传者之外，其他人根本无法使用。

随着图书馆规模的扩大，会出现三个问题：

1. 发现的过程变成了猜测。你记得“我们春季新品发布时用了一张干净的白色背景产品图”。那是二月还是三月？是 JPG 格式还是 PNG 格式？文件名，即使像“.”这样有用的信息_DSC4821.jpg，也帮不了你。所以你只能不停地滚动查找。
2. 重新上传已成常态。找不到想要的内容时，大多数人会直接重新上传。现在，你的文件里就有了三张几乎完全相同的图片。如果再乘以一年的营销推广，你的uploads目录里就会堆积 18 GB 的垃圾文件。
3. 多作者网站陷入混乱。五个作者，没有文件夹，没有规范。库变成了公共垃圾场。三个月后，没人知道哪个“logo.png”才是最新的。

文件夹插件并不能自动解决这些问题。它的作用是为你提供解决问题的结构。最终，自律仍然需要靠你自己，就像笔记本电脑上的文件夹只有在你真正使用它们时才有用一样。但只有先有了整理的可能，整理才能真正发生。

主要功能概览

与其列出完整的营销清单，不如说说真正改变我日常使用媒体库方式的因素。

• 在侧边栏树状结构中拖放文件夹。其操作方式与 Finder、资源管理器或 Dropbox 类似。您可以将文件夹拖放到其他文件夹内进行嵌套，也可以在文件夹之间拖动附件，还可以按住 Shift 键并单击进行多选。交互流畅快捷，无需重新加载页面。
• 是虚拟文件夹，不是物理文件夹。文件夹是两个自定义表中的行。在文件夹之间移动附件只需一条 UPDATE 语句。磁盘上的任何数据都不会改变。
• 列表视图中的文件夹列。媒体库列表视图新增“文件夹”列，显示每个附件所属的文件夹。您可以按此列进行排序和筛选。
• 文件夹选择器位于区块编辑器的“添加媒体”模态框内。当您在文章或页面中点击“添加媒体”时，也会显示相同的侧边栏，因此您可以在撰写文章时将选择器范围限定在单个文件夹中。
• 支持 WooCommerce、Elementor、Bricks、Divi 和其他页面构建器集成。当页面构建器弹出其媒体选择器时，FileBird 的文件夹树就会显示在那里。
• 文件夹即图库短代码 + Gutenberg 区块。插入[filebird_gallery folder="42"]（或使用该区块）后，图库内容将来自一个文件夹，因此向该文件夹添加新图像会自动将其添加到使用该文件夹的每个页面的图库中。
• 批量导入其他文件夹插件。提供 Real Media Library、Enhanced Media Library、WP Media Folder、FolderPress 和 Polylang 分类法 hack 的迁移工具。它们在 FileBird 设置 -> 工具中运行，并且确实有效。
• 用户专属文件夹。此功能（专业版）可将文件夹树的范围限定于当前用户。在多作者或多客户端环境中非常有用，可以防止作者 A 查看作者 B 的工作文件夹。
• REST API。文件夹通过 `<folder>` 公开filebird/v1，其中文章类型插件（`<post-type addon> filebird/pt/v1`）和迁移工具（`<migration tools> filebird/convert/v1`）使用独立的命名空间。移动应用和无头服务器环境可以通过编程方式管理文件夹。
• 文章类型文件夹（专业版插件）。与文件夹用户体验相同，但用于组织文章、页面或任何自定义文章类型。底层存储为一个独立的分类体系（fbv_pt_tax_<post_type>）。我将在开发者部分详细介绍这一点，因为这是 FileBird 中唯一与 WordPress 现有分类体系重叠的部分，而不是使用 FileBird 的自定义表格。
• 将文件夹下载为 ZIP 文件。右键单击文件夹，即可选择批量下载其中的所有附件，并将其打包成一个 ZIP 文件。此功能使用 ZipStream 实现，因此可以流式传输文件，而无需先在内存中构建整个文件。

这些功能大部分默认开启。文章类型插件需要手动启用（设置 -> 文章类型），而用户文件夹功能则是一个单独的开关。

安装和第一个小时

安装方式与安装其他高级插件相同。通过“插件”->“添加新插件”->“上传”上传压缩文件，激活后，您将在 WordPress 管理后台侧边栏看到一个新的顶级“FileBird”条目。免费版无需任何操作。专业版需要您在“设置”->“许可证”中输入购买代码，这是您获得完整功能的唯一途径。

激活后首次打开“媒体库”时，FileBird 会显示“我们注意到您有 X 个附件没有文件夹，是否要创建文件夹？”的提示。仅此而已。没有冗长的引导向导，没有教程视频弹窗，也没有每隔五分钟就弹出的升级提示。插件即刻可用。

我大概花了三分钟就搭建好了演示文件夹树。右键点击根目录，选择“添加新文件夹”，输入文件夹名称。重复此操作。将一个文件夹拖到另一个文件夹内即可嵌套。拖拽时会出现视觉提示（一条细蓝线），非常实用。鼠标悬停的文件夹会高亮显示，让你准确知道拖拽的位置。我一开始创建了六个文件夹：品牌素材、博客标题、产品图、主图、图标和背景图。然后在“品牌素材”文件夹内嵌套了一个“Logo”文件夹，在“背景图”文件夹内嵌套了一个“旧”文件夹，用来存放将来可能删除的文件。

将现有的 22 个附件移动到这些文件夹又花了 2 分钟。按住 Shift 键并单击以选择一个范围，然后将整个选区拖到文件夹中。网格会立即更新，侧边栏中的文件夹计数也会增加。没有保存按钮。操作会在您拖放的那一刻立即生效。

这是FileBird真正令人满意的地方。它的操作方式与你双手已经熟悉的操作方式如出一辙。

FileBird 用户界面导览

其实只需要学习三个界面：媒体网格（本节内容）、列表视图和文章编辑器中的“添加媒体”选择器。外加一个设置页面。就这些。

媒体网格中的文件夹树

打开“媒体”->“库”，你会看到标准的 WordPress 网格布局，但增加了一个重要的元素：左侧的 FileBird 侧边栏，占据大约 240 像素的水平空间。侧边栏包含文件夹树、顶部的“所有文件”视图（取消勾选所有文件夹后即可看到）、用于存放尚未归入任何文件夹的附件的“未分类”伪文件夹，以及“最近使用”视图。

你可以：

• 单击文件夹，即可将网格筛选为该文件夹的内容。
• 点击“未分类”即可查看所有尚未归档的内容，这对于清理旧上传内容非常有用。
• 拖放文件夹即可重新排序或嵌套。
• 右键单击文件夹，可选择：新建文件夹、新建子文件夹、重命名、移动到、下载、删除、排序附件。
• 将附件从网格拖到侧边栏的文件夹中。

有些看似微不足道的事情，在日常生活中却至关重要：

• 文件夹计数（显示每个文件夹中的附件数量）会随着您移动文件而实时更新，无需刷新页面。
• 搜索功能支持文件夹识别。如果您已选中某个文件夹并在搜索框中输入内容，则搜索范围仅限于该文件夹。要搜索整个库，请先点击“所有文件”。
• 侧边栏可以调整大小。如果文件夹名称较长，请拖动右侧边缘以给树状图留出更多空间。

我希望改进的一点是：网格顶部的导航栏（显示你在树状结构中的位置）太小，在文件夹间快速点击时会出现卡顿现象。这在其他方面都很简洁的界面中算是一个小小的用户体验缺陷。虽然不是什么大问题，但如果你在图书馆里待上几个小时，这点小瑕疵就会累积起来。

列表视图和文件夹列

从网格视图切换到列表视图（搜索框旁边的图标），您将看到标准的 WordPress 附件表格，其中多了一列：“文件夹”。每行附件都以可点击的标签形式显示其所属文件夹的名称。点击标签即可跳转到该文件夹​​的内容。

这是我整理文件时使用的视图。网格视图非常适合“我知道我要找什么，直接显示图片”的情况。列表视图则非常适合“显示尚未归档的 200 个 PNG 文件，并让我批量移动它们”。您可以使用标准的复选框列进行选择，然后使用“批量操作”下拉菜单，现在由于 FileBird 的加入，该下拉菜单中新增了“移动到文件夹”选项。

文件夹列排序正确。按文件夹排序，你会看到所有“背景”附件放在一起，然后是所有“博客标题”，依此类推。这虽然不是什么稀奇古怪的功能，但只有当你第一次在其他插件中遇到它不正常工作时才会注意到。

在文章编辑器中：使用 FileBird 添加媒体

这是你花费时间最多的屏幕，因为这是日常交互的界面。当你撰写文章时，点击“特色图片”按钮或在编辑器中插入图片，WordPress 媒体弹窗就会打开。

启用 FileBird 后，模态框打开时，文件夹树也会显示在模态框的左侧。您可以直接浏览到“博客标题”，而无需先滚动浏览其他内容。如果您正在处理特定类型的文章（例如 WooCommerce 产品），并且已设置文章类型插件，则选择器可以仅显示产品文件夹。

区块编辑器（Gutenberg）集成底层使用了相同的模态框，因此它可以在图像区块、图库区块以及任何会打开 WordPress 媒体选择器的第三方区块中正常工作。我测试了 Stackable、Kadence Blocks 和 GenerateBlocks，媒体选择器在所有这些区块中的行为都完全相同。

一个小细节：如果您在模态框内滚动文件夹树，滚动位置会被记住，直到模态框关闭并重新打开。您就能回到之前的位置。这只需五秒钟，但在长时间操作时却能节省大量时间。

设置、默认设置和用户文件夹

Filebird -> 设置中有一些开关选项。值得调整的选项有：

• 排序方式。默认是按字母顺序 (AZ) 排序。我将其切换为“手动”，这样我就可以按照实际使用顺序拖动文件夹，将最常用的文件夹放在顶部。
• 每页显示的文件夹数量。默认值为 20。如果文件夹数量超过 50 个，请增加此值，否则文件夹树内部会出现分页，这会让人感到非常困惑。
• 新上传文件的默认文件夹。您可以设置为“未分类”（默认）或指定一个文件夹。我通常设置为“未分类”，这样我就必须对新上传的文件进行分类，而不是让它们默默地堆积在一个我忘记查看的文件夹里。
• 通过 API 搜索。如果您的库包含 10,000 个以上的附件，请启用此功能。它会将搜索从数据库LIKE查询转移到带有分页功能的 REST 端点，这在大库中速度会显著提升。
• 用户文件夹权限。此开关可使每个 WordPress 用户仅看到自己的文件夹树。这对于客户网站非常有用，可以防止客户 A 随意查看客户 B 的营销资源。请注意，此设置仅控制文件夹的可见性，不控制附件的所有权。附件的所有权仍然归上传者所有，并且 WordPress 的标准功能仍然适用。
• 文章类型文件夹。为文章、页面或任何自定义文章类型启用文件夹。此插件底层使用真正的分类法（fbv_pt_tax_<post_type>），而不是 FileBird 的自定义表格，因为这样与文章列表表格的集成pre_get_posts更清晰。

一个小小的不足之处：设置布局虽然有所改进，但“文件夹权限”和“角色”部分仍然分散在两个不相邻的面板中。如果您正在设置客户网站，预计需要来回切换几次。与Wicked Folders Pro这类插件相比（后者角色界面更精致，但整体功能较少），FileBird 牺牲了精致度，换取了更强大的功能。

批量移动、导入和 FTP 快捷方式

有三个工作流程值得特别指出，因为它们在用户界面上并不明显。

通过列表视图批量移动。前面已经介绍过。切换到列表视图，使用复选框进行多选，选择“批量操作”->“移动到文件夹”。

从其他文件夹插件批量导入。设置 -> 工具中有一个“导入文件夹插件数据”部分，其中包含 Real Media Library、Enhanced Media Library、WP Media Folder、FolderPress 和 Polylang 分类插件的一键迁移工具。我在一个包含约 600 个附件的沙盒环境中运行了 Real Media Library 导入器，耗时约 8 秒，将每个 RML 文件夹映射到了 FileBird 中对应的文件夹。没有丢失任何文件。供应商建议先备份数据库，这个建议是正确的，但也有点奇怪，因为导入器对源插件的数据是只读的，所以最坏的情况是，如果发现问题，你需要重新运行一次。

从 FTP 导入文件。这方面的文档很少，这也是为什么你们团队通过 FTP 上传的 800 张图片备份没有出现在 FileBird 目录树中的原因。WordPress 无法识别从wp-content/uploads/外部上传的文件，因为 `<import>`wp_posts和 ` <import> wp_postmeta` 表中的元数据是在上传时创建的。FileBird 提供了一个“从服务器同步”工具，它会扫描上传目录，为 WordPress 中尚未包含的文件创建附件记录，并将它们分配到你指定的文件夹。查找方法：FileBird -> 同步。流程​​如下：

1. 在 FileBird 树中选择一个文件夹。
2. 告诉工具要扫描哪个上传子目录。
3. 跑步。

之所以这个功能在用户界面上不够显眼，可能是因为它是个隐患：单击一下就能创建数千条附件记录，一旦创建完成，就需要手动整理。如果您没有先在副本上测试导入功能，请不要一次性将数千个文件拖入新文件夹。

实际应用案例

我见过 FileBird 收取许可费的五个例子。

1. 长期运营的博客。任何运营超过两三年的博客都会有数百张特色图片和内嵌截图。FileBird 提供按年份和类别划分的文件夹。即使只是一个简单的“2023/”、“2024/”、“2025/”顶级树状结构，每个树状结构下分别包含“博客标题”、“截图”和“素材”文件夹，也能让图片库再次可搜索。

2. WooCommerce 商店。产品图片和变体图片对于扁平化图库来说是最糟糕的情况：数百个外观相似的文件，SKU 名称却晦涩难懂。为每个产品类别创建一个文件夹，并将该类别的图片设置为“所有变体”的参考图片，这样在添加重复使用图片的新产品时可以节省大量时间。

3. 代理客户网站。每个用户文件夹 + 文件夹权限 = 每个客户团队只能看到自己拥有的文件夹。当您将单个 WordPress 安装出售给多个下游客户时非常有用（例如，营销代理机构在一个多站点或一个常规安装上托管五个客户微型网站）。

4. 多作者编辑团队。同样使用用户文件夹，但原因不同：每位作者都有自己的“进行中”文件夹，用于存放图像草稿。当作品准备发布时，他们将其拖入共享的“已发布”文件夹。这种方法在扁平化库中难以实施，因为没有“私密”的存放空间。

5. 摄影师/作品集网站。文件夹对应项目或拍摄。图库模块（或 WPBakery 短代码）指向一个文件夹，因此向该文件夹添加新照片即可更新网站上的实时图库，而无需编辑任何文章或页面。这是我自己重建作品集时会使用的工作流程。

开发者参考：表格、钩子、REST、图库块

这才是开发者真正需要的部分。如果你不打算扩展 FileBird，可以略过这部分。

两张定制表格

FileBird 不使用媒体文件夹分类法。（它使用文章类型文件夹分类法，但这属于单独的插件，详见下文。）相反，它会在 MySQL 目录中创建两个自定义表Install.php：

CREATE TABLE {prefix}fbv (
  id           INT(11) UNSIGNED NOT NULL AUTO_INCREMENT,
  name         VARCHAR(250) NOT NULL,
  parent       INT(11) NOT NULL DEFAULT 0,
  type         INT(2) NOT NULL DEFAULT 0,   -- 0 folder, 1 collection
  ord          INT(11) NULL DEFAULT 0,
  created_by   INT(11) NULL DEFAULT 0,
  PRIMARY KEY (id),
  UNIQUE KEY id (id)
);

CREATE TABLE {prefix}fbv_attachment_folder (
  folder_id     INT(11) UNSIGNED NOT NULL,
  attachment_id BIGINT(20) UNSIGNED NOT NULL,
  PRIMARY KEY (folder_id, attachment_id)
);

该{prefix}fbv表保存文件夹记录。parent = 0是根文件夹；其他所有文件夹都通过引用另一个文件夹的 ID 进行嵌套。ord是手动排序顺序。created_by是文件夹创建者的用户 ID（这也是fbv_folder_created_by按用户文件夹范围筛选信息的基础）。

该{prefix}fbv_attachment_folder表是数据透视表。复合主键意味着一个附件一次只能存在于一个文件夹中。（这是一种设计选择，而非限制。多文件夹附件需要不同的架构和不同的用户体验。）

实际操作中这意味着：任何针对文件夹成员关系的查询都应该连接fbv_attachment_folder到attachment_id文件wp_posts.ID夹的附件列表。

global $wpdb;
$folder_id = 42;
$attachment_ids = $wpdb->get_col( $wpdb->prepare(
    "SELECT attachment_id FROM {$wpdb->prefix}fbv_attachment_folder
     WHERE folder_id = %d",
    $folder_id
) );

如果您之前使用过WordPress Real Media Library，那么这是一种不同的模型。RML 使用自定义分类法，而 FileBird 使用自定义表。两者都能正常工作。对于“列出文件夹 X 中的附件”这样的查询，自定义表的方法速度更快，因为它省略了term_relationships连接操作，但这意味着您无法使用 WordPress 的标准函数，例如get_object_taxonomies()枚举文件夹成员关系。

动作钩子

文件夹生命周期中会触发九个do_action钩子。以下是您真正需要的：

// After a folder is created. $insertId is the new folder ID; $data has name/parent.
add_action( 'fbv_after_folder_created', function ( $insertId, $data ) {
    error_log( "FileBird folder created: ID={$insertId}, name={$data['name']}" );
}, 10, 2 );

// After an attachment is assigned to a folder. Useful for kicking a re-render
// of any gallery that points to this folder.
add_action( 'fbv_after_assign_folder', function ( $folderId, $attachmentIds ) {
    // Bust your gallery cache, ping a webhook, whatever you need.
    do_action( 'my_site_invalidate_gallery', $folderId );
}, 10, 2 );

// Before a single attachment gets its folder set (covers single-file moves).
add_action( 'fbv_before_setting_folder', function ( $post_id, $folder_id ) {
    // E.g. log the old folder so you can build an audit trail.
}, 10, 2 );

// After a folder is renamed.
add_action( 'fbv_after_folder_renamed', function ( $folder_id, $new_name ) {
    // Update any cached folder labels (sitemaps, breadcrumbs, etc).
}, 10, 2 );

// After a folder is deleted. Note: attachments are unassigned but not deleted.
add_action( 'fbv_after_folder_deleted', function ( $id ) {
    // Clean up your own metadata tied to this folder ID.
} );

完整的操作列表：fbv_folder_parent_updated，，，，，，，，。fbv_after_assign_folder​​​fbv_before_setting_folderfbv_after_set_folderfbv_after_folder_renamedfbv_after_parent_updatedfbv_after_delete_allfbv_after_folder_createdfbv_after_folder_deleted

过滤钩子

大约有 20 个独特的apply_filters调用可以实现可调行为。以下是出现频率最高的几个：

// Toggle off the "every uploaded file auto-creates a folder by file type" behavior.
add_filter( 'fbv_auto_create_folders', '__return_false' );

// When filtering by folder, also include attachments in nested subfolders.
add_filter( 'fbv_query_include_subfolders', function ( $include, $folder_id ) {
    return $folder_id === 12 ? true : $include; // only for the "Brand assets" root
}, 10, 2 );

// Scope folders by current user. Default returns 0 (global), so all users see all folders.
// Returning the current user ID makes folders per-user. This is the heart of "per-user folders".
add_filter( 'fbv_folder_created_by', function ( $user_id ) {
    return get_current_user_id();
} );

// Disable the (relatively expensive) attachment-count query on giant libraries.
add_filter( 'fbv_speedup_get_count_query', '__return_true' );

// Block deletion of certain folders (e.g. lock the root "Client deliverables").
add_filter( 'fbv_can_delete_folder', function ( $can_delete, $folder_id ) {
    return $folder_id === 7 ? false : $can_delete;
}, 10, 2 );

// Change the filename of the "Download folder as zip" output.
add_filter( 'fbv_download_filename', function ( $zipname, $folder ) {
    return sanitize_file_name( $folder->name . '-' . date( 'Y-m-d' ) . '.zip' );
}, 10, 2 );

// Customize the list of post types the FileBird post-type addon considers.
add_filter( 'fbv_post_types', function ( $types ) {
    return array_diff( $types, array( 'attachment' ) ); // exclude attachments here
} );

这个fbv_folder_created_by过滤器值得仔细研究。返回真实的用户 ID 是实现用户级文件夹功能的关键，该值会created_by在创建文件夹时被写入相应的列中。如果在不同的请求中返回不同的值（例如，在多站点或 REST 应用中切换用户上下文），就会创建一些用户在其他会话中无法看到的文件夹。这是设计使然，但可能会出乎你的意料。

REST 端点

FileBird 在四个命名空间中注册了 48 条 REST 路由：

• filebird/v1/...涵盖文件夹 CRUD 操作、附件移动、批量操作。
• filebird/convert/v1/...运行来自其他文件夹插件的导入程序。
• filebird/pt/v1/...包含帖子类型附加路由。
• wp/v2/block-renderer/filebird/gallery是图库区块的区块渲染端点。

创建文件夹的调用非常简单，并使用标准的 WP REST nonce 进行身份验证：

fetch('/wp-json/filebird/v1/folder', {
  method: 'POST',
  headers: { 'X-WP-Nonce': wpApiSettings.nonce, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Spring 2026 launch', parent: 0 }),
  credentials: 'include'
}).then(r => r.json()).then(console.log);

完整的文件夹端点（动词和路径）都位于此处includes/Controller/FolderController.php。REST 路由没有单独的文档站点，因此源代码即为参考。

图库模块（Gutenberg + WPBakery + Elementor）

FileBird 提供了一个 Gutenberg 区块（filebird/gallery）、一个 WPBakery 短代码（[filebird_gallery]）以及一个 Elementor 小部件。这三者都基于相同的后端逻辑：选择一个文件夹，将其中的所有附件渲染成一个图库，并可选择调整列数、间距和顺序。

使用模块是最简单的方法。插入模块，点击“选择文件夹”，从树状结构中选择，就完成了。添加到该文件夹​​的新图片会自动出现在所有使用该模块的页面的图库中，无需手动更新。

短代码格式如下所示：

[filebird_gallery folder="42" columns="4" order="asc" orderby="title"]

在内部，块渲染模板会针对透视表运行此查询，并提供了一个apply_filters( 'fbv_in_not_in_where_query', ... )钩子，允许您从自己的代码中扩展 SQL 子句。这种小小的扩展钩子很容易被忽略，但在需要时却非常有用。

文章类型插件（独立模型）

令人困惑的是，“文章类型”插件（设置 -> 文章类型）并没有使用 FileBird 的自定义表格。它为每个启用的文章类型注册了一个真正的 WordPress 分类法，名为 `<taxonomy_name>` fbv_pt_tax_<post_type>。这种选择是经过深思熟虑的：它与pre_get_posts`<postslist_table_filter>` 集成，而文章列表表格筛选下拉菜单也restrict_manage_posts与 `<taxonomy_name>` 集成，并且使用分类法比使用自定义表格的钩子代码更简洁。但这样做的缺点是，任何列出分类法的插件（例如 Yoast、Rank Math以及一些站点地图插件）都会看到这些分类法，但它们可能无法正确处理。大多数插件都能正确处理，但也有少数插件无法处理，您需要通过register_taxonomy标志覆盖或相关插件的设置来排除它们。

WP-CLI

FileBird 还附带了一小部分 WP-CLI 命令。其中最实用的是：

wp filebird folder list                                       # list all folders
wp filebird folder create "Brand assets"                      # create a root folder
wp filebird folder create "Logos" --parent=42                 # create a nested folder
wp filebird attachment move 1234 --folder=42                  # assign attachment 1234 to folder 42

这些是我在为新客户站点编写初始设置脚本时常用的命令。只需在 shell 脚本中构建一次文件夹树，将其提交到配置仓库，每个新站点都会使用相同的结构。

性能、兼容性和注意事项

蜜月期过后，有几件事需要牢记。

在大文件库上的性能表现。我使用 FileBird 测试了一个包含 30,000 个附件、分布在 80 个文件夹中的文件库。与全新安装相比，初始文件库加载耗时约 180 毫秒（主要是文件夹树的加载）。文件夹切换耗时不到 100 毫秒。一次性批量移动 500 个附件大约需要 2.5 秒，速度非常快，无需等待加载完成。如果您的文件库确实非常庞大（六位数），请在设置中启用“按 API 搜索”，并考虑使用fbv_speedup_get_count_query过滤器跳过嵌套文件夹的计数查询。

与图像优化插件的兼容性。Smush Pro、ShortPixel、EWWW、Optimole 和其他上传时压缩插件都能与 FileBird 完美兼容。它们会在 FileBird 接收到文件之前接入附件上传流程，并且无需考虑文件夹位置。唯一需要注意的是按附件 ID 进行批量优化的工具：它们无法识别文件夹，因此“压缩此文件夹中的所有内容”的工作流程必须通过 FileBird 的列表视图进行操作（筛选文件夹、全选、批量操作）。

与 Elementor 的库兼容性。Elementor自身的模板库与媒体库是分开的，FileBird 不会对其进行任何修改。Elementor 构建器的媒体选择器（即在 Elementor 小部件中设置图像时看到的那个）会识别 FileBird 文件夹。如果您正在将此功能与 Elementor 的内置流程进行比较，这一点很有用。

FileBird 支持多站点功能。默认情况下，每个子站点都有自己的文件夹树（每个子站点对应一个单独的表）。FileBird 默认不支持全网文件夹，这虽然是正确的默认设置，但如果您希望在 12 个子站点之间共享一个“品牌资产”文件夹树，则可能会比较麻烦。

备份和迁移。文件夹树位于数据库中，而不是文件系统中。如果您只备份数据库wp-content/uploads/，将会丢失文件夹结构。请确保您的备份工具包含数据库，或者明确包含数据库wp_fbv和wp_fbv_attachment_folder数据库表。UpdraftPlus、BackupBuddy 和 All-in-One WP Migration 默认都包含这些表。

删除文件夹与删除附件的区别在于：删除文件夹会移除文件夹记录并取消其中所有附件的分配。附件本身不会被删除，而是会恢复到“未分类”类别。这是正确的默认设置，但第一次使用时可能会让人感到意外，尤其是在您误删了一个包含 800 张产品图片的文件夹，并以为它们会安全地保存在某个地方时。

智能自动文件夹规则。实话实说：FileBird 的“自动”归档选项比我预期的要少。它有一个“上传时自动归档”的功能（上传的文件会进入树状图中当前选中的文件夹），还有一个过滤器（fbv_auto_create_folders）可以进行微调。但它没有像“如果文件名匹配*-hero.*，则将其归档到主图文件夹”这样真正的规则引擎。如果你需要这个功能，就得自己开发一个小型插件来实现add_attachment。也许未来的版本会弥补这个缺陷。就目前而言，这是 Wicked Folders Pro 唯一胜过 FileBird 的功能。

面包屑导航的“橡皮筋”问题。之前已经提到过，但值得再次强调，因为这是我最希望修复的 bug：在侧边栏树状结构中快速点击文件夹时，面包屑导航偶尔会与网格不同步。页面刷新后即可恢复正常。这不会影响任何功能，只是看起来不够美观。

常问问题

FileBird 真的会移动磁盘上的文件吗？

不会。文件夹是虚拟的。文件仍然保留在 WordPress 上传时放置的位置（在 `<path>` 目录下wp-content/uploads/YYYY/MM/）。在文件夹之间“移动”文件实际上是对数据库表进行更新fbv_attachment_folder。这就是为什么图片 URL 和现有引用永远不会失效的原因。

我可以将一个附件放在多个文件夹中吗？

不可以。该fbv_attachment_folder表的复合主键（folder_id，attachment_id）强制规定每个附件只能放在一个文件夹中。如果您需要多文件夹功能，请查看“集合”（一项实验性功能，type=1在文件夹表中有相应的标志），或者改用 WordPress 基于分类法的Real Media Library。

如果我重新排列文件夹，图片 URL 会改变吗？

不会。无论图片位于 FileBird 的哪个文件夹中，它的 URL 都始终不变。这就是虚拟文件夹的优势所在。

FileBird 是否支持 WPML 或 Polylang 的多语言网站插件？

是的，两者都支持。WPML 需要进行一些简单的配置（如果您使用文章类型插件来翻译内容，则需要启用“使自定义文章类型可翻译”）。Polylang 则开箱即用。

我可以在 Gutenberg 图库区块中使用文件夹吗？

可以。FileBird 自带一个 Gutenberg 区块（filebird/gallery），它可以让你选择一个文件夹，并将该文件夹中的所有附件渲染成一个图库。WordPress 原生图库区块不支持文件夹，但你可以在“添加媒体”模态框中使用 FileBird 的文件夹选择器，批量选择文件夹中的图片，然后将它们拖放到标准的图库区块中。

FileBird 是否兼容 WP Smush Pro / ShortPixel / Imagify？

是的。图像优化插件会在上传时进行处理，此时 FileBird 还无法读取文件。FileBird 不会修改文件字节，因此不会产生冲突。

如果我停用 FileBird，我的文件夹会发生什么变化？

文件夹记录会保留在数据库中。文件夹界面会消失（恢复到平面媒体库）。重新激活 FileBird 后，一切都会恢复原状。通过“删除”卸载程序会在确认后删除 FileBird 的相关表。

我可以批量导入其他插件的文件夹吗？

可以。“设置”->“工具”中有 Real Media Library、Enhanced Media Library、WP Media Folder、FolderPress 和 Polylang 分类的导入器。如果您担心数据泄露，可以先在沙盒环境中运行，但请注意，这些导入器对源数据是只读的。

总结

如果朋友还没选好 WordPress 媒体库插件，而他们又想要一款速度快、功能强大且维护良好的插件，我会毫不犹豫地推荐 FileBird。它的拖放交互体验是我用过的同类插件中最好的。自定义表格存储模型非常适合这款插件所针对的那种文件夹较多的网站。Gutenberg 图库区块和文章类型插件都是实实在在的功能，并非华而不实。REST API 和钩子功能也足以满足扩展需求。

它并不完美。智能规则功能比较薄弱。面包屑导航存在一个存在已久的轻微 JavaScript bug。FTP 同步工具的文档也需要更详细的说明。但 FileBird 的优势在于它做得非常出色，而且多年来一直在持续改进。

如果你一直使用 WordPress 默认的扁平化文件库，从未创建过文件夹，不妨抽出一个小时。安装 FileBird，创建六七个文件夹，把最常用的附件拖进去，然后试用一天。你会发现，要么你会重新回到以前的工作流程（如果是这样，也无可厚非，毕竟扁平化文件库对某些人来说确实很实用），要么你会纳闷自己以前是怎么忍受没有文件夹的。