@weapp-tailwindcss/merge（Tailwind v4）

@weapp-tailwindcss/merge 是 tailwind-merge@3 的小程序友好封装，适配 tailwindcss@4。它在合并前后自动处理 escape/unescape，使运行时输出与编译期一致。

安装

npm

pnpm add @weapp-tailwindcss/merge

Yarn

pnpm add @weapp-tailwindcss/merge
# couldn't auto-convert command

pnpm

pnpm add @weapp-tailwindcss/merge
# couldn't auto-convert command

Bun

pnpm add @weapp-tailwindcss/merge
# couldn't auto-convert command

核心 API

• twMerge(...classValues)：合并 Tailwind 类名并去冲突。
• twJoin(...classValues)：拼接类名（不做冲突判断）。
• extendTailwindMerge(config) / createTailwindMerge(config)：扩展合并规则。
• create(options?)：创建隔离实例，控制 escape/unescape。
• weappTwIgnore：标记「不要转义」的模板字符串。

基础示例

import { twMerge } from '@weapp-tailwindcss/merge'

const className = twMerge(
  'px-2 py-1 bg-red hover:bg-dark-red',
  'p-3 bg-[#B91C1C]'
)

// => 已转义的类名，可直接写入小程序 class

扩展合并规则

import { extendTailwindMerge } from '@weapp-tailwindcss/merge'

const mergeCard = extendTailwindMerge({
  classGroups: {
    card: ['card-default', 'card-primary'],
  },
})

mergeCard('card-default card-primary') // => 'card-primary'

小程序用法

小程序端建议直接使用默认导出，运行时会自动输出转义后的类名：

import { twMerge } from '@weapp-tailwindcss/merge'

const buttonClass = twMerge(
  'inline-flex items-center rounded-md px-3 py-2 text-sm',
  isPrimary && 'bg-[#2563EB] text-white'
)

Web 用法（关闭转义）

在 Web/SSR 环境中，使用 create 关闭 escape/unescape：

import { create } from '@weapp-tailwindcss/merge'

// 跨平台框架请自行判断是否为 H5 构建，通常可从环境变量读取。
const isH5 = true
const { twMerge } = create({
  escape: !isH5,
  unescape: !isH5,
})

const className = twMerge('text-[#2563EB]', 'text-[#1D4ED8]')
// => 'text-[#1D4ED8]'

Demo：按钮类名合并

import { twMerge } from '@weapp-tailwindcss/merge'

const base = 'inline-flex items-center rounded-md px-4 py-2 text-sm font-medium'
const state = 'bg-[#2563EB] text-white hover:bg-[#1D4ED8]'
const override = 'px-6'

const className = twMerge(base, state, override)

常见注意事项

• 函数名保留：如果你把 twMerge 别名成 cn，需要在 ignoreCallExpressionIdentifiers 中补充该名称。
• 跳过编译期转义：当类名需要原样传递给第三方时，用 weappTwIgnore 标记模板字符串。

更多细节与调试指南见 集成与排障指南。