⚙️ 一般配置
本页收录 18 个配置项，来源于 UserDefinedOptions。
配置一览
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| supportCustomLengthUnitsPatch | boolean | ILengthUnitsPatchOptions | — | 控制 Tailwind 自定义长度单位补丁。 |
| appType | AppType | — | 声明所使用的框架类型。 |
| arbitraryValues | IArbitraryValues | — | TailwindCSS 任意值的相关配置。 |
| unocss | boolean | IUnocssCompatibilityOptions | false | 启用部分 UnoCSS class 写法兼容。 |
| jsPreserveClass | (keyword: string) => boolean | undefined | — | 控制 JS 字面量是否需要保留。 |
| jsArbitraryValueFallback | boolean | "auto" | — | 控制 JS 任意值类名在 classNameSet 异常时的受控兜底策略。 |
| replaceRuntimePackages | boolean | Record<string, string> | — | 是否替换运行时依赖包名。 |
| generator | import("../..").WeappTailwindcssGeneratorOptions | — | 控制 Tailwind CSS 直接生成目标端 CSS 的策略。 |
| disabledDefaultTemplateHandler | boolean | false | 禁用默认的 wxml 模板替换器。 |
| tailwindcssBasedir | string | — | 指定用于获取 Tailwind 上下文的路径。 |
| cache | boolean | ICreateCacheReturnType | — | 控制缓存策略。 |
| babelParserOptions | | — | @babel/parser 的配置选项。 |
| cssChildCombinatorReplaceValue | string | string[] | 'view + view' | 自定义 Tailwind 子组合器的替换值。 |
| postcssOptions | | — | postcss 的配置选项。 |
| cssRemoveHoverPseudoClass | boolean | | 是否移除 CSS 中的 :hover 选择器。 |
| cssRemoveProperty | boolean | | 是否移除 @property 节点。 |
| tailwindcssPatcherOptions | TailwindCssPatchOptions | — | 自定义 patcher 参数。 |
| logLevel | "error" | "warn" | "silent" | "info" | — | 控制命令行日志输出级别。 |
详细说明
supportCustomLengthUnitsPatch
可选 | 类型:
boolean | ILengthUnitsPatchOptions
控制 Tailwind 自定义长度单位补丁。
参阅
https://github.com/sonofmagic/weapp-tailwindcss/issues/110
备注
TailwindCSS 3.2.0 起对任意值执行长度单位校验，会将未声明的 rpx 识别为颜色。本选项默认开启，并由构建运行时自动接管。
appType
可选 | 类型:
AppType
声明所使用的框架类型。
备注
用于辅助定位主要的 CSS bundle，以便默认的 mainCssChunkMatcher 做出更准确的匹配，未传入时将尝试自动猜测变量注入位置。
arbitraryValues
可选 | 类型:
IArbitraryValues
TailwindCSS 任意值的相关配置。
unocss
可选 | 类型:
boolean | IUnocssCompatibilityOptions| 默认值:false
启用部分 UnoCSS class 写法兼容。
备注
默认关闭。传入 true 后会启用 Tailwind CSS v3 / v4 裸任意值生成。class 字符转义继续由
customReplaceDictionary 控制，JS 转译仍遵循 classNameSet 精确命中原则。
默认值
false
jsPreserveClass
可选 | 类型:
(keyword: string) => boolean | undefined| 版本: ^2.6.1
控制 JS 字面量是否需要保留。
备注
当 Tailwind 与 JS 字面量冲突时，可通过回调返回 true 保留当前值，返回 false 或 undefined 则继续转义。默认保留所有带 * 的字符串字面量。
参数
keyword
string
返回
boolean | undefined
jsArbitraryValueFallback
可选 | 类型:
boolean | "auto"
控制 JS 任意值类名在 classNameSet 异常时的受控兜底策略。
备注
为避免误伤业务字符串，兜底仅在 class 语义上下文生效。
false：关闭兜底；true：始终开启受控兜底；'auto'：仅 TailwindCSS v4 且 classNameSet 为空时启用。
replaceRuntimePackages
可选 | 类型:
boolean | Record<string, string>
是否替换运行时依赖包名。
备注
适用于运行时包名需要重定向的场景，例如：
- 小程序侧无法直接安装
tailwind-merge/class-variance-authority/tailwind-variants，需要替换为内置的 weapp 版本。 - 企业内私有镜像/多包发布导致运行时包名不同，希望在转换后统一到目标包名。
传入
true使用内置替换表，或传入对象自定义映射。
示例
replaceRuntimePackages: {
'tailwind-merge': '@weapp-tailwindcss/merge',
'class-variance-authority': '@weapp-tailwindcss/cva',
}
generator
可选 | 类型:
import("../..").WeappTailwindcssGeneratorOptions
控制 Tailwind CSS 直接生成目标端 CSS 的策略。
备注
默认值会按构建环境推断：小程序构建使用 weapp，H5/Web 与普通 uni-app App WebView 使用 web。
uni-app x 原生 App 目标继续通过 uniAppX 配置处理 uvue/App 约束，不需要配置 target: 'app'。
disabledDefaultTemplateHandler
可选 | 类型:
boolean| 默认值:false| 版本: ^2.6.2
禁用默认的 wxml 模板替换器。
备注
启用后模板匹配完全交由 customAttributes 管理，需要自行覆盖默认的 class / hover-class 等匹配规则。
默认值
false
tailwindcssBasedir
可选 | 类型:
string| 版本: ^2.9.3
指定用于获取 Tailwind 上下文的路径。
备注
在 linked 或 monorepo 场景下可手动指向目标项目的 package.json 所在目录。
cache
可选 | 类型:
boolean | ICreateCacheReturnType| 版本: ^3.0.11
控制缓存策略。
babelParserOptions
可选 | 类型:
(Partial<Options> & { cache?: boolean | undefined; cacheKey?: string | undefined; cacheMaxEntries?: number | undefined; cacheMaxSourceLength?: number | undefined; })| 版本: ^3.2.0
@babel/parser 的配置选项。
cssChildCombinatorReplaceValue
可选 | 类型:
string | string[]| 默认值:'view + view'
自定义 Tailwind 子组合器的替换值。
备注
为兼容小程序缺乏 :not([hidden])~ 支持的限制，默认会将 .space-x-4 等选择器替换为 view + view。可传入字符串或字符串数组以扩展适用标签。
// 数组示例
.space-y-4>view + view,text + text{}
// 字符串示例
.space-y-4>view,text,button,input ~ view,text,button,input{}
默认值
'view + view'
postcssOptions
可选 | 类型:
Partial<Omit<import(".pnpm/postcss-load-config@6.0.1_jiti@2.7.0_postcss@8.5.15_tsx@4.22.4_yaml@2.9.0/node_modules/postcss-load-config").Result, "file">>| 版本: ^3.2.0
postcss 的配置选项。
cssRemoveHoverPseudoClass
可选 | 类型:
boolean| 默认值:\true`` | 版本: ^3.2.1
是否移除 CSS 中的 :hover 选择器。
参阅
https://github.com/sonofmagic/weapp-tailwindcss/issues/293
备注
小程序不支持 :hover，需要使用组件的 hover-class，因此默认删除相关节点。
默认值
true
cssRemoveProperty
可选 | 类型:
boolean| 默认值:\true`` | 版本: ^4.1.2
是否移除 @property 节点。
备注
微信小程序可识别 @property，但支付宝暂不支持，默认移除以避免构建失败。
默认值
true
tailwindcssPatcherOptions
可选 | 类型:
TailwindCssPatchOptions
自定义 patcher 参数。
logLevel
可选 | 类型:
"error" | "warn" | "silent" | "info"
控制命令行日志输出级别。
备注
默认 info，可设置为 silent 屏蔽全部输出。
