重新思考我们如何自定义 UI

问题

创建一个文档框架并不具有挑战性，最棘手的问题是如何让它完美适合每个人，从用户和开发者的角度来看。 毫无疑问，这对所有框架，甚至库作者来说都是一个困境——你无法编写通用的代码，让它开箱即用，没有任何软件可以通用且直接可用。

例如，无头 UI 库如 Radix UI 向我们引入了通用 UI 组件的概念：裸露的 UI 原语，我们可以根据自己的美学进行自定义。 然而，你需要时间来调整它们，这些原语在没有进一步自定义的情况下是无法使用的。

是的，现在是 2025 年，Shadcn UI 引领了 Web 开发领域的“革命”。它是无头 UI 和样式化默认值的绝妙结合，又往前迈了一步！ 但我们的问题依然未解，当绝大多数新站点采用 Shadcn UI 时，它再次变得“无样式”可能显得荒谬。

就我个人而言，我对几乎相同、随处可见的扁平设计感到不知所措，这些设计显然是 Shadcn UI 默认样式之一。这与 Shadcn UI 无关，而是那些并不真正关心美学和独特性的其他开发者。 最终，类似 Shadcn 的设计成为了默认样式，因此，我们再次需要做更多工作来让它看起来时尚。

我们该做什么？

作为一个从**“灵活性”**出发的文档框架，Fumadocs 必须是可自定义的，调整以满足开发者的偏好。 如果 DX 是我们的目标，我们需要认真对待自定义。最重要的是，它应该鼓励那些具有美感意识的开发者进行自定义。

解决方案

通常，有两种类型的开发者：

那些希望文档只需工作即可的人

Fumadocs 默认需要有明确的观点，这样它就可以立即可用，我们只需提供最简单的选项来更改细节（例如颜色、覆盖组件）。

大多数开发者没有欲望安装数十个组件只是为了更改一个小细节，这使得 Shadcn 方法不是最优的。

那些需要根据自己的偏好量身定制完美文档的人

Fumadocs 的核心，或者我们追求的精神是后者。我创建了 Fumadocs CLI，这是专为 Fumadocs 设计的 Shadcn UI 版本，整个解决方案现在简化成一个命令：

npx @fumadocs/cli customise

它考虑了两种类型：

• 当暴露的选项不足时，自定义默认样式。
• 从零开始创建自己的布局。

第一种显而易见，人们总会有我们甚至未考虑过的荒谬需求。 我们可以安装原始组件，因此它完全与他们一直在使用的默认 UI 相同。

第二种更简单，我们可以提供他们可以开始自定义的最小模板。

这种受 ejection 启发的方法带来了些许不错的优势：

升级 Fumadocs 时不会破坏任何东西

Fumadocs 需要有明确的观点。因此，我们需要频繁迭代 UI，这显然会破坏人们的 hacky 自定义。 Fumadocs CLI 的魅力在于，一旦你安装了布局，它将永远保持不变，无论 Fumadocs UI 的未来迭代如何。

这赋予了 Fumadocs UI 迭代的勇气，以及开发者自定义的勇气，而不受升级依赖的恐惧影响。

看起来干净

就像 Shadcn UI 和 Radix UI 一样，Fumadocs UI 有一个核心包（fumadocs-core），大多数通用逻辑将由核心抽象。

接下来是什么？

Shadcn UI 的创新令人惊叹，然而，我相信 Fumadocs 可以解决更多问题。

参见 Flags SDK 和 BetterAuth，你无法一眼看出它们是否由 Fumadocs 驱动。 我希望它能继续成为一个“可破坏”的框架，以其高度可自定义性而闻名。