⚙️ 一般配置

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/index.ts:13

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

配置一览

配置一览

配置项	类型	默认值	说明
appType	AppType	undefined	声明所使用的框架类型。
arbitraryValues	IArbitraryValues	{ allowDoubleQuotes: false }	TailwindCSS 任意值的相关配置。
babelParserOptions	(Partial<Options> & { cache?: boolean; cacheKey?: string; })	内置默认配置	@babel/parser 的配置选项。
cache	boolean | ICreateCacheReturnType	true	控制缓存策略。
cssChildCombinatorReplaceValue	string | string[]	['view', 'text']	自定义 Tailwind 子组合器的替换值。
cssRemoveHoverPseudoClass	boolean	true	是否移除 CSS 中的 :hover 选择器。
cssRemoveProperty	boolean	true	是否移除 @property 节点。
disabledDefaultTemplateHandler	boolean	false	禁用默认的 wxml 模板替换器。
jsPreserveClass	(keyword: string) => boolean | undefined	保留 * 字符串字面量	控制 JS 字面量是否需要保留。
logLevel	"info" | "warn" | "error" | "silent"	'info'	控制命令行日志输出级别。
postcssOptions	LoadedPostcssOptions	{}	postcss 的配置选项。
replaceRuntimePackages	boolean | Record<string, string>	false	是否替换运行时依赖包名。
supportCustomLengthUnitsPatch	boolean | ILengthUnitsPatchOptions	true	控制 Tailwind 自定义长度单位补丁。
tailwindcssBasedir	string	undefined	指定用于获取 Tailwind 上下文的路径。
tailwindcssPatcherOptions	TailwindcssPatchOptions	内置默认配置	自定义 patcher 参数。

常用配置模板

常用配置模板（Vite）

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  postcssOptions: {},
  cssRemoveHoverPseudoClass: true,
  cssRemoveProperty: true,
  logLevel: 'info',
})

详细说明

appType

可选 | 类型: AppType

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:30

声明所使用的框架类型。

默认值 / 说明 / 示例

备注

用于辅助定位主要的 CSS bundle，以便默认的 mainCssChunkMatcher 做出更准确的匹配，未传入时将尝试自动猜测变量注入位置。

默认值

undefined

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  appType: 'taro',
})

arbitraryValues

可选 | 类型: IArbitraryValues

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:37

TailwindCSS 任意值的相关配置。

默认值 / 说明 / 示例

备注

默认只允许单引号包裹任意值，开启 allowDoubleQuotes 后可使用双引号，但在部分模板编译链路中可能导致转义冲突（例如部分 Vue3 静态模板）。

默认值

{
  allowDoubleQuotes: false,
}

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  arbitraryValues: {
    allowDoubleQuotes: true,
  },
})

babelParserOptions

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

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:119

@babel/parser 的配置选项。

默认值 / 说明 / 示例

备注

用于控制 JS/TS 语法解析行为，如 sourceType、plugins 等。若只需少量覆盖，可在默认配置基础上追加。

默认值

{
  sourceType: 'unambiguous',
  cache: true,
  cacheKey: 'st:unambiguous',
}

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  babelParserOptions: {
    sourceType: 'unambiguous',
    plugins: ['typescript'],
  },
})

cache

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

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:111

控制缓存策略。

默认值 / 说明 / 示例

备注

默认开启内存缓存，提升多文件批处理性能。传入 false 可禁用缓存，或传入自定义 ICreateCacheReturnType 实现。

默认值

true

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  cache: false,
})

cssChildCombinatorReplaceValue

可选 | 类型: string | string[] | 默认值: ['view', 'text']

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:136

自定义 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','text']，内部会拼接为 view + view 等选择器组合。

默认值

['view', 'text']

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  cssChildCombinatorReplaceValue: ['view', 'text', 'button'],
})

cssRemoveHoverPseudoClass

可选 | 类型: boolean | 默认值: true | 版本: ^3.2.1

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:155

是否移除 CSS 中的 :hover 选择器。

默认值 / 说明 / 示例

