TailwindCSS v4 安全列表（safelist）实现指南

问题背景

TailwindCSS v4 已弃用传统的 JS 配置文件(tailwind.config.js)，转而推荐使用纯 CSS 配置。这一变化导致 v3 中的 safelist 属性失效——该功能原本允许开发者通过正则表达式模式和变体动态生成所需 CSS 类（如 grid-cols-* 响应式类）。在升级后，开发者面临以下问题：

// Tailwind v3 配置 (不再适用于 v4)
export default {
  safelist: [
    {
      pattern: /grid-cols-+/,  // 匹配所有 grid-cols 类
      variants: ["sm", "md", "lg", "xl"],  // 包含响应式变体
    },
  ],
}

核心需求保持不变：如何在 Tailwind v4 中安全动态生成未在源码中显式使用的实用类，同时避免全量导入导致 CSS 体积膨胀？

解决方案：@source inline() (v4.1+)

从 TailwindCSS v4.1.0 开始，官方引入了 @source inline() 指令，完美替代原 safelist 功能。

基本语法与示例

在 CSS 配置文件中直接声明需生成类：

/* 基础单类声明 */
@source inline('underline');

/* 包含响应式变体的网格类生成 (1-12列) */
@source inline('{sm:,md:,lg:,xl:,}grid-cols-{{1..12}}');

▸ 在 Tailwind Playground 中测试网格类生成效果

进阶模式匹配

支持复杂表达式组合，满足多样化需求：

1. 混合离散值与范围

/* 生成 grid-cols-1 和 10-90 (步长5) */
@source inline('{sm:,md:,lg:,xl:,}grid-cols-{1,{10..90..5}}');

▸ 测试混合模式

2. 多类型工具类生成

/* 生成所有边距/内边距工具类 (1-10) */
@source inline("{m,p}{x,y,t,b,l,r}-{1..10}");

▸ 测试边距工具类

3. 响应式容器宽度

/* 生成响应式 max-width 类 */
@source inline("{sm:,md:,lg:,xl:,2xl:,}max-w-{sm,md,lg,xl,2xl,3xl,4xl,5xl,6xl,7xl}");

关键语法规则

1. 变体处理
   在变体后添加 ,（如 sm:,）表示同时生成基础类：

   /* 生成 hover:bg-red-500 和 bg-red-500 */
   @source inline('{hover:,}bg-red-500');

2. 数值范围
   使用 {start..end..step} 格式：

   /* 生成 bg-red-100 到 bg-red-900 (步长100) */
   @source inline('bg-red-{{100..900..100}}');

3. 多项声明
   每个 @source inline() 只接受一个模式串：

   /* 正确做法：分开声明 */
   @source inline('underline');
   @source inline('hover:bg-blue-500');

体积优化警告

过度使用 safelist 会显著增大 CSS 文件：

• 仅添加必要的动态类
• 精确指定范围（避免 {1..100} 宽泛设置）
• 定期审计生成结果

特殊场景处理

Tailwind v4.0.17 及更早版本

在 v4.1 前无官方 safelist 方案，临时替代方法:

1. HTML 占位法
   在 DOM 中隐藏使用动态类：

   <div class="hidden sm:grid-cols-1 md:grid-cols-2 lg:grid-cols-3"></div>

2. CSS @apply 注入
   在样式文件中强制应用：

   .placeholder {
     @apply sm:grid-cols-1 md:grid-cols-2 lg:grid-cols-3;
   }

3. 外部文件生成方案
   通过脚本生成类名文件并引入：

   // generate-classes.js
   import fs from 'fs';
   const classes = ['grid-cols-1', 'grid-cols-2' /*...*/];
   fs.writeFileSync('safelist.txt', classes.join('\n'));

   /* CSS 引入 */
   @source "safelist.txt";

主题变量静态化 (有限场景)

对 CSS 变量场景，可使用 @theme static 强制生成：

@theme static {
  --color-primary: var(--color-red-500);
  --spacing-md: 1rem;
}

▸ 见官方文档

最佳实践建议

1. 版本升级
   推荐至少升级到 v4.1.0 获得完整 safelist 支持：

   npm install tailwindcss@^4.1.0

2. 动态类合并
   对复杂模式拆分成独立声明：

   /* 分开声明可读性更高 */
   @source inline('grid-cols-{{1..12}}');
   @source inline('md:grid-cols-{{1..6}}');

3. 生产环境检查
   使用 npx tailwindcss -o output.css --analyze 分析 CSS 体积变化。

官方资源：

• Safelist 功能文档
• 实现原理讨论

通过 @source inline() 可实现精细化控制，平衡动态类需求和性能优化。