# weapp-tailwindcss API 与配置参考

> 包含插件配置、API 细节、常见问题与迁移指南，适合回答配置/兼容性问题。

This file contains all documentation content in a single document following the llmstxt.org standard.

## weapp-tailwindcss


## 配置项

- [UserDefinedOptions 总览](interfaces/UserDefinedOptions.md)
- [✅ 重要配置](options/important.md)
- [🧩 文件匹配](options/matchers.md)
- [🧭 生命周期](options/lifecycle.md)
- [⚙️ 一般配置](options/general.md)

## 接口

- [🗂️ 其他接口](other-interfaces.md)

---

## ApplyOptions


Tailwind 运行时行为配置。

## 属性

### overwrite?

> 可选 | **overwrite**: `boolean`

是否允许覆盖已有运行时缓存或上下文状态。

***

### exposeContext?

> 可选 | **exposeContext**: `boolean | ExposeContextOptions`

是否暴露运行时 Tailwind context，或配置具体暴露方式。

***

### extendLengthUnits?

> 可选 | **extendLengthUnits**: `false | ExtendLengthUnitsOptions`

扩展长度单位支持，传入 `false` 可完全关闭。

---

## CacheOptions


Tailwind 类名缓存配置。

## 属性

### enabled?

> 可选 | **enabled**: `boolean`

是否启用缓存。

***

### cwd?

> 可选 | **cwd**: `string`

解析缓存路径时使用的工作目录。

***

### dir?

> 可选 | **dir**: `string`

缓存文件写入目录。

***

### file?

> 可选 | **file**: `string`

缓存文件名。未传入时，会在推导出的缓存目录下使用 `class-cache.json`。

***

### strategy?

> 可选 | **strategy**: `CacheStrategy`

新类名列表与已有缓存合并时使用的策略。

***

### driver?

> 可选 | **driver**: `CacheDriver`

缓存持久化方式。默认使用 `file`。

---

## ExtractOptions


类名提取结果的输出配置。

## 属性

### write?

> 可选 | **write**: `boolean`

是否写出提取结果文件。

***

### file?

> 可选 | **file**: `string`

输出文件路径，可传绝对路径或相对路径。

***

### format?

> 可选 | **format**: `"json" | "lines"`

输出格式。未传入时使用 JSON。

***

### pretty?

> 可选 | **pretty**: `number | boolean`

JSON 格式化缩进。传入可判定为真的值会启用缩进。

***

### removeUniversalSelector?

> 可选 | **removeUniversalSelector**: `boolean`

是否从最终列表中移除通配选择器 `*`。

---

## TailwindCssOptions


按 Tailwind 版本划分的运行时配置。

## 属性

### config?

> 可选 | **config**: `string`

Tailwind 配置文件路径。自动识别不够准确时可以显式传入。

***

### cwd?

> 可选 | **cwd**: `string`

解析 Tailwind 配置相对路径时使用的工作目录。

***

### postcssPlugin?

> 可选 | **postcssPlugin**: `string`

自定义 PostCSS 插件名称。未传入时使用默认名称。

***

### version?

> 可选 | **version**: `4`

当前项目使用的 Tailwind CSS 主版本。未传入时会从已安装包推断。

***

### packageName?

> 可选 | **packageName**: `string`

Tailwind 包名。项目使用分支包时可以改这里。

***

### resolve?

> 可选 | **resolve**: `PackageResolvingOptions`

传给 `local-pkg` 的包解析配置。

***

### v4?

> 可选 | **v4**: [`TailwindV4Options`](./TailwindV4Options.md)

Tailwind CSS v4 提取与 CSS 入口选项。

#### base?

> 可选 | **base**: `string`

解析 v4 内容来源与配置时使用的基准目录。
#### css?

> 可选 | **css**: `string`

直接传给 v4 设计系统的原始 CSS。
#### cssSources?

> 可选 | **cssSources**: `TailwindV4CssSource[]`

构建器在 CSS 落盘前捕获的内存 CSS 入口。
#### cssEntries?

> 可选 | **cssEntries**: `string[]`

Tailwind CSS 4 入口文件列表，用于识别入口中的 `@import "tailwindcss"`、`@source` 与 `@config`。入口 CSS 仍然需要被项目实际 import 或纳入构建图，`cssEntries` 不会替代框架生成该 CSS 资产。

类型上保持可选，是为了兼容内存 CSS 来源；业务项目应显式传入绝对路径。多入口、分包、独立分包、Webpack/Gulp/自定义构建和多平台构建都应该写清楚这些入口。
#### sources?

> 可选 | **sources**: `SourceEntry[]`

覆盖 oxide 扫描器默认扫描的内容来源。
#### bareArbitraryValues?

> 可选 | **bareArbitraryValues**: `boolean | { units?: string[]; }`

是否启用 UnoCSS 风格的裸任意值，例如 `p-10%`、`p-2.5px`。

---

## TailwindCssRuntimeOptions


Tailwind CSS 运行时根配置。

## 属性

### projectRoot?

> 可选 | **projectRoot**: `string`

解析 Tailwind 资源时使用的项目根目录。默认是 `process.cwd()`。

***

### tailwindcss?

> 可选 | **tailwindcss**: [`TailwindCssOptions`](./TailwindCssOptions.md)

Tailwind 运行时配置。

#### config?

> 可选 | **config**: `string`

Tailwind 配置文件路径。自动识别不够准确时可以显式传入。
#### cwd?

> 可选 | **cwd**: `string`

解析 Tailwind 配置相对路径时使用的工作目录。
#### postcssPlugin?

> 可选 | **postcssPlugin**: `string`

自定义 PostCSS 插件名称。未传入时使用默认名称。
#### version?

> 可选 | **version**: `4`

当前项目使用的 Tailwind CSS 主版本。未传入时会从已安装包推断。
#### packageName?

> 可选 | **packageName**: `string`

Tailwind 包名。项目使用分支包时可以改这里。
#### resolve?

> 可选 | **resolve**: `PackageResolvingOptions`

传给 `local-pkg` 的包解析配置。
#### v4?

> 可选 | **v4**: [`TailwindV4Options`](./TailwindV4Options.md)

Tailwind CSS v4 提取与 CSS 入口选项。

***

### apply?

> 可选 | **apply**: [`ApplyOptions`](./ApplyOptions.md)

运行时行为开关。

#### overwrite?

> 可选 | **overwrite**: `boolean`

是否允许覆盖已有运行时缓存或上下文状态。
#### exposeContext?

> 可选 | **exposeContext**: `boolean | ExposeContextOptions`

是否暴露运行时 Tailwind context，或配置具体暴露方式。
#### extendLengthUnits?

> 可选 | **extendLengthUnits**: `false | ExtendLengthUnitsOptions`

扩展长度单位支持，传入 `false` 可完全关闭。

***

### extract?

> 可选 | **extract**: [`ExtractOptions`](./ExtractOptions.md)

类名提取结果输出配置。

#### write?

> 可选 | **write**: `boolean`

是否写出提取结果文件。
#### file?

> 可选 | **file**: `string`

输出文件路径，可传绝对路径或相对路径。
#### format?

> 可选 | **format**: `"json" | "lines"`

输出格式。未传入时使用 JSON。
#### pretty?

> 可选 | **pretty**: `number | boolean`

JSON 格式化缩进。传入可判定为真的值会启用缩进。
#### removeUniversalSelector?

> 可选 | **removeUniversalSelector**: `boolean`

是否从最终列表中移除通配选择器 `*`。

***

### filter()?

> 可选 | **filter()**: `(className: string) => boolean`

过滤最终类名的函数。

#### 参数

##### className

`string`

#### 返回

`boolean`

***

### cache?

> 可选 | **cache**: `boolean | CacheOptions`

缓存配置。传入布尔值可快速启用或关闭。

---

## TailwindV4Options


Tailwind CSS v4 提取配置。

## 属性

### base?

> 可选 | **base**: `string`

解析 v4 内容来源与配置时使用的基准目录。

***

### css?

> 可选 | **css**: `string`

直接传给 v4 设计系统的原始 CSS。

***

### cssSources?

> 可选 | **cssSources**: `TailwindV4CssSource[]`

构建器在 CSS 落盘前捕获的内存 CSS 入口。

***

### cssEntries?

> 可选 | **cssEntries**: `string[]`

Tailwind CSS 4 入口文件列表，用于识别入口中的 `@import "tailwindcss"`、`@source` 与 `@config`。入口 CSS 仍然需要被项目实际 import 或纳入构建图，`cssEntries` 不会替代框架生成该 CSS 资产。

类型上保持可选，是为了兼容内存 CSS 来源；业务项目应显式传入绝对路径。多入口、分包、独立分包、Webpack/Gulp/自定义构建和多平台构建都应该写清楚这些入口。

***

### sources?

> 可选 | **sources**: `SourceEntry[]`

覆盖 oxide 扫描器默认扫描的内容来源。

***

### bareArbitraryValues?

> 可选 | **bareArbitraryValues**: `boolean | { units?: string[]; }`

是否启用 UnoCSS 风格的裸任意值，例如 `p-10%`、`p-2.5px`。

---

## UserDefinedOptions

## 分组入口

- [✅ 重要配置](../options/important.md) (20)
- [🧩 文件匹配](../options/matchers.md) (7)
- [🧭 生命周期](../options/lifecycle.md) (4)
- [⚙️ 一般配置](../options/general.md) (6)

---

## WeappTailwindcssGenerateOptions


weapp-tailwindcss 生成器的调用配置。

## 属性

### target?

> 可选 | **target**: [`WeappTailwindcssGeneratorTarget`](./WeappTailwindcssGeneratorTarget.md)

生成目标。`weapp` 输出小程序兼容 CSS，`web` 保留 Web 形态，`tailwind` 返回 Tailwind 原始输出。

***

### styleOptions?

> 可选 | **styleOptions**: `Partial<IStyleHandlerOptions>`

传给小程序 CSS 兼容转换器的额外配置。

***

### candidates?

> 可选 | **candidates**: `Iterable<string>`

***

### sources?

> 可选 | **sources**: `TailwindV4CandidateSource[]`

***

### incrementalCache?

> 可选 | **incrementalCache**: `boolean`

是否启用增量生成缓存。

***

### bareArbitraryValues?

> 可选 | **bareArbitraryValues**: `boolean | { units?: string[]; }`

是否启用 UnoCSS 风格的裸任意值，例如 `p-10%`、`p-2.5px`。

***

### scanSources?

> 可选 | **scanSources**: `boolean | TailwindV4SourcePattern[]`

是否扫描文件系统中的源码入口。

---

## WeappTailwindcssGenerateResult


weapp-tailwindcss 生成器的输出结果。

## 属性

### classSet

> **classSet**: `Set<string>`

***

### rawCandidates

> **rawCandidates**: `Set<string>`

***

### dependencies

> **dependencies**: `string[]`

***

### sources

> **sources**: `TailwindV4SourcePattern[]`

***

### root

> **root**: `TailwindV4CompiledSourceRoot`

***

### css

> **css**: `string`

转换后的 CSS。

***

### rawCss

> **rawCss**: `string`

Tailwind 原始输出 CSS。

***

### incrementalCss?

> 可选 | **incrementalCss**: `string`

本次增量新增的转换后 CSS。

***

### incrementalRawCss?

> 可选 | **incrementalRawCss**: `string`

本次增量新增的 Tailwind 原始 CSS。

***

### target

> **target**: `"weapp" | "web"`

实际生成目标。

---

## WeappTailwindcssGenerator


weapp-tailwindcss 统一生成器实例。

## 属性

### generate()

> **generate()**: `(options?: WeappTailwindcssGenerateOptions) => Promise<WeappTailwindcssGenerateResult>`

生成目标 CSS。

#### 参数

##### options?

[`WeappTailwindcssGenerateOptions`](./WeappTailwindcssGenerateOptions.md)

#### 返回

`Promise<WeappTailwindcssGenerateResult>`

***

### loadDesignSystem()

> **loadDesignSystem()**: `() => Promise<TailwindV4DesignSystem>`

#### 返回

`Promise<TailwindV4DesignSystem>`

***

### validateCandidates()

> **validateCandidates()**: `(candidates: Iterable<string>) => Promise<Set<string>>`

#### 参数

##### candidates

`Iterable<string>`

#### 返回

`Promise<Set<string>>`

***

### source

> **source**: `TailwindV4ResolvedSource`

解析后的 Tailwind v4 source。

#### cwd?

> 可选 | **cwd**: `string`
#### projectRoot

> **projectRoot**: `string`
#### cssSources?

> 可选 | **cssSources**: `TailwindV4CssSource[]`
#### sources?

> 可选 | **sources**: `TailwindV4SourcePattern[]`

---

## WeappTailwindcssGeneratorTarget


## 属性

### length

> **length**: `number`

---

## WeappTailwindcssPostcssPluginOptions


`weapp-tailwindcss` PostCSS 插件配置。

## 属性

### projectRoot?

> 可选 | **projectRoot**: `string`

***

### base?

> 可选 | **base**: `string`

***

### css?

> 可选 | **css**: `string`

***

### packageName?

> 可选 | **packageName**: `string`

***

### generator?

> 可选 | **generator**: `WeappTailwindcssPostcssGeneratorUserOptions`

生成器配置，用于控制目标端和 Tailwind 配置路径。

***

### config?

> 可选 | **config**: `string`

Tailwind 配置文件路径。

***

### postcssPlugin?

> 可选 | **postcssPlugin**: `string`

Tailwind PostCSS 插件名称。

***

### candidates?

> 可选 | **candidates**: `Iterable<string>`

额外传入的候选类名。

***

### scanSources?

> 可选 | **scanSources**: `boolean`

是否扫描 Tailwind v4 源码入口中的候选类名。

***

### sources?

> 可选 | **sources**: `TailwindCandidateSource[]`

额外传入的 Tailwind v4 内联候选来源。

***

### styleOptions?

> 可选 | **styleOptions**: `Partial<IStyleHandlerOptions>`

传给小程序 CSS 兼容转换器的额外配置。

---

## WeappTailwindcssStyleInjectorOptions


## 属性

### imports?

> 可选 | **imports**: `string[]`

***

### perFileImports()?

> 可选 | **perFileImports()**: `PerFileImportResolver`

#### 参数

##### fileName

`string`

#### 返回

`string | string[] | null | undefined`

***

### dedupe?

> 可选 | **dedupe**: `boolean`

***

### pagesJsonPath?

> 可选 | **pagesJsonPath**: `string | string[]`

uni-app 的 `pages.json` 路径。未传入时，uni-app 预设会按当前工作目录探测 `src/pages.json` 与 `pages.json`。

***

### appConfigPath?

> 可选 | **appConfigPath**: `string | string[]`

Taro 的 `app.config` 路径。未传入时，Taro 预设会按当前工作目录探测常见配置文件。

***

### appPath?

> 可选 | **appPath**: `string | string[]`

Mpx 的 app 配置路径。未传入时，Mpx 预设会按当前工作目录探测 `src/app.mpx`、`app.mpx` 等入口。

***

### sourceRoot?

> 可选 | **sourceRoot**: `string`

Mpx 源码根目录。

***

### subPackages?

> 可选 | **subPackages**: `UniAppSubPackageConfig | UniAppSubPackageConfig[] | TaroSubPackageConfig | TaroSubPackageConfig[] | MpxSubPackageConfig | MpxSubPackageConfig[]`

框架分包样式配置。

***

### uniAppSubPackages?

> 可选 | **uniAppSubPackages**: `UniAppSubPackageConfig | UniAppSubPackageConfig[]`

uni-app 通用分包配置。

***

### uniAppStyleScopes?

> 可选 | **uniAppStyleScopes**: `UniAppManualStyleConfig | UniAppManualStyleConfig[]`

uni-app 手动样式作用域配置。

***

### subpackageStyleScopes?

> 可选 | **subpackageStyleScopes**: `ResolvedSubpackageStyleScope[]`

已解析的分包样式作用域。通常只在需要完全接管预设解析时使用。

***

### generateSubpackageStyle()?

> 可选 | **generateSubpackageStyle()**: `SubpackageStyleGenerator | ((context: SubpackageStyleGenerateContext) => string | Uint8Array | null | undefined | Promise<string | Uint8Array | null | undefined>)`

生成分包样式入口内容。

#### 参数

##### context

`SubpackageStyleGenerateContext`

#### 返回

`string | Uint8Array<ArrayBufferLike> | Promise<string | Uint8Array<ArrayBufferLike> | null | undefined> | null | undefined`

***

### loadSubpackageTargetStyle()?

> 可选 | **loadSubpackageTargetStyle()**: `((fileName: string, sourceAbsolutePath: string) => string | Uint8Array | null | undefined | Promise<string | Uint8Array | null | undefined>)`

