# 无需 Node 的Tailwind v4

每个页面只会编译自身用到的类，并在PHP中完成。

## 一个设置，无需构建

在 `blockstudio.json` 中设置 `tailwind.enabled`，然后在任意模板中编写实用类。每次前端请求时，Blockstudio都会收集最终HTML中的类候选项，并通过PHP（Tailwind CSS 4.3 的TailwindPHP移植版）仅编译这些类。

没有Node.js、没有CLI，也没有监视器。区块模板、主题模板、插件和 `the_content` 中的类都会计入，因为系统会扫描整个页面。

[启用Tailwind](https://blockstudio.dev/zh/docs/tailwind/#enabling-tailwind)

blockstudio.json

```
{
  "tailwind": {
    "enabled": true
  }
}
```

## 无需 Node 运行时

TailwindPHP会在请求期间编译，无需构建或部署任何内容。

## Tailwind 4.3 实用类

Tailwind CSS 4.3 中的实用类、变体、任意值和指令。

## 扫描整个页面

最终HTML中出现的类都会计入。

## 按类集缓存

使用相同类的页面共用一个编译文件。

## CSS 优先配置

在blockstudio.json或筛选器中设置@theme令牌和@utility规则。

## 编辑器实时预览

随附的浏览器构建版本可在输入时预览类。

## 链接式输出

一个内容哈希样式表，浏览器和边缘缓存都可以保留。

## 排版和表单

这两个官方插件已移植到PHP，并通过 @plugin 加载。

## 在CSS中配置

Tailwind v4通过CSS配置，而非JavaScript文件。在 `tailwind.config` 中放入 `@theme` 令牌、`@utility` 规则和层，或者在这些内容跨越多行时，通过 `blockstudio/tailwind/css` 筛选器追加。

官方的排版和表单插件已移植到PHP，并通过 `@plugin` 加载。仅以JavaScript包形式存在的插件无法运行，因为这里不会执行 Node。

类别名是 `@layer utilities` 内的 `@apply` 规则，例如由内边距和圆角实用类构成的 `.btn`。这些规则在前端和编辑器预览中都会编译。

[配置](https://blockstudio.dev/zh/docs/tailwind/#configuration)

functions.php

```
add_filter('blockstudio/tailwind/css', function (string $css): string {
  return $css . '
    @plugin "@tailwindcss/typography";
    @theme { --color-brand: #4f46e5; }
    @utility container-narrow {
      max-width: 48rem;
      margin-inline: auto;
    }
  ';
});
```

## 将类作为字段

为 `classes` 字段提供 `"tailwind": true`，编辑者即可从完整类列表中获得自动补全；随附的Tailwind浏览器构建版本还会在画布中预览每次更改。

使用 `assets.reset.enabled` 后，画布还会恢复 `flex`、`grid` 和 `sticky` 等显示与定位实用类，否则这些类会被编辑器包装器规则覆盖。

[类字段类型](https://blockstudio.dev/zh/docs/tailwind/#classes-field-type)

block.json

```
{
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      {
        "id": "classes",
        "type": "classes",
        "label": "Classes",
        "tailwind": true,
        "default": "bg-white text-gray-900"
      }
    ]
  }
}
```

## 一个样式表，按类集缓存

编译后的CSS会缓存在磁盘上，缓存键由页面排序后的类候选项和CSS输入构成，因此随机数和时间戳不会使缓存失效，使用相同类的页面也会共用一个文件。

默认采用内联输出。`"output": "link"` 会改为将该缓存文件作为内容哈希样式表输出。在2026 October 8 对本网站的本地副本进行测量时，首页大小从 451,648 降至 296,379 字节，HTML。

当 `cache.path` 指向私有卷时，Blockstudio 会改用内联 CSS，除非 `blockstudio/files/url` 过滤器针对 `tailwind` 范围返回公共 URL，例如 CDN 主机。

[前端输出](https://blockstudio.dev/zh/docs/tailwind/#frontend-output)

blockstudio.json

```
{
  "tailwind": {
    "enabled": true,
    "output": "link"
  }
}
```

## 在PHP中合并类

`bs_tw_merge()` 会解决相互冲突的实用类，让作者编写的类优先于默认类。`bs_tw_variants()` 会返回一个变体调用函数，支持基础类、变体、默认值和复合变体。

两者都使用TailwindPHP引擎Blockstudio已内置的版本，因此主题无需自带副本。

[模板助手](https://blockstudio.dev/zh/docs/tailwind/#template-composition-helpers)

index.php

```
echo bs_tw_merge('px-2 text-sm', 'px-4');
// text-sm px-4

$button = bs_tw_variants([
  'base' => 'inline-flex items-center',
  'variants' => [
    'size' => ['sm' => 'h-8 px-3', 'lg' => 'h-12 px-6'],
  ],
  'defaultVariants' => ['size' => 'sm'],
]);

echo $button(['size' => 'lg', 'class' => 'rounded']);
```

## 按需清除

Runtime_Cache::purge(‘tailwind’) 会清除已编译的 CSS，下一个请求会重新编译。

## 可选页面缓冲

既不使用 Tailwind 也不使用区块资源的网站，可以通过 blockstudio/buffer/enabled 过滤器关闭页面缓冲。

## 按来源隔离

使用逻辑发现来源时，选定来源和运行时上下文会一并纳入缓存命名空间，因此预览之间不会泄漏上次成功的 CSS。

## 规范的层级顺序

主题、基础、组件，然后是实用类，与 Tailwind CSS 中的顺序相同，因此后面的层会覆盖前面的层。

Plus

## 官方扩展套件

高级站点模板、AI 系统指令和私人 Discord 社区。一次购买，终身更新。

- 500+ 个网站模板
- AI 系统指令
- 终身更新
- 私有 Discord 社区

[获取 Plus](https://blockstudio.dev/zh/plus/)