参阅

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

备注

小程序不支持 :hover，需要使用组件的 hover-class，因此默认删除相关节点。

默认值

true

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  cssRemoveHoverPseudoClass: false,
})

cssRemoveProperty

可选 | 类型: boolean | 默认值: true | 版本: ^4.1.2

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:165

是否移除 @property 节点。

默认值 / 说明 / 示例

备注

微信小程序可识别 @property，但支付宝暂不支持，默认移除以避免构建失败。

默认值

true

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  cssRemoveProperty: false,
})

disabledDefaultTemplateHandler

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

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:77

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

默认值 / 说明 / 示例

备注

启用后模板匹配完全交由 customAttributes 管理，需要自行覆盖默认的 class / hover-class 等匹配规则。

默认值

false

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  disabledDefaultTemplateHandler: true,
  customAttributes: {
    '*': [/class/i],
  },
})

jsPreserveClass

可选 | 类型: (keyword: string) => boolean | undefined | 默认值: 见下方 | 版本: ^2.6.1

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:47

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

默认值 / 说明 / 示例

备注

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

默认值

(keyword) => {
  if (keyword === '*') {
    return true
  }
  return false
}

参数：keyword: string

返回：boolean | undefined

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  jsPreserveClass(keyword) {
    return keyword.startsWith('safe-')
  },
})

logLevel

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

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:180

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

默认值 / 说明 / 示例

备注

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

默认值

'info'

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  logLevel: 'silent',
})

postcssOptions

可选 | 类型: LoadedPostcssOptions | 版本: ^3.2.0

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:144

postcss 的配置选项。

默认值 / 说明 / 示例

备注

用于向样式处理流程注入额外的 PostCSS 插件或调整处理选项。

默认值

{}

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'
import postcssPresetEnv from 'postcss-preset-env'

uvtw({
  postcssOptions: {
    plugins: [
      postcssPresetEnv({ stage: 3 }),
    ],
  },
})

replaceRuntimePackages

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

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:66

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

默认值 / 说明 / 示例

备注

适用于运行时包名需要重定向的场景，例如：

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

默认值

false

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  replaceRuntimePackages: {
    'tailwind-merge': '@weapp-tailwindcss/merge',
    'class-variance-authority': '@weapp-tailwindcss/cva',
  },
})

supportCustomLengthUnitsPatch

可选 | 类型: boolean | ILengthUnitsPatchOptions

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:21

控制 Tailwind 自定义长度单位补丁。

默认值 / 说明 / 示例

参阅

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

备注

TailwindCSS 3.2.0 起对任意值执行长度单位校验，会将未声明的 rpx 识别为颜色。本选项默认开启以注入 rpx 支持。当 Node.js 在插件执行前已缓存 tailwindcss 模块时，首轮运行可能未生效，可通过在 postinstall 中执行 weapp-tw patch 提前打补丁。

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

默认值

true

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  supportCustomLengthUnitsPatch: {
    units: ['rpx', 'vw'],
  },
})

tailwindcssBasedir

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

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:103

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

默认值 / 说明 / 示例

备注

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

默认值

undefined

示例

import path from 'node:path'
import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  tailwindcssBasedir: path.resolve(__dirname, '../apps/miniapp'),
})

tailwindcssPatcherOptions

可选 | 类型: TailwindcssPatchOptions

定义于: packages/weapp-tailwindcss/src/types/user-defined-options/general.ts:172

自定义 patcher 参数。

默认值 / 说明 / 示例

备注

用于控制 tailwindcss-patch 的行为，如缓存、补丁开关、扫描路径等。一般无需配置，除非你需要自定义补丁策略或多项目共享缓存。

默认值

{
  filter: (className) => !isAllowedClassName(className),
}

示例

import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'

uvtw({
  tailwindcssPatcherOptions: {
    features: {
      extendLengthUnits: {
        enabled: true,
        units: ['rpx', 'vw'],
      },
    },
    cache: {
      enabled: true,
      dir: './node_modules/.cache/tw-patch',
    },
  },
})