加载由源码模块推导出的目标样式内容。Webpack 场景必须同步返回。

#### 参数

##### fileName

`string`

##### sourceAbsolutePath

`string`

#### 返回

`string | Uint8Array<ArrayBufferLike> | Promise<string | Uint8Array<ArrayBufferLike> | null | undefined> | null | undefined`

***

### sourceFileName?

> 可选 | **sourceFileName**: `string | string[]`

分包样式源文件名。

***

### outputName?

> 可选 | **outputName**: `string`

分包样式输出名。

***

### files?

> 可选 | **files**: `string | string[]`

限定需要注入分包入口的目标文件。

***

### include?

> 可选 | **include**: `string | string[]`

分包目标文件 include 规则。

***

### exclude?

> 可选 | **exclude**: `string | string[]`

分包目标文件 exclude 规则。

***

### styleScopes?

> 可选 | **styleScopes**: `UniAppStyleScopeInput | UniAppStyleScopeInput[]`

uni-app 样式作用域配置。

***

### rules?

> 可选 | **rules**: `SubpackageStyleRules`

框架预设的分包样式注入规则，用样式入口到目标产物的映射描述注入关系。

#### 示例

```ts
rules: {
  'tailwind.css': ['pages/index.wxss'],
  'components.css': ['components/card.wxss'],
}
```

***

### preprocess?

> 可选 | **preprocess**: `boolean`

生成分包入口前是否走框架预处理。

---

## ⚙️ 一般配置

本页收录 6 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [cssSourceTrace](#csssourcetrace) | <code>CssSourceTraceUserOptions</code> | <code>false</code> | 在输出 CSS 中为工具类规则标注 token 来源文件。 |
| [babelParserOptions](#babelparseroptions) | <code>(Partial & { cache?: boolean &#124; undefined; cacheKey?: string &#124; undefined; cacheMaxEntries?: number &#124; undefined; cacheMaxSourceLength?: number &#124; undefined; })</code> | — | `@babel/parser` 的配置选项。 |
| [experimentalJsFastPath](#experimentaljsfastpath) | <code>boolean &#124; "oxc"</code> | — | 实验性 JS 转译快路径。 |
| [postcssOptions](#postcssoptions) | <code>Partial></code> | — | `postcss` 的配置选项。 |
| [tailwindcssRuntimeOptions](#tailwindcssruntimeoptions) | [`TailwindCssRuntimeOptions`](../interfaces/TailwindCssRuntimeOptions.md) | — | 自定义 Tailwind CSS 运行时参数。 |
| [logLevel](#loglevel) | <code>"info" &#124; "warn" &#124; "error" &#124; "silent"</code> | — | 控制命令行日志输出级别。 |

## 详细说明

### cssSourceTrace

> 可选 | 类型: `CssSourceTraceUserOptions` | 默认值: `false`

在输出 CSS 中为工具类规则标注 token 来源文件。

#### 备注

默认关闭。开启后会在生成的 CSS 规则前插入 `tokens: token <= source-file` 注释，
用于排查某条工具类来自哪个源码文件。可传入 `{ root }` 控制注释里的相对路径基准。
该能力面向调试与 demo 验收，生产构建通常保持关闭以减少产物体积。

#### 默认值

```ts
false
```

### babelParserOptions

> 可选 | 类型: `(Partial<Options> & { cache?: boolean | undefined; cacheKey?: string | undefined; cacheMaxEntries?: number | undefined; cacheMaxSourceLength?: number | undefined; })` | 版本: ^3.2.0

`@babel/parser` 的配置选项。

### experimentalJsFastPath

> 可选 | 类型: `boolean | "oxc"`

实验性 JS 转译快路径。

#### 备注

当前仅在调用侧关闭 source map，且没有模块图、模块替换、ignore 调用/标签模板语义时尝试 OXC。
`weapp-tailwindcss@5.2.0` 起要求 Node `>=22.12.0`。OXC 加载失败时仍会自动回退到 Babel。

### postcssOptions

> 可选 | 类型: `Partial<Omit<Result, "file">>` | 版本: ^3.2.0

`postcss` 的配置选项。

### tailwindcssRuntimeOptions

> 可选 | 类型: [`TailwindCssRuntimeOptions`](../interfaces/TailwindCssRuntimeOptions.md)

自定义 Tailwind CSS 运行时参数。

### logLevel

> 可选 | 类型: `"info" | "warn" | "error" | "silent"`

控制命令行日志输出级别。

#### 备注

默认 `info`，可设置为 `silent` 屏蔽全部输出。

---

## ✅ 重要配置

本页收录 20 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [supportCustomLengthUnits](#supportcustomlengthunits) | <code>boolean &#124; LengthUnitsRuntimeOptions</code> | — | 控制 Tailwind 自定义长度单位支持。 |
| [appType](#apptype) | <code>AppType</code> | — | 声明所使用的框架类型。 |
| [arbitraryValues](#arbitraryvalues) | <code>IArbitraryValues</code> | — | TailwindCSS 任意值的相关配置。 |
| [unocss](#unocss) | <code>boolean &#124; IUnocssCompatibilityOptions</code> | <code>false</code> | 启用部分 UnoCSS class 写法兼容。 |
| [jsPreserveClass](#jspreserveclass) | <code>(keyword: string) => boolean &#124; undefined</code> | — | 控制 JS 字面量是否需要保留。 |
| [disabled](#disabled) | <code>boolean &#124; { plugin?: boolean &#124; undefined; }</code> | — | 是否禁用此插件。 |
| [replaceRuntimePackages](#replaceruntimepackages) | <code>boolean &#124; Record<string, string></code> | — | 是否替换运行时依赖包名。 |
| [rewriteCssImports](#rewritecssimports) | <code>boolean</code> | <code>false</code> | 是否把 CSS 中的 Tailwind 包入口改写到 `weapp-tailwindcss` 内部样式入口。 |
| [customAttributes](#customattributes) | <code>ICustomAttributes</code> | — | 自定义 `wxml` 标签属性的转换规则。 |
| [customReplaceDictionary](#customreplacedictionary) | <code>Record<string, string></code> | <code>MappingChars2String</code> | 自定义 class 名称的替换字典。 |
| [generator](#generator) | <code>WeappTailwindcssGeneratorUserOptions</code> | — | 控制 Tailwind CSS 直接生成目标端 CSS 的策略。 |
| [ignoreTaggedTemplateExpressionIdentifiers](#ignoretaggedtemplateexpressionidentifiers) | <code>(string &#124; RegExp)[]</code> | <code>['weappTwIgnore']</code> | 忽略指定标签模板表达式中的标识符。 |
| [styleInjector](#styleinjector) | <code>WeappTailwindcssStyleInjectorUserOptions</code> | <code>false</code> | 开启构建产物样式入口注入。 |
| [ignoreCallExpressionIdentifiers](#ignorecallexpressionidentifiers) | <code>(string &#124; RegExp)[]</code> | — | 忽略指定调用表达式中的标识符。 |
| [disabledDefaultTemplateHandler](#disableddefaulttemplatehandler) | <code>boolean</code> | <code>false</code> | 禁用默认的 `wxml` 模板替换器。 |
| [tailwindcssBasedir](#tailwindcssbasedir) | <code>string</code> | — | 指定用于获取 Tailwind 上下文的路径。 |
| [cache](#cache) | <code>boolean &#124; ICreateCacheReturnType</code> | — | 控制缓存策略。 |
| [cssOptions](#cssoptions) | <code>CssOptions</code> | — | CSS 生成与兼容后处理的微调配置。 |
| [tailwindcss](#tailwindcss) | [`TailwindCssOptions`](../interfaces/TailwindCssOptions.md) | — | 为不同版本的 Tailwind 配置行为。 |
| [cssEntries](#cssentries) | <code>string[]</code> | — | 指定 tailwindcss@4 的入口 CSS。 |

## 详细说明

### supportCustomLengthUnits

> 可选 | 类型: `boolean | LengthUnitsRuntimeOptions`

控制 Tailwind 自定义长度单位支持。

#### 参阅

https://github.com/sonofmagic/weapp-tailwindcss/issues/110

#### 备注

TailwindCSS 3.2.0 起对任意值执行长度单位校验，会将未声明的 `rpx` 识别为颜色。本选项默认开启，并由构建运行时自动接管。

### appType

> 可选 | 类型: `AppType`

声明所使用的框架类型。

#### 备注

用于区分框架运行环境。Vite 产物样式关系会优先从构建图和真实 bundle 文件中推导，不应依赖固定的主样式文件名。

### arbitraryValues

> 可选 | 类型: `IArbitraryValues`

TailwindCSS 任意值的相关配置。

### unocss

> 可选 | 类型: `boolean | IUnocssCompatibilityOptions` | 默认值: `false`

启用部分 UnoCSS class 写法兼容。

#### 备注

默认关闭。传入 `true` 后会启用 Tailwind CSS v4 裸任意值生成。class 字符转义继续由
`customReplaceDictionary` 控制，JS 转译仍遵循 `classNameSet` 精确命中原则。

#### 默认值

```ts
false
```

### jsPreserveClass

> 可选 | 类型: `(keyword: string) => boolean | undefined` | 版本: ^2.6.1

控制 JS 字面量是否需要保留。

#### 备注

当 Tailwind 与 JS 字面量冲突时，可通过回调返回 `true` 保留当前值，返回 `false` 或 `undefined` 则继续转义。默认保留所有带 `*` 的字符串字面量。

#### 参数

##### keyword

`string`

#### 返回

`boolean | undefined`

### disabled

> 可选 | 类型: `boolean | { plugin?: boolean | undefined; }`

是否禁用此插件。

#### 备注

`disabled` 只适合完全不希望插件参与的构建，例如 RN、Harmony、独立原生或自定义构建。

uni-app / uni-app x / Taro / Mpx / Weapp-vite 的 H5/Web 与普通 App WebView 构建通常应继续保留插件；
生成器会根据平台环境变量自动切换到 `web` 输出。自定义环境无法注入平台变量时，
请优先显式设置 `generator.target: 'web'`，而不是禁用插件。

#### 示例

```ts
// Taro RN 或其他完全不希望插件参与的构建
import process from 'node:process'

const disabled = process.env.TARO_ENV === 'rn'

import { WeappTailwindcss } from 'weapp-tailwindcss/webpack'

new WeappTailwindcss({
  disabled,
})
```

### replaceRuntimePackages

> 可选 | 类型: `boolean | Record<string, string>`

是否替换运行时依赖包名。

#### 备注

适用于运行时包名需要重定向的场景，例如：
- 小程序侧无法直接安装 `tailwind-merge`/`class-variance-authority`/`tailwind-variants`，需要替换为内置的 weapp 版本。
- 企业内私有镜像/多包发布导致运行时包名不同，希望在转换后统一到目标包名。
传入 `true` 使用内置替换表，或传入对象自定义映射。

#### 示例

```ts
replaceRuntimePackages: {
  'tailwind-merge': '@weapp-tailwindcss/merge',
  'class-variance-authority': '@weapp-tailwindcss/cva',
}
```

### rewriteCssImports

> 可选 | 类型: `boolean` | 默认值: `false`

是否把 CSS 中的 Tailwind 包入口改写到 `weapp-tailwindcss` 内部样式入口。

#### 备注

默认关闭。Tailwind CSS v4 项目应保留 `@import "tailwindcss"` 原始入口，由
`weapp-tailwindcss` 基于 CSS AST/source 结果生成目标端 CSS。仅在需要兼容旧项目
或特定框架无法正常解析 Tailwind 包入口时显式开启。

#### 默认值

```ts
false
```

### customAttributes

> 可选 | 类型: `ICustomAttributes`

自定义 `wxml` 标签属性的转换规则。

#### 备注

默认会转换所有标签上的 `class` 与 `hover-class`。此配置允许通过 `Map` 或对象为特定标签指定需要转换的属性字符串或正则表达式数组。
- 使用 `'*'` 作为键可为所有标签追加通用规则。
- 支持传入 `Map<string | RegExp, (string | RegExp)[]>` 以满足复杂匹配需求。
- 常见场景包括通过组件 `prop` 传递类名，或对三方组件的自定义属性做匹配，更多讨论见 [issue#129](https://github.com/sonofmagic/weapp-tailwindcss/issues/129#issuecomment-1340914688) 与 [issue#134](https://github.com/sonofmagic/weapp-tailwindcss/issues/134#issuecomment-1351288238)。
如果自定义规则已经覆盖默认的 `class`/`hover-class`，可开启 [`disabledDefaultTemplateHandler`](/docs/api/options/important#disableddefaulttemplatehandler) 以关闭内置模板处理器。

#### 示例

```js
const customAttributes = {
  '*': [/[A-Za-z]?[A-Za-z-]*[Cc]lass/],
  'van-image': ['custom-class'],
  'ice-button': ['testClass'],
}
```

### customReplaceDictionary

> 可选 | 类型: `Record<string, string>` | 默认值: `MappingChars2String`

自定义 class 名称的替换字典。

#### 备注

默认策略会将小程序不允许的字符映射为等长度的替代字符串，因此无法通过结果反推出原始类名。如需完全自定义，可传入 `Record<string, string>`，只需确保生成的类名不会与已有样式冲突。示例参考 [dic.ts](https://github.com/sonofmagic/weapp-core/blob/main/packages/escape/src/dic.ts)。

#### 默认值

```ts
MappingChars2String
```

### generator

> 可选 | 类型: `WeappTailwindcssGeneratorUserOptions`

控制 Tailwind CSS 直接生成目标端 CSS 的策略。

#### 备注

默认值会按构建环境推断：小程序构建使用 `weapp`，H5/Web 与普通 uni-app App WebView 使用 `web`。
uni-app x 原生 App 目标继续通过 `uniAppX` 配置处理 uvue/App 约束，不需要配置 `target: 'app'`。

#### Web 兼容模式

`generator.webCompat` 用于 Web/H5 与经典 uni-app App WebView 目标下的 Tailwind CSS v4 兼容降级。自动推断 `generator.target: "web"` 时默认开启，uni-app 的 `app` / `app-plus` 构建也会自动启用；如果显式配置了 `generator.target`，则以用户传入的 `webCompat` 为准。

传入 `true` 等价于 `{ preset: "legacy-web" }`，该预设面向 Web Compact 输出，兼容基线为 `Chrome/91.0.4472.114` 与 `AppleWebKit/537.36`。它会移除或降级 `@theme`、`@layer`、`@property`、嵌套规则、`oklch()`、现代颜色函数与相关 `@supports` 包裹，并补充 `-webkit-background-clip: text`，同时保留 Tailwind CSS v4 的运行时间距变量语义。需要保持 Tailwind CSS 官方 Web 输出时，可传入 `false` 或 `{ preset: "off" }`。

```ts
WeappTailwindcss({
  generator: {
    target: "web",
    webCompat: true,
  },
})
```

### ignoreTaggedTemplateExpressionIdentifiers

> 可选 | 类型: `(string | RegExp)[]` | 默认值: `['weappTwIgnore']` | 版本: ^4.0.0

忽略指定标签模板表达式中的标识符。

#### 备注

当模板字符串被这些标识符包裹时，将跳过转义处理。

#### 默认值

```ts
['weappTwIgnore']
```

### styleInjector

> 可选 | 类型: `WeappTailwindcssStyleInjectorUserOptions` | 默认值: `false`

开启构建产物样式入口注入。

#### 备注

默认关闭。传入 `true` 等价于启用空配置；传入对象时会透传给内置
`weapp-style-injector` 实现，可配置 `imports`、`perFileImports`、分包样式入口等能力。

Vite 会按当前 `appType` 自动选择 uni-app、Taro 或通用预设；Webpack 会按当前
`appType` 自动选择 uni-app、Taro、Mpx、Weapp-vite 或通用预设。未显式配置 `appType` 时，会复用
`weapp-tailwindcss` 在当前构建器中的推断结果。

当 `disabled: true` 或 `disabled: { plugin: true }` 时，该能力会跟随主插件一起关闭。

#### 默认值

```ts
false
```

### ignoreCallExpressionIdentifiers

> 可选 | 类型: `(string | RegExp)[]` | 版本: ^4.0.0

忽略指定调用表达式中的标识符。

#### 备注

使用这些方法包裹的模板字符串或字符串字面量会跳过转义，常与 `@weapp-tailwindcss/merge` 配合（如 `['twMerge', 'twJoin', 'cva']`）。

### disabledDefaultTemplateHandler

> 可选 | 类型: `boolean` | 默认值: `false` | 版本: ^2.6.2

禁用默认的 `wxml` 模板替换器。

#### 备注

启用后模板匹配完全交由 [`customAttributes`](/docs/api/options/important#customattributes) 管理，需要自行覆盖默认的 `class` / `hover-class` 等匹配规则。

#### 默认值

```ts
false
```

### tailwindcssBasedir

> 可选 | 类型: `string` | 版本: ^2.9.3

指定用于获取 Tailwind 上下文的路径。

#### 备注

在 linked 或 monorepo 场景下可手动指向目标项目的 `package.json` 所在目录。

### cache

> 可选 | 类型: `boolean | ICreateCacheReturnType` | 版本: ^3.0.11

控制缓存策略。

### cssOptions

> 可选 | 类型: `CssOptions` | 版本: ^4.3.4

CSS 生成与兼容后处理的微调配置。

#### 备注

后续用于控制生成 CSS 的兼容兜底、变量保留、规则修剪等细粒度行为。
`cssPreflight`、`cssPreflightRange`、`cssChildCombinatorReplaceValue`、`cssPresetEnv`、`autoprefixer`、
`atRules`、`injectAdditionalCssVarScope`、`cssSelectorReplacement`、`rem2rpx`、`px2rpx`、`unitsToPx`、
`unitConversion`、`platform`、`cssRemoveActivePseudoClass`、`cssRemoveHoverPseudoClass`、`cssRemoveFocusPseudoClass`、`cssRemoveProperty`、`cssCalc`
与 `tailwindcssV4GradientFallback` 都推荐放在这里。

#### 小程序默认移除 `:active` 与 `:focus`

小程序本身不支持 CSS `:active` 与 `:focus` 伪类，因此 `cssOptions.cssRemoveActivePseudoClass` 和 `cssOptions.cssRemoveFocusPseudoClass` 均默认为 `true`。Tailwind CSS v4 仍会识别对应 candidate，模板和 JS 类名也会正常转成安全类，但小程序最终样式不会包含对应 selector。H5 与 App 的 Web 构建不执行这项删除。

不需要使用 `@source not inline("active:*")`：`@source not inline()` 排除的是完整 candidate，`active:*` 不是变体通配表达式。

如果某个自定义小程序运行时确实支持这些伪类，可以显式恢复：

```ts
WeappTailwindcss({
  cssOptions: {
    cssRemoveActivePseudoClass: false,
    cssRemoveFocusPseudoClass: false,
  },
})
```

同一条小程序兼容边界也会默认删除 `focus-visible`、`focus-within`、`disabled`、`enabled`、`checked`、`required`、`optional`、`valid`、`invalid`、`visited`、`target` 等依赖浏览器状态的选择器。`first`、`last`、`nth-*` 等结构选择器以及 Tailwind 为兼容性生成的 `:is`、`:where`、`:not` 不在此清理范围内。

#### `@custom-variant` 的跨平台条件

Tailwind CSS v4 的任意 `@custom-variant` 都支持 uni-app 条件编译，条件注释放在变体内部或包住整个变体，效果相同：

```css
@custom-variant active {
  &:active {
    /* #ifndef MP */
    @slot;
    /* #endif */
  }
}
```

```css
/* #ifndef MP */
@custom-variant active {
  &:active {
    @slot;
  }
}
/* #endif */
```

这项兼容不限定变体名称，`active`、`any-hover`、`wx` 以及项目自定义的其他 `@custom-variant` 都会按目标平台处理。条件表达式支持 `#ifdef`、`#ifndef` 及现有 uni-app 平台别名。

### tailwindcss

> 可选 | 类型: [`TailwindCssOptions`](../interfaces/TailwindCssOptions.md) | 版本: ^4.0.0

为不同版本的 Tailwind 配置行为。

### cssEntries

> 可选 | 类型: `string[]` | 版本: ^4.2.6

指定 tailwindcss@4 的入口 CSS。

#### 备注

等价于设置 `tailwindcss.v4.cssEntries`。Tailwind CSS 4 项目应显式配置入口 CSS 的绝对路径；多入口、分包、独立分包、Webpack/Gulp/自定义构建和多平台构建都应该写清楚这些入口。`cssEntries` 只负责入口识别，入口样式文件仍然要被项目实际 import 或纳入构建图。

虽然类型上是可选项，但业务项目不应依赖入口推断作为长期配置契约。显式配置可以避免某些平台产物名、CSS 合并策略或分包输出差异导致 Tailwind CSS 生成不完整。

---

## 🧭 生命周期

本页收录 4 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [onLoad](#onload) | <code>(() => void)</code> | — | 插件 `apply` 初始调用时触发。 |
| [onStart](#onstart) | <code>(() => void)</code> | — | 开始处理前触发。 |
| [onUpdate](#onupdate) | <code>(filename: string, oldVal: string, newVal: string) => void</code> | — | 匹配并修改文件后触发。 |
| [onEnd](#onend) | <code>(() => void)</code> | — | 结束处理时触发。 |

## 详细说明

### onLoad

> 可选 | 类型: `(() => void)`

插件 `apply` 初始调用时触发。

#### 返回

`void`

### onStart

> 可选 | 类型: `(() => void)`

开始处理前触发。

#### 返回

`void`

### onUpdate

> 可选 | 类型: `(filename: string, oldVal: string, newVal: string) => void`

匹配并修改文件后触发。

#### 参数

##### filename

`string`

##### oldVal

`string`

##### newVal

`string`

#### 返回

`void`

### onEnd

> 可选 | 类型: `(() => void)`

结束处理时触发。

#### 返回

`void`

---

## 🧩 文件匹配

本页收录 7 个配置项，来源于 `UserDefinedOptions`。

## 配置一览

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| [htmlMatcher](#htmlmatcher) | <code>(name: string) => boolean</code> | — | 匹配需要处理的 `wxml` 等模板文件。 |
| [cssMatcher](#cssmatcher) | <code>(name: string) => boolean</code> | — | 匹配需要处理的 `wxss` 等样式文件。 |
| [jsMatcher](#jsmatcher) | <code>(name: string) => boolean</code> | — | 匹配需要处理的编译后 `js` 文件。 |
| [transform](#transform) | <code>TransformOptions</code> | — | 控制哪些源码模块或产物需要进入 `weapp-tailwindcss` 转译流程。 |
| [mainCssChunkMatcher](#maincsschunkmatcher) | <code>(name: string, appType?: AppType) => boolean</code> | — | 声明负责承载 Tailwind CSS 全局变量作用域的 CSS Bundle。 |
| [wxsMatcher](#wxsmatcher) | <code>(name: string) => boolean</code> | <code>()=>false</code> | 匹配各端的 `wxs`/`sjs`/`.filter.js` 文件。 |
| [inlineWxs](#inlinewxs) | <code>boolean</code> | <code>false</code> | 是否转义 `wxml` 中的内联 `wxs`。 |

## 详细说明

### htmlMatcher

> 可选 | 类型: `(name: string) => boolean`

匹配需要处理的 `wxml` 等模板文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

### cssMatcher

> 可选 | 类型: `(name: string) => boolean`

匹配需要处理的 `wxss` 等样式文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

### jsMatcher

> 可选 | 类型: `(name: string) => boolean`

匹配需要处理的编译后 `js` 文件。

#### 参数

##### name

`string`

#### 返回

`boolean`

### transform

> 可选 | 类型: `TransformOptions`

控制哪些源码模块或产物需要进入 `weapp-tailwindcss` 转译流程。

#### 备注

该配置只影响 `weapp-tailwindcss` 的 HTML/CSS/JS 转译，不影响 Tailwind CSS `@source`/content token 扫描。
Vite 构建中 JS chunk 会基于 Rollup `moduleIds`/`modules` 判断源码模块；当一个 JS chunk 不满足 `include` 或所有源码模块都命中 `exclude` 时，跳过该 chunk 的 JS AST 转译。
HTML/CSS asset 会优先基于 Rollup `originalFileName`/`originalFileNames` 判断，缺失时使用输出文件名兜底。
`exclude` 优先级高于 `include`；多来源产物只有全部来源都命中 `exclude` 时才整体跳过。

#### 示例

```ts
transform: {
  include: ['src/**.{wxml,js,ts,vue,css,scss}'],
  exclude: ['src/generated/**', /\/openapi\//],
}
```

### mainCssChunkMatcher

> 可选 | 类型: `(name: string, appType?: AppType) => boolean`

声明负责承载 Tailwind CSS 全局变量作用域的 CSS Bundle。

#### 备注

默认不根据框架、平台或文件名推断主样式。需要主样式语义时，应由用户按当前构建图中的真实产物名显式返回 `true`。
可结合 `appType`、环境变量或框架配置自行区分不同端。

#### 参数

##### name

`string`

##### appType?

`AppType`

#### 返回

`boolean`

### wxsMatcher

> 可选 | 类型: `(name: string) => boolean` | 默认值: `()=>false`

匹配各端的 `wxs`/`sjs`/`.filter.js` 文件。

#### 备注

配置前请确保在 `tailwind.config.js` 的 `content` 中包含对应格式。

#### 默认值

```ts
()=>false
```

#### 参数

##### name

`string`

#### 返回

`boolean`

### inlineWxs

> 可选 | 类型: `boolean` | 默认值: `false`

是否转义 `wxml` 中的内联 `wxs`。

#### 备注

使用前同样需要在 `tailwind.config.js` 中声明 `wxs` 格式。

#### 默认值

```ts
false
```

#### 示例

```html
<!-- index.wxml -->
<wxs module="inline">
// 我是内联wxs
// 下方的类名会被转义
  var className = "after:content-['我是className']"
  module.exports = {
    className: className
  }
</wxs>
<wxs src="./index.wxs" module="outside"/>
<view><view class="{{inline.className}}"></view><view class="{{outside.className}}"></view></view>
```

---

## 🗂️ 其他接口

以下接口用于补充配置或运行时能力，本页面仅提供索引。

- [ApplyOptions](./interfaces/ApplyOptions.md) - Tailwind 运行时行为配置。
- [CacheOptions](./interfaces/CacheOptions.md) - Tailwind 类名缓存配置。
- [ExtractOptions](./interfaces/ExtractOptions.md) - 类名提取结果的输出配置。
- [TailwindCssOptions](./interfaces/TailwindCssOptions.md) - 按 Tailwind 版本划分的运行时配置。
- [TailwindCssRuntimeOptions](./interfaces/TailwindCssRuntimeOptions.md) - Tailwind CSS 运行时根配置。
- [TailwindV4Options](./interfaces/TailwindV4Options.md) - Tailwind CSS v4 提取配置。
- [WeappTailwindcssGenerateOptions](./interfaces/WeappTailwindcssGenerateOptions.md) - weapp-tailwindcss 生成器的调用配置。
- [WeappTailwindcssGenerateResult](./interfaces/WeappTailwindcssGenerateResult.md) - weapp-tailwindcss 生成器的输出结果。
- [WeappTailwindcssGenerator](./interfaces/WeappTailwindcssGenerator.md) - weapp-tailwindcss 统一生成器实例。
- [WeappTailwindcssGeneratorTarget](./interfaces/WeappTailwindcssGeneratorTarget.md)
- [WeappTailwindcssPostcssPluginOptions](./interfaces/WeappTailwindcssPostcssPluginOptions.md) - `weapp-tailwindcss` PostCSS 插件配置。
- [WeappTailwindcssStyleInjectorOptions](./interfaces/WeappTailwindcssStyleInjectorOptions.md)

---

## css 中使用 @apply 警告问题


## 解决方案

我们以 `vscode` 为例

1. 创建 `.vscode` 目录

然后在目录下创建 `settings.json` 和 `tailwind.json`

2. 修改 `settings.json` 添加

```jsn
{
  "css.customData": [".vscode/tailwind.json"]
}
```

3. 修改 `tailwind.json`

````json
{
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@tailwind",
      "description": "Use the `@tailwind` directive to insert Tailwind's `base`, `components`, `utilities` and `screens` styles into your CSS.",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#tailwind"
        }
      ]
    },
    {
      "name": "@apply",
      "description": "Use the `@apply` directive to inline any existing utility classes into your own custom CSS. This is useful when you find a common utility pattern in your HTML that you’d like to extract to a new component.",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#apply"
        }
      ]
    },
    {
      "name": "@responsive",
      "description": "You can generate responsive variants of your own classes by wrapping their definitions in the `@responsive` directive:\n```css\n@responsive {\n  .alert {\n    background-color: #E53E3E;\n  }\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#responsive"
        }
      ]
    },
    {
      "name": "@screen",
      "description": "The `@screen` directive allows you to create media queries that reference your breakpoints by **name** instead of duplicating their values in your own CSS:\n```css\n@screen sm {\n  /* ... */\n}\n```\n…gets transformed into this:\n```css\n@media (min-width: 640px) {\n  /* ... */\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#screen"
        }
      ]
    },
    {
      "name": "@variants",
      "description": "Generate `hover`, `focus`, `active` and other **variants** of your own utilities by wrapping their definitions in the `@variants` directive:\n```css\n@variants hover, focus {\n   .btn-brand {\n    background-color: #3182CE;\n  }\n}\n```\n",
      "references": [
        {
          "name": "Tailwind Documentation",
          "url": "https://tailwindcss.com/docs/functions-and-directives#variants"
        }
      ]
    }
  ]
}
````

这样 `@apply` 就不会报错了。

## 参考文档

https://github.com/tailwindlabs/tailwindcss/discussions/5258

---

## 默认盒模型(box-sizing)问题


`Tailwindcss` 默认会把所有的元素的盒模型，设置为 `border-box`

但是一些组件库，比如 `wot-design-uni`，实现使用的是 `content-box` ，一切换到 `border-box` 高度塌陷了， 所以会导致部分显示效果错乱。

> `box-sizing: border-box;` 这行样式是在 'tailwindcss/base' 中的，所以你禁用这行代码，感觉上生效了，但是这样不是很好的解决方案。

假如你要从插件层面解决问题，只要做出如下修改:

```js
WeappTailwindcss({
  // 添加这一行配置即可
  cssOptions: {
    cssPreflight: {
      'box-sizing': false,
    },
  },
}),
```

这样就可以把 `box-sizing` 这个样式给去掉，但是你这样就要去评估原先那些依赖盒模型的样式是否会受到影响：

比如 `w-2`, `h-4` 都是盒子模型潜在的影响。

## 参考文档

https://tw.icebreaker.top/docs/api/options/important#cssoptions

https://github.com/sonofmagic/weapp-tailwindcss/issues/604

---

## CSS 变量失效问题


## 问题的现象

在 `Taro`、`uni-app` 等小程序项目中，可能会遇到 Tailwind CSS 变量丢失的问题。

常见表现是渐变类名没有效果。例如下面这些类名在模拟器里没有背景色：

```jsx
<View className='h-14 bg-gradient-to-r from-cyan-500 to-blue-500'></View>
<View className='h-14 bg-gradient-to-r from-sky-500 to-indigo-500'></View>
<View className='h-14 bg-gradient-to-r from-violet-500 to-fuchsia-500'></View>
<View className='h-14 bg-gradient-to-r from-purple-500 to-pink-500'></View>
```

## 原因与处理方式

这些工具类依赖 Tailwind 生成的 CSS 变量。如果最终的 `app.wxss` / `app.css` 里没有变量初始化区域，渐变、阴影、ring、transform 等样式就可能失效。参阅[什么是 Tailwind CSS 变量初始化区域](#什么是-tailwind-css-变量初始化区域)。

一个常见场景是 Taro 项目同时使用 `@tarojs/plugin-html`，构建过程中把 Tailwind 的变量初始化区域删掉了。

可以先在 `WeappTailwindcss` 的 `cssOptions` 里开启：

```ts
WeappTailwindcss({
  cssOptions: {
    injectAdditionalCssVarScope: true,
  },
})
```

代码片段和配置详情详见[和 NutUI 一起使用](./use-with-nutui)。

## 设置成功后的效果

设置成功之后的效果如下所示，可以观察一下左侧的效果，和右下角的 `inspect` 面板作为参考

![小程序生效图片](./css-vars.jpg)

## 什么是 Tailwind CSS 变量初始化区域

在 `app.wxss` 样式产物文件中（例如 Taro 或 uni-app 的 `dist` 目录），通常会有一块 Tailwind 变量初始化 CSS。

如果这块区域被删掉，依赖 CSS 变量的工具类就会出问题。

```css
::before,::after {
  --tw-content: "";
}
view,text,::before,::after {
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  --tw-skew-x: 0;
  --tw-skew-y: 0;
  --tw-scale-x: 1;
  --tw-scale-y: 1;
  --tw-pan-x:  ;
  --tw-pan-y:  ;
  --tw-pinch-zoom:  ;
  --tw-scroll-snap-strictness: proximity;
  --tw-gradient-from-position:  ;
  --tw-gradient-via-position:  ;
  --tw-gradient-to-position:  ;
  --tw-ordinal:  ;
  --tw-slashed-zero:  ;
  --tw-numeric-figure:  ;
  --tw-numeric-spacing:  ;
  --tw-numeric-fraction:  ;
  --tw-ring-inset:  ;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-color: rgb(59 130 246 / 0.5);
  --tw-ring-offset-shadow: 0 0 #0000;
  --tw-ring-shadow: 0 0 #0000;
  --tw-shadow: 0 0 #0000;
  --tw-shadow-colored: 0 0 #0000;
  --tw-blur:  ;
  --tw-brightness:  ;
  --tw-contrast:  ;
  --tw-grayscale:  ;
  --tw-hue-rotate:  ;
  --tw-invert:  ;
  --tw-saturate:  ;
  --tw-sepia:  ;
  --tw-drop-shadow:  ;
  --tw-backdrop-blur:  ;
  --tw-backdrop-brightness:  ;
  --tw-backdrop-contrast:  ;
  --tw-backdrop-grayscale:  ;
  --tw-backdrop-hue-rotate:  ;
  --tw-backdrop-invert:  ;
  --tw-backdrop-opacity:  ;
  --tw-backdrop-saturate:  ;
  --tw-backdrop-sepia:  ;
  box-sizing: border-box;
  border-width: 0;
  border-style: solid;
  border-color: currentColor;
}
::backdrop {
  --tw-border-spacing-x: 0;
  --tw-border-spacing-y: 0;
  --tw-translate-x: 0;
  --tw-translate-y: 0;
  --tw-rotate: 0;
  --tw-skew-x: 0;
  --tw-skew-y: 0;
  --tw-scale-x: 1;
  --tw-scale-y: 1;
  --tw-pan-x:  ;
  --tw-pan-y:  ;
  --tw-pinch-zoom:  ;
  --tw-scroll-snap-strictness: proximity;
  --tw-gradient-from-position:  ;
  --tw-gradient-via-position:  ;
  --tw-gradient-to-position:  ;
  --tw-ordinal:  ;
  --tw-slashed-zero:  ;
  --tw-numeric-figure:  ;
  --tw-numeric-spacing:  ;
  --tw-numeric-fraction:  ;
  --tw-ring-inset:  ;
  --tw-ring-offset-width: 0px;
  --tw-ring-offset-color: #fff;
  --tw-ring-color: rgb(59 130 246 / 0.5);
  --tw-ring-offset-shadow: 0 0 #0000;
  --tw-ring-shadow: 0 0 #0000;
  --tw-shadow: 0 0 #0000;
  --tw-shadow-colored: 0 0 #0000;
  --tw-blur:  ;
  --tw-brightness:  ;
  --tw-contrast:  ;
  --tw-grayscale:  ;
  --tw-hue-rotate:  ;
  --tw-invert:  ;
  --tw-saturate:  ;
  --tw-sepia:  ;
  --tw-drop-shadow:  ;
  --tw-backdrop-blur:  ;
  --tw-backdrop-brightness:  ;
  --tw-backdrop-contrast:  ;
  --tw-backdrop-grayscale:  ;
  --tw-backdrop-hue-rotate:  ;
  --tw-backdrop-invert:  ;
  --tw-backdrop-opacity:  ;
  --tw-backdrop-saturate:  ;
  --tw-backdrop-sepia:  ;
}
```

这块区域是 Tailwind 入口展开后生成的变量初始化代码，来自 `@import "tailwindcss";` 对应的生成结果。

丢失这块区域会导致 `bg-gradient-to-r` 这类依赖 CSS 变量的工具类失效。

---

## 使用 doctor 命令诊断项目配置


当项目出现样式未生成、JS 中的 class 未转义、CSS 入口没有被扫描、插件没有在目标端生效等问题时，可以先运行 `doctor` 命令收集项目配置状态。

```bash npm2yarn
npx weapp-tailwindcss doctor
```

如果你不在项目根目录，可以通过 `--cwd` 指定业务项目目录：

```bash npm2yarn
npx weapp-tailwindcss doctor --cwd ./packages/miniprogram
```

## 检查内容

`doctor` 命令只读取本地项目文件，不会修改项目配置。当前会检查以下内容：

| 检查项 | 说明 |
| --- | --- |
| `package.json` | 确认命令是否运行在项目根目录 |
| Node.js | 检查当前 Node.js 是否满足最低版本要求 |
| 包管理器 | 识别 `packageManager`、`pnpm-lock.yaml`、`package-lock.json` 或 `yarn.lock` |
| `weapp-tailwindcss` | 检查当前项目是否安装本插件 |
| `tailwindcss` | 检查 Tailwind CSS 是否可解析，并尽量读取实际安装版本 |
| Tailwind 配置 | 检查 `tailwind.config.*` 是否存在 |
| PostCSS 配置 | 检查 `postcss.config.*` 是否存在 |
| 生成模式配置 | 检查 v5 项目是否应移除 Tailwind 官方 PostCSS / Vite 生成插件 |
| 框架依赖 | 识别 Taro、uni-app、MPX、Remax |
| 构建器配置 | 识别 `vite.config.*` 或 `webpack.config.*` |

## 输出说明

普通输出适合人工排查：

```bash npm2yarn
npx weapp-tailwindcss doctor
```

JSON 输出适合在 issue、CI 或自动化脚本中使用：

```bash npm2yarn
npx weapp-tailwindcss doctor --json
```

严格模式会在存在 `warn` 或 `error` 时返回非零退出码，适合放在项目检查脚本中：

```bash npm2yarn
npx weapp-tailwindcss doctor --strict
```

## 常见诊断结果

### 未检测到 package.json

说明命令大概率没有运行在项目根目录。请切换到业务项目根目录后重试，或者使用 `--cwd` 指定目录。

```bash npm2yarn
npx weapp-tailwindcss doctor --cwd ./demo/uni-app-vue3-vite
```

### 未检测到 tailwindcss

说明当前项目没有安装 `tailwindcss`，或者依赖无法从当前目录解析。请先确认依赖安装完成，再重新运行诊断命令。

### 生成模式项目仍注册 Tailwind 官方生成插件

`weapp-tailwindcss@5` 默认由 `WeappTailwindcss` 构建器插件接管 Tailwind CSS 生成。小程序构建里不要再同时注册 `@tailwindcss/postcss` 或 `@tailwindcss/vite`。

如果项目已有 `postcss.config.*`，只保留业务自己的非 Tailwind 插件。Tailwind CSS 4.x 的入口 CSS 使用 `@import "tailwindcss"` 与 `@source`；应通过 `cssEntries` 显式传给 `WeappTailwindcss`，并使用项目根目录解析出的绝对路径。`cssEntries` 不是替代 import 的开关，入口 CSS 仍然要被框架纳入构建图。

### 未检测到 tailwind.config.*

Tailwind CSS 4 支持 CSS-first 配置，未检测到 `tailwind.config.*` 不一定是问题。如果 JS 字符串中的 class 没有被识别，需要检查 CSS 入口中的 `@source`。

当前文档仅维护 Tailwind CSS 4 接入说明。

## issue 反馈建议

提交 issue 时，建议附上以下信息：

```bash npm2yarn
npx weapp-tailwindcss doctor --json
```

同时补充：

| 信息 | 示例 |
| --- | --- |
| 框架 | Taro / uni-app / MPX / 原生小程序 |
| 构建器 | Vite / Webpack / Gulp |
| Tailwind CSS 版本 | v4 |
| 目标端 | 微信小程序 / H5 / App / 鸿蒙 |
| 复现命令 | `pnpm dev:mp-weixin` |

这样可以更快判断问题属于依赖安装、Tailwind 扫描范围、PostCSS 注册、插件禁用条件还是小程序端限制。

---

## 组件外部样式类（externalClasses）的支持

:::warning 快速结论
如果在自定义组件里写了 `my-class="bg-[#fafa00] text-[40px]"`，但调试器里看到变成了 `my-class="bg- #fafa00  text- 40px"` 并导致样式失效，请在插件配置中为 `customAttributes` 显式声明 `my-class`。
:::

## 典型现象

在封装原生自定义组件时经常会用到外部样式类（`externalClasses`）。例如：

```js
/* custom-component.js */
Component({
  externalClasses: ['my-class'],
})
```

在页面里直接使用 `tailwindcss` 工具类：

```html
<custom-component my-class="bg-[#fafa00] text-[40px]" />
```

小程序开发者工具会把 `my-class` 中的样式拆开成 `bg- #fafa00  text- 40px`，最终导致样式全部失效。

## 根本原因

插件默认只会转译 `class` 和 `hover-class`。外部样式类属于自定义属性，如果没有配置 [`customAttributes`](/docs/api/options/important#customattributes)，就不会被识别处理。

## 解决方案

在插件选项里增加自定义属性的映射即可：

```js
customAttributes: {
  '*': ['my-class'],
}
```

- `*` 代表匹配所有标签，你也可以改成具体的标签名或正则表达式。
- 支持传入 `Object` 或 `Map`，用于灵活地映射标签与属性的关系。

:::tip 多个外部样式类
如果组件同时暴露 `['my-class', 'title-class']`，直接把它们都写进同一个数组即可。
:::

## 扩展阅读

- 微信官方文档：[外部样式类](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#外部样式类)
- 插件配置项说明：[customAttributes](/docs/api/options/important#customattributes)

> 使用正则进行自定义匹配标签时，需要传入一个 `Map`，其中正则作为 `key`，数组作为 `value`。

---

## Tailwindcss 格式化


## prettier 插件

> 这是官方提供的包，

使用并在 `prettier` 注册 [`prettier-plugin-tailwindcss`](https://www.npmjs.com/package/prettier-plugin-tailwindcss)

## eslint 插件

使用并在 `eslint` 注册 [`eslint-plugin-tailwindcss`](https://www.npmjs.com/package/eslint-plugin-tailwindcss)

---

## group 和 peer 使用限制


## group 使用注意事项

在 `tailwindcss` 中，我们常常会这样写:

```html
<div class="group">
  <view class="bg-pink-400 group-hover:bg-yellow-400">
    group tapped
  </view>
</div>
```

这样在最外层的 `div` 进入 `hover` 状态时，内部的子元素中的 `group-hover` 就会生效，从而改变样式。

然而，在小程序中，伪类 `:hover` 是不起作用的，取而代之的是 `hover-class` 这样一个属性，所以这种情况我们可以这么写：

```html
<view class="group" hover-class="tapped">
  <view class="bg-pink-400 group-[.tapped]:bg-yellow-400">
    group tapped
  </view>
</view>
```

这样在 `group` 进入 `hover` 状态时，`bg-yellow-400` 就会生效了。

相关 issue：[#14](https://github.com/sonofmagic/uni-app-vite-vue3-tailwind-vscode-template/issues/14)

## peer 使用注意事项

我们一般使用 `peer` 来标记一个元素，再使用各种 `peer-*` 来让它后续兄弟节点的样式生效。这些主要生成大量包含 `~` [后续兄弟选择器](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Subsequent-sibling_combinator) 的 `css` 代码。

然而很不幸，在小程序中 `~` 这个选择器非常容易报错，它前面只能跟 `class` 选择器，不能跟伪类，不然会报错:

```scss
// 报错
// .xxx:invalid~.xxx-invalid:visible {
//   visibility: visible;
// }
// 不报错
.xxx~.xxx-invalid:visible {
  visibility: visible;
}
```

所以你要么就不使用 `peer` 特性，如果需要此特性请使用内嵌 `class` 的方式来使用:

```html
<view>
  <view class="w-20 h-20 peer bg-gray-300" hover-class="tapped" />
  <view class="w-20 h-20 peer-[.tapped]:bg-red-400 bg-blue-400"></view>
</view>
```

> 前一个方块按压后进入 `hover` 状态 ，后面那个就变成红色。

## 出现 unexpected token "~" 错误

出现这个错误后，你应该把对应报错的相关 `peer`、`peer-*` 删掉，注意是删掉，请不要注释，因为 `tailwindcss` 中也会从注释中提取字符串，所以注释掉是没有效果的。

删掉之后，你需要重新启动一下你的应用（例如 `yarn dev:weapp`），不然导致错误的 `css` 还是会存在，导致项目崩溃。

---

## 常见问题


:::info 组件外部样式类必读
自定义组件使用 `externalClasses` 时样式被拆分？请先查看《[组件外部样式类（externalClasses）的支持](/docs/issues/externalClasses)》，按照文档里的 `customAttributes` 配置即可解决。
:::

:::tip 先运行诊断命令
接入失败、样式未生成、Tailwind CSS v4 PostCSS 报错或 JS 字符串 class 未转义时，可以先运行 `pnpm exec weapp-tailwindcss doctor`。详见《[使用 doctor 命令诊断项目配置](/docs/issues/doctor)》。
:::

## 为什么我更改了 class 保存重新打包的时候热更新失效？

[[#93](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/93)]

目前微信开发者工具会默认开启代码自动热重载 `compileHotReLoad` 功能，这个功能在原生开发中表现良好，但在 `uni-app` 和 `taro` 等的框架中，存在一定的问题，参见 [issues#37](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/37)，所以如果你遇到了此类问题，建议关闭 `compileHotReLoad` 功能。

## `disabled:opacity-50` 这类的 `tailwindcss` 工具类不生效?

这是由于微信小程序 `wxss` 选择器的原生限制，无法突破。参见 [issue#33](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/33)。

## `background-image` 为什么不能使用本地路径？

微信小程序在 `wxss` 中禁止 `background-image` 引用本地文件，解析时会直接报 `do-not-use-local-path` 错误。因此像 <code>bg-&#91;url('/images/homebg.png')&#93;</code> 这样的写法无法生效。请改用以下任一方式：

- 使用线上可访问的远程图片地址，例如 `bg-[url('https://example.com/bg.png')]`
- 将资源转成 `base64` 后内联到 `background-image`
- 改用 `<image>` 组件渲染背景效果

选择合适方案后再通过 `tailwindcss` 编写样式，即可避免编译报错。

## 和原生组件一起使用注意事项

假如出现原生组件引入报错的情况，可以参阅 [issue#35](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/35)，忽略指定目录下的文件，跳过插件处理，例如 `uni-app` 中的 `wxcomponents`。

如何更改？在传入的配置项 `cssMatcher`，`htmlMatcher` 这类配置，来过滤指定目录或文件。

## uni-app + Tailwind CSS 4 扫描 `src/uni_modules` 后生成异常 CSS

### 问题现象

当 CSS 入口使用下面这种过宽的 `@source` 配置：

```css
@import "tailwindcss";
@source "./src/**/*.{html,js,ts,jsx,tsx,vue}";
```

并且项目里存在 `src/uni_modules/**/*` 第三方包时，Tailwind 可能扫描到依赖源码中的正则片段或示例文本，例如 `[a-zA-Z:_]`，并把它当成 arbitrary property class 提取。

在小程序场景下，再经过 `weapp-tailwindcss` 转译后，最终可能出现类似：

```css
._ba-zA-Z_c__B {
  a-z-a--z:;
}
```

这样的异常产物。

### 根因

这类问题的根因不是业务代码真的写了这个 class，而是扫描范围过宽，误扫了第三方目录中的源码、文档或构建产物。

### 推荐配置

请显式排除 `src/uni_modules`：

```css title="src/app.css"
@import "tailwindcss";
@source "./src/**/*.{html,js,ts,jsx,tsx,vue}";
@source not "./src/uni_modules";
```

### 最佳实践

- `@source` 应尽量只覆盖业务源码目录
- 默认应排除 `uni_modules`、`node_modules`、`dist`、`unpackage`、文档和生成产物
- 如果必须扫描某个 `uni_modules` 包，应只精确包含其中真正承载模板类名的文件，而不是整个目录全量扫描

## 编译到 h5 / app 注意事项

有些用户通过 `uni-app` 等跨端框架，不止开发成各种小程序，也开发为 `H5` 或 App。从 v5 开始，H5/Web 与普通 uni-app App WebView 构建不再需要禁用 `WeappTailwindcss`：插件会根据 `UNI_PLATFORM=h5/app/app-plus` 自动把生成器目标切到 `web`，输出浏览器原生 Tailwind CSS。

```js
// 我们以 uni-app-vue3-vite 这个 demo为例
// vite.config.ts
import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';
import { WeappTailwindcss } from "weapp-tailwindcss/vite";
// vite 插件配置
const vitePlugins = [uni(),WeappTailwindcss({
  cssOptions: {
    rem2rpx: true,
  },
})];

export default defineConfig({
  plugins: vitePlugins
});

// Tailwind CSS 由 WeappTailwindcss 生成模式接管。
// 如果项目已有 PostCSS 配置，只保留 autoprefixer、业务自定义插件等非 Tailwind 插件。
```

如果自定义构建环境没有注入 `UNI_PLATFORM=h5/app/app-plus`，可以显式指定 Web 输出：

```js
WeappTailwindcss({
  generator: {
    target: "web",
  },
  cssOptions: {
    rem2rpx: true,
  },
});
```

`disabled` 只适合完全不希望插件参与的 RN、Harmony、独立原生或自定义构建，不是 H5 / 普通 App WebView 的常规配置。

## 报错 TypeError: Cannot use 'in' operator to search for 'CallExpression' in undefined

遇到这个问题是由于 `babel` 相关的包之间的版本产生了冲突导致的，这种时候可以删除掉 `lock` 文件（`yarn.lock`、`pnpm-lock.yaml`、`package-lock.json`），然后重新安装即可。

## taro webpack5 环境下，这个插件和外置额外安装的 `terser-webpack-plugin` 一起使用，会导致插件转义功能失效

相关 issue：[#142](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/142)

例如：`.h-4/6`、`!w-full` 正常会转义为`.h-4s6`、`.iw-full`，本插件失效后小程序开发者工具报编译错误 `.h-4\/6`、`.\!w-full`。

请压缩代码并不要使用[链接](https://docs.taro.zone/docs/config-detail/#terserenable)中的方法，太老旧了。

使用 `taro` 配置项里的的 `terser` 配置项，参见 [`terser` 配置项](https://docs.taro.zone/docs/config-detail#terser)。

> `terser` 配置只在生产模式下生效。如果你正在使用 `watch` 模式，又希望启用 `terser`，那么则需要设置 `process.env.NODE_ENV` 为 `production`。

也就是说，直接在开发 `watch` 模式的时候，设置环境变量 `NODE_ENV` 为 `production` 就行。

另外也可以不利用 `webpack` 插件压缩代码，去使用微信开发者工具内部的压缩代码选项。

## 为什么 space-y-1 这类写法不起作用?

相关 issue：[#108](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/108)

考虑到小程序的组件 `shadow root` 实现方式，默认情况下 `space` 这一类带有子选择器的，只对 `view` 元素生效。

即选择器变成了 `.space-y-1 > view + view`

这时候解决方案有 3 种：

- 组件外层套一层 `<view>` 元素。
- `virtualHost` 解决方案，在自定义组件中添加 `options: { virtualHost: true }` 即可解决此问题。
- [`cssOptions.cssChildCombinatorReplaceValue`](/docs/api/options/important#cssoptions) 配置项

## 使用 uni-app vite vue 注册插件时，发行到 h5 环境出现: [plugin:vite-plugin-uni-app-weapp-tailwindcss-adaptor] 'import' and 'export' may appear only with 'sourceType: "module"' (1:0) 错误

解决方案：

```js
import { WeappTailwindcss } from "weapp-tailwindcss/vite";
const vitePlugins = [uni(), WeappTailwindcss({
  cssOptions: {
    rem2rpx: true,
  },
})];
```

即 H5 与普通 uni-app App WebView 环境继续保留插件，由生成器自动切到 `web` 目标。自定义构建环境没有注入平台变量时，可以显式设置 `generator: { target: "web" }`。

## 使用 pnpm@8 插件注册失败问题

pnpm 8 这个版本改变了一些默认值，其中 `resolution-mode` 默认值变成了 `lowest-direct`。

这会导致所有的依赖，会被安装成你在 `package.json` 里注册的最低版本，这可能会造成一些问题。如何解决？

目录下创建一个 `.npmrc`，设置 `resolution-mode` 为 `highest`，然后重新安装，

或者，使用 `pnpm up -Li` 升级一下你 `package.json` 里的依赖包版本到最新即可。

## uni-app 在从v1升级到v2的过程中，如果使用了云函数相关功能，编译到小程序会出现问题

解决方案参见：<https://ask.dcloud.net.cn/question/170057>

相关 issue：[#74](https://github.com/sonofmagic/weapp-tailwindcss/issues/74#issuecomment-1573033475)

## uni-app vue2 中的 css 使用 @import 引入其他 css，导致在 `rpx` 在H5下不生效

需要添加并配置 `postcss-import`，参见 [issues/75](https://github.com/sonofmagic/weapp-tailwindcss/issues/75#issuecomment-1574592907)。

你可以参考仓库中的 `demo/uni-app-vue3-vite` 来进行配置。

## 为什么在 Taro JSX / JS 里写类名不生效？

在 `weapp-tailwindcss@5` 中，不再需要执行 `weapp-tw patch`。JS/JSX 里的类名能否转译，主要看这些类名是否已经进入 Tailwind 的扫描范围，并出现在构建时收集到的 `classNameSet` 中。

排查顺序：

- 检查 CSS 入口里的 `@source` 是否覆盖对应源码目录
- 检查项目是否还把官方 Tailwind PostCSS/Vite 插件和 `weapp-tailwindcss` 同时用于小程序目标；小程序生成链路应由 `weapp-tailwindcss` 接管
- 任意值类名如果写在动态拼接字符串里，Tailwind 可能扫描不到；这种场景需要改成完整字面量，或加入 safelist / `@source`

## monorepo 项目中 arbitrary values 写法无效？

这通常是 Tailwind 上下文定位不准，或源码没有被扫描到。可以先检查两件事：

- 配置 [tailwindcssBasedir](https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#tailwindcssbasedir)，让插件从正确的项目目录解析 Tailwind

- 检查 `@source` / `cssEntries`

如果 monorepo 的依赖提升导致不同包拿到的 Tailwind 版本不一致，再考虑限制 `tailwindcss` 包提升。具体配置取决于包管理器。

---

## 写在 js 中的 tailwindcss 任意值失效


`weapp-tailwindcss` 是允许你在 `js` 中编写任意值的，而且 `weapp-tailwindcss` 会自动帮你做好任意值的转译。

比如:

```js title="src/pages/index/index.js"
const xs = {
  wrapper: 'px-[4px] h-[40px]',
}
```

那么在最终的产物中，编译结果会自动变为

```js title="dist/pages/index/index.js"
const xs = {
  wrapper: 'px-_4px_ h-_40px_',
}
```

但是你这个文件，必须被 `tailwindcss` 感知到，并从里面提取到这 `2` 个 `class`。`weapp-tailwindcss` 才能通过和 `tailwindcss` 的通信，来完成这 `2` 个 `class` 的转译。

所以你这个源文件必须被 `@source` 包括到，这个自动转译的流程才能走完。

否则就会出现 `js` 转译没有进行, 导致开发者工具中审查元素时，出现:

```html
<view class="px- 4px  h- 40px "></view>
```

这种类名被切断的情况。

## 解决方案

检查你的 `@source`，确认你出现类名被切断的源文件，被 `@source` 包括。

文档地址: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources

当前文档仅维护 Tailwind CSS 4 接入说明。

<!-- 因为 `tailwindcss` 和 `weapp-tailwindcss` 的转化规则 ，是根据你的源代码里提取出来的 `token` 决定的 -->

---

## 在 monorepo 中使用


在 `monorepo` 由于存在 `hoist` 机制，可能会导致 `weapp-tailwindcss` 和 `tailwindcss` 通信受阻，这时候需要显式的去指定 `tailwindcss` 的路径

这里我们以 `taro@4` 的配置 `config/index.ts` 配置为例

## Tailwindcss@3

```ts
const config = {
  webpackChain(chain) {
    chain.merge({
      plugin: {
        install: {
          plugin: WeappTailwindcss,
          args: [
            {
              cssOptions: {
                rem2rpx: true,
              },
              // highlight-next-line
              tailwindcssBasedir: path.resolve(__dirname, '../'),
            },
          ],
        },
      },
    })
  },
}
```

## Tailwindcss@4

```ts
const config = {
  webpackChain(chain) {
    chain.merge({
      plugin: {
        install: {
          plugin: WeappTailwindcss,
          args: [
            {
              cssOptions: {
                rem2rpx: true,
              },
              // highlight-next-line
              cssEntries: [
                // app.css 的路径
                path.resolve(__dirname, '../src/app.css'),
              ],
            },
          ],
        },
      },
    })
  },
}
```

使用这样的配置，就能在 `monorepo` 中使用了

---

## 生成样式只作用于view和text标签


在微信小程序中，`darkMode` 设置为 `class`/ `selector` 后，`dark:className` 类选择器在 `button` 上无效，看生成样式只作用于 `view` 和 `text` 标签

这是由于小程序是不接受 `*` 这样一个选择器的。

默认情况下， `weapp-tailwindcss` 会把 `*` 选择器转化成 `view,text` 的选择器

这个配置可以通过 `cssOptions.cssSelectorReplacement.universal` 进行更改，从而适配更多标签。

详见 [`cssOptions`](/docs/api/options/important#cssoptions)

---

## 原生头条小程序使用 TailWindCSS


> 以下内容由使用 `weapp-tailwindcss` 的热心网友提供，十分感谢！

## 创建项目

创建项目 `test-miniapp`, 进入项目目录并初始化 `package.json`

```sh
cd test-miniapp
npm init -y
```

新建小程序开发目录 `src`，对应的小程序代码，生成目标代码目录为 `dist`

此时目录结构如下所示:

```
test-miniapp
-- src
-- dist
-- package.json
```

## 安装 gulp 及插件

- 本地安装 `gulp`

```sh
npm i -D gulp
```

- 安装 gulp 模块及插件

```sh
npm i -D gulp gulp-postcss gulp-plumber del@^6
```

## 安装与配置 tailwindcss

- 安装 Tailwind CSS 与 weapp-tailwindcss

```sh
npm i -D tailwindcss weapp-tailwindcss
```

- 不再创建 Tailwind 专用的 `postcss.config.js`

`weapp-tailwindcss@5` 默认由构建器插件接管 Tailwind CSS 生成。如果项目已有 PostCSS 配置，只保留业务自己的非 Tailwind 插件。

- 代码引入 `tailwindcss`，打开 `src/app.ttss`

```css
@import "tailwindcss";
@source "./**/*.{ttml,js}";
@source not "../dist";
```

当前文档仅维护 Tailwind CSS 4 接入说明。

## 配置 vscode 插件

### Prettier - Code formatter

安装插件

```sh
npm i -D prettier prettier-plugin-tailwindcss
```

配置 `prettier.config.js`

```js
module.exports = {
  // 行尾加分号
  semi: false,
  // 使用单引号
  singleQuote: true,
  // 配置文件类型
  overrides: [
    {
      files: '*.ttml',
      options: { parser: 'html' },
    },
    {
      files: '*.ttss',
      options: { parser: 'css' },
    },
  ],
  plugins: ['prettier-plugin-tailwindcss'],
}
```

将小程序的文件包括进来，设置：`首选项->工作区->设置->扩展->Prettier->Prettier: Document Selectors`

```txt
**/*.ttml
**/*.ttss
```

- 字节小程序开发助手（微信小程序是这个：WXML - Language Service）

### Tailwind CSS IntelliSense

并配置：`首选项->工作区->设置->扩展->Tailwind CSS IntelliSense->Tailwind CSS: Include Languages`

```
项：ttml，值：html
```

### Gulp Tasks

- Gulp Tasks

  安装插件

  ```sh npm2yarn
  npm install -D weapp-tailwindcss
  ```

  配置 `gulpfile.js`，需要注意的事，在面板执行 `serve` 后，即使后来停止了任务，程序里的监听 `watch` 也不会停，使得后续再启动 `serve` 后，会有多个监听 `watch` 和多个监听处理程序 `watchHandler`，重复处理文件。所以停止后再启动 `serve`，应该关闭 `vscode` 后重新打开

  ```js
  const { src, dest, series, parallel, task, watch } = require('gulp')
  const postcss = require('gulp-postcss')
  const plumber = require('gulp-plumber')
  const path = require('path')
  const del = require('del')
  const tailwindcssGulp = require('weapp-tailwindcss/gulp')

  // 在 gulp 里使用, 先使用 postcss 转化 css, 触发 tailwindcss，然后转化 transformWxss，最后转化 transformJs, transformWxml
  const {
    transformJs,
    transformWxml: transformHtml,
    transformWxss: transformCss,
  } = tailwindcssGulp.createPlugins({
    cssOptions: {
      rem2rpx: true,
    },
  })

  const config = {
    srcDir: 'src',
    distDir: 'dist',
    cssExt: '.ttss',
    jsExt: '.js',
    htmlExt: '.ttml',
  }

  function transformCssFiles() {
    return src(`${config.srcDir}/**/*${config.cssExt}`)
      .pipe(plumber())
      .pipe(postcss())
      .pipe(transformCss())
      .pipe(dest(`${config.distDir}`))
  }

  function transformJsFiles() {
    return src(`${config.srcDir}/**/*${config.jsExt}`)
      .pipe(plumber())
      .pipe(transformJs())
      .pipe(dest(`${config.distDir}`))
  }

  function transformHtmlFiles() {
    return src(`${config.srcDir}/**/*${config.htmlExt}`)
      .pipe(plumber())
      .pipe(transformHtml())
      .pipe(dest(`${config.distDir}`))
  }

  function copyOtherFiles() {
    return src([
      `${config.srcDir}/**/*`,
      `!${config.srcDir}/**/*${config.cssExt}`,
      `!${config.srcDir}/**/*${config.jsExt}`,
      `!${config.srcDir}/**/*${config.htmlExt}`,
    ]).pipe(dest(`${config.distDir}`))
  }

  function promisify(task) {
    return new Promise((resolve, reject) => {
      if (task.destroyed) {
        resolve(undefined)
        return
      }
      task.on('finish', resolve).on('error', reject)
    })
  }

  // type 取值: changed, added, deleted
  async function watchHandler(type, file) {
    if (type == 'deleted') {
      await del([
        file.replace(
          `${config.srcDir}${path.sep}`,
          `${config.distDir}${path.sep}`
        ),
      ])
    } else {
      const extName = path.extname(file)
      switch (extName) {
        case config.cssExt:
          await promisify(transformCssFiles())
          break

        case config.jsExt:
          await promisify(transformCssFiles())
          await promisify(transformJsFiles())
          break

        case config.htmlExt:
          await promisify(transformCssFiles())
          await promisify(transformHtmlFiles())
          break

        default:
          await promisify(copyOtherFiles())
      }
    }
  }

  function watchTask() {
    const watcher = watch([`${config.srcDir}/**/*`])
    watcher
      .on('change', function (file) {
        console.log(`${file} is changed`)
        watchHandler('changed', file)
      })
      .on('add', function (file) {
        console.log(`${file} is added`)
        watchHandler('added', file)
      })
      .on('unlink', function (file) {
        console.log(`${file} is deleted`)
        watchHandler('deleted', file)
      })
  }

  function clean() {
    return del(config.distDir, { force: true })
  }

  const buildTasks = [
    transformCssFiles,
    transformJsFiles,
    transformHtmlFiles,
    copyOtherFiles,
  ]

  // 注册服务任务
  task('serve', series(...buildTasks, watchTask))

  // 注册清除任务
  task('clean', parallel(clean))
  ```

---

## rpx 任意值颜色或长度单位二义性与解决方案


## 这是一个什么问题？

在不使用 `weapp-tailwindcss` 的情况下，你直接写这样的 `rpx` 写法：

```html
<div class="text-[32rpx]"></div>
```

最终它会生成这样的 `css`：

```css
.text-\[32rpx\] {
  color: 32rpx;
}
```

为什么 `rpx` 这个好端端的长度单位，会变成颜色呢？

原因在于 `rpx` 不是一个标准的 `W3C` 规定的 `CSS` 长度单位，这是微信小程序自己定的 `WXSS` 单位。

## 什么是 **二义性**?

`tailwindcss` 中有些原子类具有 **二义性**，比如:

- `text-[]`
- `border-[]`
- `bg-[]`
- `outline-[]`
- `ring-[]`

其中 `text-[]` 中的 `text-[16.16px]` 生成的 css 是 `font-size: 16.16px;`, 而 `text-[#123456]` 生成的 css 是 `color: #123456;`;

这就是原子类的 **二义性**

---

而 `tailwindcss` 在针对具有**二义性**的任意值写法:

这些会去**校验括号**内的任意值，是否为有效的 `CSS` 长度单位！

如果为 `true`，则生成出长度单位的 `css` 节点，反之则生成出颜色单位的 `css` 节点:

```css
/* text-[16px] */
.text-\[16px\] {
    font-size: 16px
}
/* text-[#fafafa] */
.text-\[\#fafafa\] {
    --tw-text-opacity: 1;
    color: rgb(250 250 250 / var(--tw-text-opacity))
}
```

那么问题来了，`rpx` 在单位校验的时候，由于不认识这个单位，导致单位无效所有被分到了颜色组。

```css
/* text-[32rpx] */
.text-\[32rpx\] {
    --tw-text-opacity: 1;
    color: 32rpx;
}
```

所以造成了这个问题！那么如何解决呢？

## 目前插件的解决方案

目前 `weapp-tailwindcss@5` 的生成模式会在构建运行时处理 Tailwind CSS 4 的候选类名与小程序单位兼容，不需要再执行 `weapp-tw patch`。

如果你仍然在旧项目里看到 `postinstall: "weapp-tw patch"`，可以直接删除。当前 `weapp-tw patch` 只是兼容旧脚本的提示命令。

<!-- 然而，以后 `tailwindcss` 将会使用由 `rust` 编写的新引擎。

这时候这种 `hack` 方式将会失效，毕竟那种情况下都是二进制文件了！

那么为了预防这种可能出现的危机，我们应该怎么做呢？ -->

## 强制CSS单位的解决方案

我们可以在使用这些带有**二义性**的单位的时候，可以通过 `length` 或 `color` 这种的前缀来指定它应该是什么，例如：

```html
<div class="text-[22rpx]">...</div>
<div class="text-[#bada55]">...</div>
<!-- 变成下列的写法 -->
<div class="text-[length:22rpx]">...</div>
<div class="text-[color:#bada55]">...</div>
```

这样就通过指定的方式，直接跳过了长度单位校验，生成出长度单位的 `css` 了！

```css
.text-\[length\:22rpx\] {
    font-size: 22rpx
}
```

同样你可以使用这 2 个前缀来指定 `css` 变量的生成形式：

```html
<!-- 生成 font-size  -->
<div class="text-[length:var(--my-var)]">...</div>

<!-- 生成 color -->
<div class="text-[color:var(--my-var)]">...</div>
```

## 参见

- `tailwindcss` 中的[添加自定义样式](https://tailwindcss.com/docs/adding-custom-styles#resolving-ambiguities)
- 相关 Issue：[#110](https://github.com/sonofmagic/weapp-tailwindcss/issues/110)、[#110](https://github.com/sonofmagic/weapp-tailwindcss/issues/109)

---

## `Tarojs` 中使用 `terser` 压缩代码


在 `taro` `webpack5` 环境下，这个插件和外置额外安装的 `terser-webpack-plugin` 一起使用，会导致插件转义功能失效

相关 issue：[#142](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/142)

## 现象

例如：`.h-4/6`、`!w-full` 正常会转义为`.h-4s6`、`.iw-full`，本插件失效后小程序开发者工具报编译错误 `.h-4\/6`、`.\!w-full`。

## 解决方案

请压缩代码并不要使用[链接](https://docs.taro.zone/docs/config-detail/#terserenable)中的方法，太老旧了。

使用 `taro` 配置项里的的 `terser` 配置项，参见 [`terser` 配置项](https://docs.taro.zone/docs/config-detail#terser)。

> `terser` 配置只在生产模式下生效。如果你正在使用 `watch` 模式，又希望启用 `terser`，那么则需要设置 `process.env.NODE_ENV` 为 `production`。

也就是说，直接在开发 `watch` 模式的时候，设置环境变量 `NODE_ENV` 为 `production` 就行。

另外也可以不利用 `webpack` 插件压缩代码，去使用微信开发者工具内部的压缩代码选项。

## 配置参考

```ts title="config/index.ts"
{
  terser: {
    enable: true,
    config: {
      // 相关配置项
    },
  },
}
```

然后你想要在开发时，就生效，那就需要传入 `NODE_ENV=production` 环境变量，例如:

```json title="package.json"
{
  "scripts":{
    "dev:weapp": "cross-env NODE_ENV=production npm run build:weapp -- --watch",
  }
}
```

`cross-env` 没有安装的可以安装一下

---

## H5 端原生 toast 样式偏移问题


在使用 `tailwindcss` 的时候，编译到 `h5` 平台，使用 `uni.toast` / `taro.toast` 时，出现下列的效果

![](./toast-svg-bug.jpg)

`tailwindcss` 的 `base` 中的 `preflight` 影响这个 `uni.toast` 的样式

这是由于 `preflight.css` 中默认会添加下方的样式

```css
img,
svg,
video,
canvas,
audio,
iframe,
embed,
object {
  display: block; /* 1 */
  vertical-align: middle; /* 2 */
}
```

这导致了 `svg` 变成了 `display: block;` 的状态

解决方案也非常的简单, 在 `app.wxss` 使用样式进行覆盖:

```scss
.uni-toast{
  svg {
    display: initial; // 重新初始化 uni-toast 里的样式进行覆盖 覆盖
  }
}
```

假如你使用的是 `uni-app`，那么还可以使用样式条件编译的方式来做:

```scss
/*  #ifdef  H5  */
svg {
  display: initial;
}
/*  #endif  */
```

---

## uni-app Vite App WebView 中特殊字符类名的支持结论


结论先说清楚：普通 `uni-app Vite` 运行到 Android / iOS App WebView 后，WebView 的 DOM/CSSOM 本身并不是完全不支持 `dark:bg-red-300`、`text-[45rpx]` 这类带 `:`、`[`、`]` 的 class。只要 class 原样进入 DOM，并且 CSS selector 做了标准 CSS 转义，例如 `.dark\:bg-red-300`、`.text-\[45rpx\]`，真实 WebView 可以匹配到样式。

但在 `uni-app Vite + Tailwind CSS + weapp-tailwindcss` 的实际构建链里，不建议依赖这些 raw class 留在最终 App 产物中。原因是 App 端还要同时处理：

- Vue / uni-app 模板编译后的运行时代码
- Tailwind v4 生成的 selector 与变体 selector
- `rpx` 任意值的长度单位归类与单位转换
- Android / iOS WebView 对现代 CSS 值的兼容差异
- JS 字符串 class 与 CSS selector 是否一一对应

因此 `weapp-tailwindcss` 在普通 uni-app App WebView 分支会把这些类名映射成 safe class，并让 JS 运行时代码和 CSS selector 同步。例如：

| 源码写法 | App WebView 产物 class |
| --- | --- |
| `dark:bg-red-300` | `dark_cbg-red-300` |
| `text-[45rpx]` | `text-_b45rpx_B` |
| `bg-white/70` | `bg-white_f70` |

## 本次验证环境

`demo/uni-app-vite-tailwindcss-v4` 已分别运行到 Android 和 iOS App，并确认输出目录为 `dist/dev/app-plus`。

| 平台 | 运行时 | WebView 版本信息 | 验证结论 |
| --- | --- | --- | --- |
| Android | HBuilder `15.07` / `1507`，Android 11 emulator | Android System WebView `com.google.android.webview` `91.0.4472.114`，UA 中 `Chrome/91.0.4472.114`、`AppleWebKit/537.36` | raw class selector、raw class 属性选择器、safe class 均匹配 |
| iOS | HBuilder `15.07` / `1507`，iOS Simulator `26.5` | WKWebView / WebKit bundle `8624.2.5.10.4`，Safari `26.5` / `8624.2.5.10.4` | view 层 raw class 属性选择器、safe class 均匹配 |

Android 通过 WebView 远程调试协议在真实 HBuilder App WebView 中执行 DOM/CSSOM 探针，结果为：

```json
{
  "rawClassSelectorMatched": true,
  "rawAttributeSelectorMatched": true,
  "rawTextClassSelectorMatched": true,
  "rawTextAttributeSelectorMatched": true,
  "safeDarkMatched": true,
  "safeTextMatched": true
}
```

iOS 的 `uni-app` App service 层不一定暴露 `document`，所以页面上的 DOM/CSSOM 探针会显示 `document unavailable`。因此 iOS 同时提供 `Special Class Visual Probe` 可视探针：它把 raw class 通过运行时拼接绑定到 `view/text`，再用 `[class~="dark:bg-red-300"]`、`[class~="text-[45rpx]"]` 这类属性选择器匹配。iOS 截图中 raw dark 背景变粉、raw text 变为 45px，说明 view 层可以保留并匹配这些 raw class。

## 验证方式

仓库里的 `demo/uni-app-vite-tailwindcss-v4` 首页包含一个 `Special Class Probe` 面板。把它运行到 Android 或 iOS App 后，会在真实 App WebView 中执行下列检查：

1. 用 `document.createElement` 创建 raw class 元素：
   - `dark:bg-red-300`
   - `text-[45rpx]`
2. 注入标准转义后的 CSS selector：
   - `.dark .dark\:bg-red-300`
   - `.text-\[45rpx\]`
3. 创建 safe class 对照组：
   - `dark_cbg-red-300`
   - `text-_b45rpx_B`
4. 使用 `getComputedStyle` 读取真实渲染结果。

页面和 console 会输出：

```text
[uni-app-vite] Special Class Probe
```

如果看到：

```text
raw.dark:bg-red-300.matched: true
raw.text-[45rpx].matchedViaEscapedSelector: true
safe.dark_cbg-red-300.matched: true
safe.text-_b45rpx_B.matched: true
```

说明当前可运行 DOM/CSSOM 探针的 App WebView 本身可以识别这些 raw class，只是要求 CSS selector 正确转义。iOS 如果显示 `document unavailable`，以页面里的 `Special Class Visual Probe` 为准。

页面还包含 `Special Class Visual Probe`。它不依赖 `document`，用于覆盖 iOS 这类 service 层没有 DOM API 的 App 运行时。该探针包含两组对照：

- raw 组：运行时拼接出 `dark:bg-red-300`、`text-[45rpx]` 并绑定到页面节点。
- safe 组：直接使用 `dark_cbg-red-300`、`text-_b45rpx_B`。

如果 raw 组和 safe 组都出现粉色背景、45px 大字，说明当前 App view 层可以保留并匹配 raw class；如果只有 safe 组命中，则说明不能依赖 raw class 直接进入最终产物。

## 推荐写法

业务源码继续写 Tailwind 原始类名：

```html
<view class="theme-dark dark:bg-red-300 text-[45rpx]">
  App WebView
</view>
```

不要手写产物里的 safe class，也不要在业务代码里混用 raw class 和 safe class。safe class 是构建产物契约，由 `weapp-tailwindcss` 负责生成和同步。

## 不推荐的做法

不要通过关闭 `weapp-tailwindcss` 或跳过转译来强行保留 raw class：

```ts
// 不推荐：App WebView 下容易造成 CSS selector、JS class 与 rpx 处理不一致
WeappTailwindcss({
  disabled: process.env.UNI_PLATFORM === 'app',
})
```

普通 uni-app App WebView 应继续保留插件，让生成器按 WebView 分支输出兼容 CSS。

## 排查标准

如果 App 端看到这类样式不生效，优先按下面顺序查：

1. 看最终 `dist/dev/app-plus/app-service.js` 里的 class 是否已经变成 safe class。
2. 看最终 `dist/dev/app-plus/app.css` 是否存在对应 safe selector。
3. 看颜色是否已经从 Tailwind v4 的 `oklch()` / `color-mix()` 降级为 `rgb()`、`rgba()` 或 `#hex`。
4. 看 `text-[45rpx]` 是否生成了长度样式，而不是错误地生成 `color: 45rpx`。
5. 再看 `Special Class Probe` 面板，区分“WebView 本身不支持 raw class”还是“构建链没有把 class 和 CSS 对齐”。

## 当前结论

基于 `demo/uni-app-vite-tailwindcss-v4` 在 Android / iOS App WebView 上的实测，结论是：

- `:`、`[`、`]` 这类特殊字符不是 App WebView 的绝对禁区。
- raw class 只有在 DOM class 与转义后的 CSS selector 同时保留时才可靠。
- iOS App service 层可能没有 `document`，不要把 `document.createElement` 探针是否可运行等同于 view 层是否支持特殊 class。
- 在真实 `uni-app Vite + Tailwind CSS` 产物中，更稳定的方案是使用 `weapp-tailwindcss` 自动输出 safe class。
- 文档、demo 与测试都应按 safe class 作为最终产物断言，而不是假设 raw class 会保留到 App 产物。

---

## 和 NutUI 一起使用


Taro 项目使用 [NutUI](https://nutui.jd.com) 的 Vue 或 React 版本时，通常会同时启用 `@tarojs/plugin-html`。

`@tarojs/plugin-html` 可能会在构建过程中删掉 Tailwind 的 CSS 变量初始化区域。结果是依赖变量的工具类失效，例如 `drop-shadow-2xl`、`translate-1/2`、渐变、ring 等。

此时可以开启 `cssOptions.injectAdditionalCssVarScope`。它会补一份 Tailwind CSS 变量初始化作用域，避免变量类名在小程序端丢失。配置入口见 [`cssOptions`](/docs/api/options/important#cssoptions)。

示例：

```diff
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')

{
  mini: {
    webpackChain(chain, webpack) {
      chain.merge({
        plugin: {
          install: {
            plugin: WeappTailwindcss,
            args: [{
              cssOptions: {
                rem2rpx: true,
+               injectAdditionalCssVarScope: true
              }
            }]
          }
        }
      })
    }
  }
}
```

## 旧 Taro 版本的备选方案

部分旧 Taro 版本可以通过 `postcss-html-transform` 保留相关选择器。优先使用上面的 `cssOptions.injectAdditionalCssVarScope`；只有旧项目无法升级时，再考虑下面的方式。

```js
// config/index.js
config = {
  // ...
  mini: {
    // ...
    postcss: {
      htmltransform: {
        enable: true,
        // 设置成 false 表示 不去除 * 相关的选择器区块
        // 开启后可能删除 Tailwind CSS 变量初始化区域
        // 需要用 config 套一层，官方文档上是错的
        config: {
          removeCursorStyle: false,
        }
      },
    },
  },
}
```

## 参见

- [taro 官方文档](https://docs.taro.zone/docs/use-h5#插件-postcss-配置项)
- 相关 Issue：[#155](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/155)

---

## 和 Taroify 一起使用


`taro` 使用 [Taroify](https://taroify.github.io/taroify.com/) 的共同注意点:

由于 [Taroify](https://taroify.github.io/taroify.com/) 引入后，会导致 `tailwindcss` 的样式被覆盖，[Taroify](https://taroify.github.io/taroify.com/) 样式的优先级会高于 `tailwindcss`。

## 解决方案

### 修改Taroify引入方式

按照[Taroify](https://taroify.github.io/taroify.com/) 修改引入方式，将 `taroify` 引入方式改成按需引入

```bash npm2yarn
# 安装插件
npm i babel-plugin-import
```

修改Babel配置文件，修改组件和图标样式的引入方式为手动引入

```js
// babel.config.js
module.exports = {
  plugins: [
    [
      'import',
      {
        libraryName: '@taroify/core',
        libraryDirectory: '',
        // 这修改为false
        style: false,
        // style: false,
      },
      '@taroify/core',
    ],
    [
      'import',
      {
        libraryName: '@taroify/icons',
        libraryDirectory: '',
        camel2DashComponentName: false,
        // 这里修改为false
        style: false,
        // style: () => "@taroify/icons/style",
        customName: name => name === 'Icon' ? '@taroify/icons/van/VanIcon' : `@taroify/icons/${name}`,
      },
      '@taroify/icons',
    ],
  ],
}
```

### 修改引入样式顺序

修改根目录下的样式引入顺序，优先引入[Taroify](https://taroify.github.io/taroify.com/) 的样式，再引入Tailwindcss的样式

```tsx
// src/app.tsx

import Taro from '@tarojs/taro'

import '@taroify/icons/index.scss'
import '@taroify/core/index.scss'
import './app.scss'

// ...

```

```scss
// src/app.scss

@use 'tailwindcss/base';
@use 'tailwindcss/components';
@use 'tailwindcss/utilities';
```

## 参见

- [Taroify 官方文档](https://taroify.github.io/taroify.com/)

---

## 和 wot-design-uni 一起使用



---

## v1 版本插件常见问题，使用最新版本插件无须参考


## 我在 `js` 里写了 `tailwindcss` 的任意值，为什么没有生效?

详见 [issue#28](https://github.com/sonofmagic/weapp-tailwindcss-webpack-plugin/issues/28)

A: 因为这个插件，主要是针对, `wxss`,`wxml` 和 `jsx` 进行转义的，`js` 里编写的 `string` 是不转义的。如果你有这样的需求可以这么写:

```js
import { replaceJs } from 'weapp-tailwindcss-webpack-plugin/replace'
const cardsColor = reactive([
  replaceJs('bg-[#4268EA] shadow-indigo-100'),
  replaceJs('bg-[#123456] shadow-blue-100')
])
```

> 你不用担心把代码都打进来导致体积过大，我在 'weapp-tailwindcss-webpack-plugin/replace' 中，只暴露了2个方法，代码体积 1k左右，esm格式。

## replaceJs 跨端注意点

就是在常见问题中的 `replaceJs` 这个方法原先是为小程序平台设计的，假如你一份代码，需要同时编译到小程序和 `h5` 平台，可以参考如下的封装：

```js
// util.js
import { replaceJs } from 'weapp-tailwindcss-webpack-plugin/replace'
// uni-app 的条件编译写法
export function replaceClass(str) {
  // #ifdef H5
  return str
  // #endif
  return replaceJs(str)
}
// or 环境变量判断
export function replaceClass(str) {
  // 需要根据自己目标平台自定义，这里仅仅给一些思路
  if(process.env.UNI_PLATFORM === 'h5'){
    return str
  }
  return replaceJs(str)
}

// then other.js
const cardsColor = reactive([
  replaceClass('bg-[#4268EA] shadow-indigo-100'),
  replaceClass('bg-[#123456] shadow-blue-100')
])
```

这样就能在多端都生效了。

---

## 从 v1 迁移到 v2


在 `2.x` 版本中，可以把之前使用的 `webpack` 插件，全部更换为 `WeappTailwindcss` 插件，不过 `vite` 插件的导出有一些小变化:

`1.x`:

```js
import vwt from 'weapp-tailwindcss-webpack-plugin/vite';
```

`2.x`:

```js
// WeappTailwindcss 就是新的插件
import { WeappTailwindcss } from 'weapp-tailwindcss-webpack-plugin/vite';
```

另外新的 `WeappTailwindcss` 可以直接从 `weapp-tailwindcss-webpack-plugin` 引入，同时在新的 `WeappTailwindcss` 中，之前所有的配置项都被继承了过来，只需要用它直接替换原先插件即可。

另外不要忘记把:

```json
 "scripts": {
+  "postinstall": "weapp-tw patch"
 }
```

添加进你的 `package.json` 里，然后清除原先的打包缓存之后重新打包运行。

---

## 从 v2 迁移到 v3


v3 版本相比于 v2, 主要是删去一些过时的功能，配置项，同时会改变插件的默认值，使得整体插件变得更易用，更容易安装
假如你没有用到什么复杂自定义配置，那么完全可以平滑升级上来。

## 配置项改动

### 删除的配置项

- 删去 `replaceUniversalSelectorWith` 选项，使用 `cssSelectorReplacement.universal` 来代替，后者参数覆盖前者
- 删去 `minifiedJs` 选项，现在完全遵从用户的配置，用户压缩就压缩，反之亦然
- 删去 `jsEscapeStrategy` 选项，现在默认只有一种模式 `replace`/ 不再提供 `regenerate` 模式
- 删去 `customReplaceDictionary` 的 `complex` 模式，只内置 `simple` 模式 (你如果还要 `complex` 模式 ,可以从 `@weapp-core/escape` 引入，再传入 `customReplaceDictionary` 配置项即可)
- `cssMatcher`/`htmlMatcher`/`jsMatcher`/ `mainCssChunkMatcher` / `wxsMatcher` 不再能够传入 `glob` 表达式(例如`**/*.html`)，现在都是传入一个方法: `(name: string) => boolean`。要兼容原先的 `glob` 表达式，你可以通过 `minimatch` 把 `glob` 表达式转化成正则来兼容原先的配置
- `cssPreflightRange` 只存在一种模式，为 `all`, 之前的 `view` 选项交给 `cssSelectorReplacement.universal` 进行托管

### 增加的配置项

- `rem2rpx` : 类型 `rem2rpx?: boolean | rem2rpxOptions`

rem 转 rpx 配置，默认 **不开启**，可传入配置项，配置项见 <https://www.npmjs.com/package/postcss-rem-to-responsive-pixel>
这个配置项代表插件内置了 `postcss-rem-to-responsive-pixel` ，不过默认不开启，传入一个 `true` 相当于传入配置:

```js
{
  // 32 意味着 1rem = 32rpx
  rootValue: 32,
  // 默认所有属性都转化
  propList: ['*'],
  // 转化的单位,可以变成 px / rpx
  transformUnit: 'rpx',
}
```

当然你也可以传入 `rem2rpxOptions` 这样一个 `object` 进行自定义

#### 为什么默认不开启？

1. 为了从 `2.x` 版本可以平滑的过渡到 `3.x`
2. 从我的视角看，内置 `postcss` 插件功能，虽然整体集成度上更高了，但是对其他开发者可能不是那么自由，比如在 `2.x` 时候，由于 `postcss-rem-to-responsive-pixel` 是外置的，所以开发者可以自由的决定它的加载顺序和加载逻辑，但是内置之后都是我决定的。不过内置好处也有，就是开箱即用

### 增强的配置项

- `cssChildCombinatorReplaceValue`, `cssSelectorReplacement.root`,`cssSelectorReplacement.universal` 现在都可以接受字符串数组了，它们可以自动展开，防止选择器格式化错误问题

### 修改的默认值

- `cssPreflightRange` 从 `'view'` 变为 `undefined`, 现在 `all` 的作用变成了在 `tailwindcss` 变量注入区域的选择器，添加一个 `:not(not)` 的选择器作为全局选择器的替代
- `cssSelectorReplacement.universal` 从 `'view'` 变为 `['view', 'text']`, 这意味着 `*` 选择器会被展开成 `view,text` 以及对应方式
- `cssChildCombinatorReplaceValue` 从 `'view + view'` 变为 `['view']`
- `replaceUniversalSelectorWith`,`jsEscapeStrategy`,`minifiedJs` 选项被删除，所以不再保留默认值

### 现在选项合并，数组默认行为变为覆盖，原先是合并

```js
const options = getOptions(input,defaults)
defaults: ['a','b'], input:['c']
// before:
options == ['a','b','c']
// after:
options == ['c']
```

<https://github.com/sonofmagic/weapp-tailwindcss/issues/259>

---

## 从 v4 迁移到 v5


v5 最大的变化不是 API 名字，而是职责边界变了。

在 v4 里，很多项目会先让 Tailwind 官方插件生成 CSS，再由 `weapp-tailwindcss` 做小程序转义。v5 改成由 `WeappTailwindcss` 接管 Tailwind CSS 生成链路：同一份 Tailwind 输入，在小程序端生成小程序可用的选择器和样式；在 H5/Web 端生成浏览器可用的 Tailwind CSS。

所以迁移时别急着到处改类名。先把构建链路理顺。

## 先看结论

大多数项目要做这几件事：

1. 升级 `weapp-tailwindcss` 到 v5。
2. 删除 `postinstall: "weapp-tw patch"`。
3. 小程序构建里移除 Tailwind 官方生成插件。
4. 注册 `WeappTailwindcss`。
5. 检查 Tailwind CSS 4 的入口和扫描范围。
6. H5/Web 构建不要再简单禁用 `WeappTailwindcss`；Taro 项目要同时覆盖 H5 和小程序构建。
7. 跑一次小程序构建，再测一行新增任意值 class。

当前 v5 文档默认迁移到 Tailwind CSS 4。当前文档仅维护 Tailwind CSS 4 接入说明。

## 1. 升级依赖

```bash npm2yarn
npm install -D weapp-tailwindcss@5 tailwindcss@4
```

如果这些包只服务小程序构建，可以删掉：

```bash npm2yarn
npm uninstall tailwindcss-patch @tailwindcss/vite @tailwindcss/postcss
```

如果同一个仓库里还有独立的 Web 应用，Web 应用可以继续使用 `@tailwindcss/vite` 或 `@tailwindcss/postcss`。限制只针对同一次小程序构建：不要让官方 Tailwind 插件和 `WeappTailwindcss` 同时生成 Tailwind CSS。

## 2. 删除安装后 patch

删掉 `package.json` 里的旧脚本：

```jsonc title="package.json"
{
  "scripts": {
    // 删除
    "postinstall": "weapp-tw patch"
  }
}
```

v5 的生成链路会在构建时处理 Tailwind 运行时，不需要安装后 patch。保留这个脚本通常不会带来收益，排查问题时反而会多一个干扰项。

## 3. 清理 Tailwind 官方生成插件

小程序构建里不要再注册这些插件：

```js title="postcss.config.js"
module.exports = {
  plugins: {
    tailwindcss: {},
    '@tailwindcss/postcss': {},
  },
}
```

```ts title="vite.config.ts"
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})
```

业务 PostCSS 插件可以留，比如 `autoprefixer`、框架自己的 PostCSS 插件、压缩插件等。要删的是 Tailwind CSS 的生成入口。

## 4. 检查 Tailwind CSS 入口

Tailwind CSS 4 使用 CSS-first 入口：

```css title="src/app.css"
@import "tailwindcss";
@source "./**/*.{html,js,ts,jsx,tsx,vue,wxml,axml,ttml,mpx,uts,uvue}";
@source not "./uni_modules";
@source not "../node_modules";
@source not "../dist";
@source not "../unpackage";
```

Tailwind CSS 4 的入口请放在纯 `.css` 文件里。不要把 `@import "tailwindcss"` 直接写到 `scss`、`less`、`sass` 文件中。业务预处理样式可以引入这个 CSS 文件，但 Tailwind 入口本身最好保持简单。

## 5. 注册 WeappTailwindcss

Vite 项目：

```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const projectRoot = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  plugins: [
    WeappTailwindcss({
      cssEntries: [
        resolve(projectRoot, 'src/app.css'),
      ],
      cssOptions: {
        rem2rpx: true,
      },
    }),
  ],
})
```

uni-app Vite 项目里，放在 `uni()` 后面：

```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const projectRoot = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss({
      cssEntries: [
        resolve(projectRoot, 'src/app.css'),
      ],
      cssOptions: {
        rem2rpx: true,
      },
    }),
  ],
})
```

Webpack 项目：

```js title="webpack.config.js"
const path = require('node:path')
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')

module.exports = {
  plugins: [
    new WeappTailwindcss({
      cssEntries: [
        path.resolve(__dirname, 'src/app.css'),
      ],
      cssOptions: {
        rem2rpx: true,
      },
    }),
  ],
}
```

Taro、Mpx、uni-app Webpack 这类项目的挂载位置各不相同，按对应框架页复制完整写法即可。迁移时要抓住一个点：Tailwind 生成交给 `WeappTailwindcss`，不要再从 PostCSS 或官方 Vite 插件生成第二份 Tailwind CSS。

### Taro 迁移要覆盖 H5 和小程序

Taro 迁移时不要只在小程序链路注册插件。v5 的 `WeappTailwindcss` 会根据 `TARO_ENV=h5` 自动切到 Web 目标，所以 H5 构建也应该保留插件。

Webpack 项目里，`mini.webpackChain` 和 `h5.webpackChain` 都注册一次：

```js title="config/index.[jt]s"
const path = require('node:path')
const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')

const weappTailwindcssOptions = {
  cssOptions: {
    rem2rpx: true,
  },
  cssEntries: [
    path.resolve(__dirname, '../src/app.css'),
  ],
}

function registerWeappTailwindcss(chain) {
  chain.merge({
    plugin: {
      install: {
        plugin: WeappTailwindcss,
        args: [weappTailwindcssOptions],
      },
    },
  })
}

module.exports = {
  mini: {
    webpackChain(chain) {
      registerWeappTailwindcss(chain)
    },
  },
  h5: {
    webpackChain(chain) {
      registerWeappTailwindcss(chain)
    },
  },
}
```

Vite 项目里，把插件放在 `config/index` 的 `compiler.vitePlugins`。不要只写单独的 `vite.config.ts`，因为它通常只在小程序运行时被加载，H5 不会走这份配置。

```ts title="config/index.ts"
import path from 'node:path'
import type { Plugin } from 'vite'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

export default {
  compiler: {
    type: 'vite',
    vitePlugins: [
      WeappTailwindcss({
        cssOptions: {
          rem2rpx: true,
        },
        cssEntries: [
          path.resolve(__dirname, '../src/app.css'),
        ],
      }),
    ] as Plugin[],
  },
}
```

## 6. 写清 cssEntries

Tailwind CSS 4 项目应总是写清 `cssEntries`，并使用项目根目录解析出的绝对路径。显式入口更稳定，也更容易排查跨框架、跨平台、分包和多入口问题。

这些情况必须显式写：

- Tailwind CSS 4 项目里有多个 CSS-first 入口。
- 普通分包、独立分包有自己的 CSS-first 入口。
- 入口 CSS 没有被框架直接引入，或由自定义插件/loader 间接引入。
- Webpack、Gulp、自定义构建。
- 构建日志提示没有找到 Tailwind CSS 入口。
- uni-app x + Tailwind CSS 4，尤其是 HBuilderX 项目。

即使是单入口 Vite 项目，也推荐显式写。它不是为了替代 import，而是为了让 `WeappTailwindcss` 稳定读取入口 CSS 中的 `@source`、`@config` 与 Tailwind 指令。

```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const projectRoot = dirname(fileURLToPath(import.meta.url))

WeappTailwindcss({
  cssOptions: {
    rem2rpx: true,
  },
  cssEntries: [
    resolve(projectRoot, 'src/app.css'),
  ],
})
```

多入口或分包项目：

```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'

const projectRoot = dirname(fileURLToPath(import.meta.url))

WeappTailwindcss({
  cssEntries: [
    resolve(projectRoot, 'src/app.css'),
    resolve(projectRoot, 'src/sub-normal/pages/index.css'),
    resolve(projectRoot, 'src/sub-independent/pages/index.css'),
  ],
})
```

`cssEntries` 写绝对路径，指向包含 `@import "tailwindcss"` 或 `@tailwind` 指令的 CSS 入口。多个入口就都写进去。

## 7. H5/Web 构建不要一刀切禁用

v4 项目里经常有这段：

```ts title="vite.config.ts"
const isH5 = process.env.UNI_PLATFORM === 'h5'

WeappTailwindcss({
  disabled: isH5,
})
```

迁移到 v5 后，先删掉这种 H5/Web 禁用逻辑：

```ts title="vite.config.ts"
WeappTailwindcss({
  cssOptions: {
    rem2rpx: true,
  },
})
```

v5 会根据常见环境变量自动切换目标。例如 `UNI_PLATFORM=h5/app/app-plus`、`UNI_UTS_PLATFORM=h5/web/web-*`、`TARO_ENV=h5`、`MPX_CLI_MODE=web`、`MPX_CURRENT_TARGET_MODE=web` 会走 Web 目标，输出浏览器可用的 Tailwind CSS，而不是小程序转义后的选择器。`UNI_UTS_PLATFORM=app-android/app-ios/app-harmony` 这类 uni-app x 原生 App 目标不会被当成 Web，也不需要新增 `target: 'app'`。

如果你在自定义构建里需要明确指定，也可以写：

```ts title="vite.config.ts"
WeappTailwindcss({
  generator: {
    target: 'web',
  },
})
```

`disabled` 仍然有用，但它适合“完全跳过插件”的构建，例如某些 RN、Harmony 或独立原生构建。对 uni-app、uni-app x、Taro、Mpx、Weapp-vite 的 H5/Web 目标，通常不需要禁用。

## 8. uni-app x 和 HBuilderX

uni-app x 建议使用 `uniAppX` 预设：

```ts title="vite.config.ts"
import { dirname, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { uniAppX } from 'weapp-tailwindcss/presets'
import { WeappTailwindcss } from 'weapp-tailwindcss/vite'

const projectRoot = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  plugins: [
    uni(),
    WeappTailwindcss(
      uniAppX({
        base: projectRoot,
        cssEntries: [
          resolve(projectRoot, 'main.css'),
        ],
        cssOptions: {
          rem2rpx: true,
        },
      }),
    ),
  ],
})
```

uni-app x 项目应显式写 `cssEntries`，指向纯 CSS 入口。

HBuilderX 本地运行时可以按目标分别验证：

```bash npm2yarn
npm run dev:mp-weixin
npm run dev:android:emulator
npm run dev:ios:simulator
```

如果用仓库里的本地 e2e，则是：

```bash npm2yarn
npm run e2e:hbuilderx:local:app
npm run e2e:hbuilderx:local:android
npm run e2e:hbuilderx:local:ios
```

iOS 模拟器需要完整 Xcode。`xcode-select -p` 应指向 `/Applications/Xcode.app/Contents/Developer`，`xcodebuild -checkFirstLaunchStatus` 应返回 0。

## 9. 验证迁移是否真的成功

只看构建成功还不够。迁移后至少测一条新增类。

在页面里临时写：

```html
<view class="mt-[11px] w-[173px] rounded-[13px] bg-[#102938] p-4 text-[#f7fbff]">
  v5 check
</view>
```

然后跑对应目标：

```bash npm2yarn
npm run dev:mp-weixin
```

H5/Web 项目再跑一次 HMR：启动 dev server 后，连续改几次任意值 class，确认 CSS 会刷新。例如把 `bg-[#102938]` 依次改成 `bg-[#0f5132]`、`bg-[#7c2d12]`、`bg-[#4338ca]`。如果第一遍有样式，后续新增任意值 class 没有样式，通常是入口扫描或 HMR 依赖没有接上。

App 端不要只看 `manifest.json`。uni-app x 的 Android 产物可以检查 `.uvue/app-android/**` 里是否出现转换后的类名；iOS 在 HBuilderX 不同版本下输出位置会不同，可以检查 `app-ios/app-service.js` 或 `unpackage/cache/.app-ios/sourcemap/app-service.js.map`。例如：

```txt
bg-[#102938]  -> bg-_b_h102938_B
text-[#f7fbff] -> text-_b_hf7fbff_B
w-[173px] -> w-_b173px_B
```

## 常见问题

| 现象 | 优先检查 |
| --- | --- |
| 完全没有样式 | CSS 入口是否被构建器引入，或是否需要配置 `cssEntries` |
| Tailwind CSS 4 类名没生成 | CSS 入口里的 `@source` 是否覆盖源码，是否排除了 `dist` / `unpackage` |
| 样式重复或顺序怪 | 小程序构建里是否还注册了 `tailwindcss` / `@tailwindcss/postcss` / `@tailwindcss/vite` |
| 安装后还在 patch | `package.json` 是否还保留 `postinstall: "weapp-tw patch"` |
| JS 字符串里的类名没转 | 这个类是否先被 Tailwind 扫描到了；v5 不会猜普通字符串 |
| H5 样式变成小程序转义类 | 检查 Web 目标环境变量，必要时显式设置 `generator.target: 'web'` |
| uni-app x App 样式缺失 | 检查是否启用 `uniAppX` 预设，Tailwind CSS 4 是否配置了 `cssEntries` |

## 迁移后可以删掉的东西

- `tailwindcss-patch`
- `postinstall: "weapp-tw patch"`
- 小程序构建里的 `@tailwindcss/vite`
- 小程序构建里的 `@tailwindcss/postcss`
- 小程序构建里的 `tailwindcss` PostCSS 插件
- 只为 H5/Web 写的 `disabled: isH5` 逻辑

不要急着删业务 PostCSS 插件、框架插件、Tailwind 配置文件。它们是否保留，取决于项目本身。

## 继续看

- [快速使用](/docs/quick-start/install)
- [Tailwind CSS 4 默认模式参考](/docs/tailwindcss/v4-reference)
- [v5 与官方 Tailwind 插件对照](/docs/tailwindcss/v5-official-plugin-parity)
- [uni-app x 专题](/docs/uni-app-x)

---

## 使用 arbitrary values


`arbitrary values` 是 `tailwindcss v3` 的重要更新内容，幸运的是你使用了本插件。

使得你可以使用 `tailwindcss v3` 强大的 `arbitrary values` 功能。

比如:

```html
<view :class="[flag?'bg-red-900':'bg-[#fafa00]']">bg-[#fafa00]</view>
<view :class="{'bg-[#098765]':flag===true}">bg-[#098765]</view>
<view class="p-[20px] -mt-2 !mb-[-20px] ">p-[20px] -mt-2 mb-[-20px] margin的jit 不能这么写 -m-[20px]</view>
<view class="space-y-[1.6rem]">
  <view class="w-[300rpx] text-black text-opacity-[0.19]">w-[300rpx] text-black text-opacity-[0.19]</view>
  <view class="min-w-[300rpx] max-h-[100px] text-[20px] leading-[0.9]">min-w-[300rpx] max-h-[100px] text-[20px] leading-[0.9]</view>
  <view class="max-w-[300rpx] min-h-[100px] text-[#dddddd]">max-w-[300rpx] min-h-[100px] text-[#dddddd]</view>
  <view class="flex items-center justify-center h-[100px] w-[100px] rounded-[40px] bg-[#123456] bg-opacity-[0.54] text-[#ffffff]">Hello</view>
  <view class="border-[10px] border-[#098765] border-solid border-opacity-[0.44]">border-[10px] border-[#098765] border-solid border-opacity-[0.44]</view>
  <view class="grid grid-cols-3 divide-x-[10px] divide-[#010101] divide-solid">
    <view>1</view>
    <view>2</view>
    <view>3</view>
  </view>
</view>
```

or `@apply`

```html
<template><view class="hello">world</view></template>
<style lang="scss">
.hello {
  @apply flex items-center justify-center h-[100px] w-[100px] rounded-[40px] bg-[#123456] bg-opacity-[0.54] text-[#ffffff] #{!important};
}
</style>
```

详见 [tailwindcss/using-arbitrary-values 章节](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values)

---

## js 中的精确转化与忽略


默认对所有 `jsx`、`js`、`wxml`、`wxss` 中出现的 `tailwindcss` 运行时工具类进行转化，如果不需要转化可以使用 `weappTwIgnore` 标识符来进行忽略:

例如:

```js
<view :class="classArray">classArray</view>

// weappTwIgnore 就是 String.raw ，所以它的结果就是后面字符串的结果
const weappTwIgnore = String.raw
const classArray = [
  'text-[30rpx]',
  weappTwIgnore`bg-[#00ff00]`
]

```

此时只有 `'text-[30rpx]'` 会被转化，`'bg-[#00ff00]'` 会被忽略。

> 默认情况下仅会忽略与 `weappTwIgnore` 有直接关系的标记模板，例如从包里导入后重命名、或在同一文件里一路别名过去的写法。简单的 `String.raw` 别名会继续参加转译，防止误杀。

如果需要自定义别名，可以包装一层函数并在配置里显式加入该别名，例如：

```js
const alias = (...args) => String.raw(...args)
// 在 ignoreTaggedTemplateExpressionIdentifiers 中加入 'alias'
```

或者直接使用 `ignoreTaggedTemplateExpressionIdentifiers` 配置追加其它标识符。

---

## weapp-tailwindcss 导出总览


> 本文根据 `packages/weapp-tailwindcss/package.json` 的 `exports` 字段整理，帮助你在不同框架/构建场景中快速定位合适的入口文件。

weapp-tailwindcss 同时提供 ESM 与 CommonJS 入口，并内置多个二级导出以适配 webpack、Vite、Gulp、Tailwind 宏等不同组合。下面按用途分类进行说明。

## 核心插件入口

| 导出路径 | 说明 | 典型用法 |
| --- | --- | --- |
| `weapp-tailwindcss` | 聚合入口：生成器、Webpack / Vite 历史插件名等常用工厂齐备 | `import { createWeappTailwindcssGenerator } from 'weapp-tailwindcss'`
| `weapp-tailwindcss/webpack` | webpack@5 适配入口（uni-app CLI、mpx、原生小程序等） | `const { WeappTailwindcss } = require('weapp-tailwindcss/webpack')`
| `weapp-tailwindcss/vite` | Vite 插件入口（Taro Vite、weapp-vite 等） | `import { WeappTailwindcss } from 'weapp-tailwindcss/vite'`
| `weapp-tailwindcss/core` | 暴露 `createContext` 等底层 API，可自定义 transform 流程 | `import { createContext } from 'weapp-tailwindcss/core'`

## 配置、工具与周边

| 导出路径 | 说明 | 场景 |
| --- | --- | --- |
| `weapp-tailwindcss/defaults` | 默认插件配置与运行时常量 | 查看/复用默认选项
| `weapp-tailwindcss/presets` | 官方预设集合（差异化策略、Tailwind 配置等） | 扩展或组合默认行为
| [`weapp-tailwindcss/reset`](./reset) | 内置默认 `button` reset，可通过 `buttonReset` 选项禁用或改写选择器 | `@plugin 'weapp-tailwindcss/reset';`
| `weapp-tailwindcss/types` | TypeScript 类型定义便捷入口 | `import type { UserDefinedOptions } from 'weapp-tailwindcss/types'`
| `weapp-tailwindcss/escape` | `replaceWxml`、`isAllowedClassName` 等字符串处理工具 | 单独处理模板/字符串时复用
| `weapp-tailwindcss/postcss-html-transform` | 针对 HTML/WXML 的 PostCSS 转换器 | 自定义 PostCSS 流程
| `weapp-tailwindcss/css-macro` | 旧版 Tailwind CSS 条件编译宏入口 | 存量项目迁移参考；新项目优先使用 Tailwind CSS v4 `@custom-variant`
| `weapp-tailwindcss/css-macro/postcss` | 旧版宏工具的 PostCSS 入口 | 仅用于自定义 PostCSS 流程或旧项目迁移
| `weapp-tailwindcss/gulp` | Gulp 插件入口 | 传统 Gulp 构建链集成
| `weapp-tailwindcss/package.json` | 包元数据 | 读取版本号等信息

> 补充：如果你需要的是“可直接导入的静态 reset 样式资源”，请使用独立包 [`@weapp-tailwindcss/reset`](/docs/community/reset)，而不是这里的 `weapp-tailwindcss/reset` 插件入口。

:::tip 插件命名
Vite、Webpack 与 Gulp 入口都导出 `WeappTailwindcss` 和 `weappTailwindcss` 两个别名。文档推荐使用大写 `WeappTailwindcss`；小写 `weappTailwindcss` 适合偏函数式命名的项目。
:::

## 样式资源

在 `tailwindcss@4` + `weapp-tailwindcss@5` 的项目样式入口里，推荐统一写 `@import 'tailwindcss';`。下面这些 `weapp-tailwindcss/*` CSS 导出是给兼容旧项目、直接引用静态子资源或自定义组合时使用的稳定路径。

| 导出路径 | 说明 | 引用示例 |
| --- | --- | --- |
| `weapp-tailwindcss/index.css` (`weapp-tailwindcss/index`) | 兼容 runtime 样式入口 | `@import 'weapp-tailwindcss/index.css';`
| `weapp-tailwindcss/preflight.css` (`weapp-tailwindcss/preflight`) | 小程序专用 Preflight | `@import 'weapp-tailwindcss/preflight.css';`
| `weapp-tailwindcss/theme.css` (`weapp-tailwindcss/theme`) | 主题变量定义 | `@import 'weapp-tailwindcss/theme.css';`
| `weapp-tailwindcss/utilities.css` (`weapp-tailwindcss/utilities`) | 原子类集合 | `@import 'weapp-tailwindcss/utilities.css';`
| `weapp-tailwindcss/with-layer.css` (`weapp-tailwindcss/with-layer`) | layer 版样式，适配 Tailwind v4 layer 写法 | `@import 'weapp-tailwindcss/with-layer.css';`
| `weapp-tailwindcss/uni-app-x.css` (`weapp-tailwindcss/uni-app-x`) | uni-app x 定制样式 | `@import 'weapp-tailwindcss/uni-app-x.css';`
| `weapp-tailwindcss/css` | 指向 `css/index.css`，兼容旧目录结构 | `@import 'weapp-tailwindcss/css';`

> ⚠️ 注意：不要在项目入口里写裸包名 `@import 'weapp-tailwindcss';`。部分构建工具（例如 `postcss-import`、mpx CLI）可能把它解析到 JS 入口（`dist/index.js`），并抛出 “Unknown word "use strict"”。Tailwind v4 项目入口请写 `@import 'tailwindcss';`；只有在明确需要直接引用静态子资源时，才使用上表里的 `weapp-tailwindcss/*` 路径。

## 其他导出

- `weapp-tailwindcss/*`：保留通配符路径，兼容历史文件结构；建议优先使用上表列出的稳定入口。
- 所有 JS 模块同时提供 `import` 与 `require` 两种格式，TS 项目结合 `types` 入口即可获得完整声明。

想进一步了解各模块暴露的 API，可以查阅 [`weapp-tailwindcss` API 总览](../api/index.md) 或直接阅读对应类型定义与源码。

---

## 选项概览

该章节的详细配置已经迁移至 [API / 配置项文档](/docs/api/interfaces/UserDefinedOptions)。

- [允许的类名写法](/docs/options/arbitrary-values)
- [注释用法与忽略开关](/docs/options/comments)

如果你在升级过程中需要参考原先的配置写法，请参见上方链接。

---

## `weapp-tailwindcss/reset`


`weapp-tailwindcss/reset` 提供一组面向小程序生态的 reset 插件能力，默认会：

- 清除所有 `button` 的原生样式（padding / 颜色 / border 等），让它的表现和 `view` / `text` 一致；
- 将 `<image>` / `<img>` 统一为 `display: block`，并限制为 `max-width: 100%`、`height: auto`。

你可以通过选项控制是否注入这些规则、改写选择器 / 声明，甚至追加自定义 reset。

> ℹ️ `weapp-tailwindcss/reset` 目前是兼容导出层，实际实现来自 `@weapp-tailwindcss/reset`。老项目可以继续使用原入口，新项目也可以直接从 `@weapp-tailwindcss/reset` 导入。

> ℹ️ 当你传入 `.class` / `#id` 作为选择器时，插件会自动转换为 `[class~="class"]` / `[id="id"]`，确保它们仍属于 base layer，不会破坏其他层级。

## 可用选项

- `preset?: 'minimal' | 'form' | 'content' | 'media' | 'all' | ResetPreset[]`
- `buttonReset?: false | ResetConfig`
- `imageReset?: false | ResetConfig`
- `inputReset?: false | ResetConfig`
- `textareaReset?: false | ResetConfig`
- `listReset?: false | ResetConfig`
- `navigatorReset?: false | ResetConfig`
- `videoReset?: false | ResetConfig`
- `extraResets?: ResetConfig[]`

```ts
interface ResetConfig {
  selectors?: string[]        // 支持元素 / 类名 / ID
  declarations?: Record<string, string | number | false>
  pseudo?: Record<string, string | number | false> // 注入到 ::after
}
```

设置为 `false` 即可关闭对应默认 reset；当提供类名 / ID 时会自动转换为 `[class~="foo"]` / `[id="bar"]`。

对于 `inputReset`、`textareaReset`、`listReset`、`navigatorReset`、`videoReset` 这类默认未开启的内置项，如果你直接传入配置对象，插件也会自动启用对应 reset，不必先额外声明 `preset`。

```ts
reset({
  inputReset: {
    selectors: ['.wx-reset-input'],
  },
  videoReset: {
    selectors: ['.wx-reset-video'],
  },
})
```

## preset

`preset` 用来快速启用一组内置 reset。默认不传时等价于 `minimal`，保持和旧版本一致，只注入 `button` 与 `image`。

- `minimal`：`button` + `image`
- `form`：`minimal` + `input` + `textarea`
- `content`：`minimal` + `ul/ol` + `navigator/a`
- `media`：`minimal` + `video`
- `all`：启用全部内置 reset

你也可以组合多个 preset：

```ts
reset({
  preset: ['content', 'media'],
})
```

## Tailwind 插件用法

```ts title="tailwind.config.ts"
import reset from 'weapp-tailwindcss/reset'

export default {
  plugins: [
    // 默认注入 button/image reset
    reset(),

    // 完全自定义
    reset({
      preset: 'form',
      buttonReset: {
        selectors: ['.wx-reset-btn', '#primary-btn'],
        declarations: {
          padding: '0',
          backgroundColor: 'transparent',
        },
        pseudo: {
          border: 'none',
        },
      },
      imageReset: {
        selectors: ['.wx-reset-image'],
        declarations: {
          display: 'inline-block',
          borderWidth: '0',
        },
      },
      listReset: {
        selectors: ['.wx-reset-list'],
      },
      extraResets: [
        {
          selectors: ['.wx-reset-view'],
          declarations: {
            display: 'block',
            borderWidth: '0',
          },
          pseudo: {
            borderColor: 'transparent',
          },
        },
      ],
    }),
  ],
}
```

关闭默认 reset：

```ts
reset({
  buttonReset: false,
  imageReset: false,
})
```

即使启用了 `preset`，你仍然可以通过把单项设置为 `false` 的方式精确关闭内置 reset：

```ts
reset({
  preset: 'all',
  listReset: false,
  videoReset: false,
})
```

## Tailwind CSS v4 用法

在入口 CSS 中通过 `@plugin` 注册即可：

```css title="app.css"
@plugin 'weapp-tailwindcss/reset';

@plugin 'weapp-tailwindcss/reset' ({
  preset: 'content',
  buttonReset: false,
  imageReset: {
    selectors: ['.wx-reset-image'],
    declarations: {
      display: 'inline-block',
    },
  },
  extraResets: [
    {
      selectors: ['.list-reset'],
      declarations: { listStyle: 'none', margin: '0', padding: '0' },
    },
  ],
});

@import 'tailwindcss/utilities';
```

同样可以通过 `buttonReset: false` / `imageReset: false` 精准控制需要的 reset。`preset` 负责批量开启内置规则，`extraResets` 允许你一次性追加多个自定义规则。