{ "version": "https://jsonfeed.org/version/1", "title": "weapp-tailwindcss 博客订阅", "home_page_url": "https://next.tw.icebreaker.top/blog", "description": "tailwindcss 在小程序与多端开发中的更新、案例与教程资讯。", "items": [ { "id": "https://next.tw.icebreaker.top/blog/2025/11/v4.7.0-merge-runtime", "content_html": "

大家好，我是 weapp-tailwindcss、weapp-vite 的作者 icebreaker。

\n

最近我一直在思考 weapp-tailwindcss 的未来，以至于都没有怎么玩，最近回归的星际争霸2。

\n

巨大的阻碍​

\n

为什么？因为之前有一个很重要的问题，严重阻碍了 weapp-tailwindcss 发展的脚步。

\n

那就是 tailwind-merge / class-variance-authority / tailwind-variants 这些极其重要的原子化样式基础包，没有什么很好的办法在小程序里使用。

\n

为什么无法在小程序里使用？​

\n

简短一点来说，核心原因是，小程序 wxml 类名中，不允许很多特殊字符串，比如 !、[、]、# 等字符。

\n

所以 weapp-tailwindcss 根据这个设计，在编译时，就对 tailwindcss 类名进行转换，从而达到了兼容市面上众多小程序的编译插件。

\n

比如用户写的是 bg-[#123456]，被 weapp-tailwindcss 捕获到了之后，在编译的时候，就会同时把 wxml、js、wxss 里面的这个类名转换成小程序可以接受的 bg-_h123456_。

\n

而 tailwind-merge 它们都是在运行时进行计算的，那时候它们接收到的，已经是 bg-_h123456_ 这种转译之后的字符串，自然合并不了，导致到处出错。

\n

为了兼容，我做了非常多的尝试！给大家展示一下我的受苦之路吧！

\n

1. tailwind-merge plugin / createTailwindMerge​

\n

最直观的念头，就是给 tailwind-merge 写一个 weapp-tailwindcss 专用插件就好了!

\n

于是我开始阅读 tailwind-merge 源代码，并尝试使用 extendTailwindMerge 和 createTailwindMerge 完全创建出一个属于我自己的 weapp-tailwind-merge 来。

\n

在尝试过程中，我把 tailwind-merge 的内部冲突表导出，尝试用自定义 escape hook 覆盖那些非法字符；甚至写了一个半成品的 createTailwindMerge 变体，希望能在编译阶段就生成完全符合小程序命名规则的类名。

\n

然而，现实很快给了我当头棒喝：tailwind-merge 对运行时字符串的依赖极强，部分字符是强依赖，根本无法替换。

\n

下面这几个字符串都是写在常量里的，无法通过配置更换

\n
export const IMPORTANT_MODIFIER = '!' // 小程序不行
const MODIFIER_SEPARATOR = ':' // 小程序不行
\n

详见 https://github.com/dcastil/tailwind-merge/blob/v3.3.1/src/lib/parse-class-name.ts。

\n

所以这已经不是 extendTailwindMerge 和 createTailwindMerge 能够解决的问题了。

\n

摆在我面前的，是一条看不到未来的路：为了强行兼容，我需要重写它的核心，fork 一个全新的包，这个成本是巨大的。

\n

2. 编译期豁免​

\n

第二条路看起来更务实：沿用我熟悉的编译期管线，给 twMerge / twJoin / cva 等函数做“豁免处理”。

\n

我当时是这样想的，只要在编译时忽略它们内部的转义，运行时拿到的就是完整的 class 字符串，那 tailwind-merge 不就能工作了吗？

\n

然后我再包装一下 twMerge 函数，让它获取最后的结果的时候 escape 不就行了吗？

\n

大概长这样：

\n
export function cn(...inputs: ClassValue[]) {
  const result = twMerge(inputs)
  return escape(result)
}
\n

然后我让 cn 里面的字面量和模板字符串跳过转义不就行了吗？

\n
// 第一个是字符串，第二个是模板字符串，它们对应的 ast 类型不同，需要分开处理
// 里面的不转译
cn('bg-[#123456]',`bg-[#987654]`)

// 假如转译那么，结果如下
// cn('bg-_h123456_',`bg-_h987654_`)
\n

看上去运行良好，然而情况正在变得越来越复杂：

\n

嘿，变量引用来了：

\n
const a = 'bg-[#123456]';
cn(a,\"xx\",\"yy\")
\n

嘿嘿，变量引用 + 表达式来了：

\n
const a = 'bg-[#123456]' + ' bb' + ` text-[#123456]`;
cn(a,\"xx\",\"yy\")
\n

嘿嘿嘿，变量引用链路 + 表达式 + 模板插值来了：

\n
const b = 'after:xx';const a = 'bg-[#123456]' + ' bb' + `${b} text-[#123456]`;
cn(a,\"xx\",\"yy\")
\n

哈哈，只是在考验我操作 ast 进行预编译的水平而已！

\n

吃我一拳：ASTNodePathWalker + scope.getBinding + WeakMap，哈哈轻松消灭！

\n

于是我以为这条思路可行，编写了 @weapp-tailwindcss/merge 的 v1 版本。

\n

直到用户提交了新的 case！

\n

新的挑战​

\n

什么，怎么还有你们这种相互引用的情况！

\n
// shared2.js
export const ddd = 'bg-[#123456]';

const a = 'bg-[#123456]';

export {
  a as default
}
\n
// shared.js
export const a = 'bg-[#123456]';

const b = 'bg-[#123456]';

const c = 'bg-[#123456]';

const d = 'bg-[#123456]';

export default d

export {
  b
}

export {
  c as xaxaxaxa,
}

export * from './shared2'
\n
// main.js
import cc, { a as bb, b as aa } from './shared'
import * as shared from './shared'

cn(bb, cc, aa, shared.default, shared.a, \"[]\", \"()\")
\n

……我吐了，这是要我自己去实现一个 webpack / rollup 打包器嘛？有点搞不定啊！

\n

不过困难怕什么，我要迎难而上！于是我仿照了 rollup 的思路，收集了每个模块的 import / export 这里面大量的 ast 节点，并构建出了一个 ModuleGraph。

\n

另外表面上看这条路是可行的，我甚至找到了几个 demo 可以跑通，我还把豁免名单抽离出来，变成了 ignoreCallExpressionIdentifiers 配置项，以为自己解决了问题。

\n

然而理想很丰满，现实很骨感​

\n

这套方案高度依赖 AST 解析和构建工具的配合，我写的插件无法保证运行时得到的类名永远完整。构建链路上的任一环节——Terser、esbuild、rollup 插件甚至手写 Babel 宏——都可能把函数名或模板字符串的标识符压缩重命名，导致最后留给运行时的是一个残缺的字符串。

\n

用人话说就是 cn , twMerge, tv 这种方法，在产物里面被重命名成 e/a/c 这种玩意，所以我必须在压缩之前就进行豁免操作，但是那时候我似乎无法去准确收集产物的模块依赖情况(可能是水平不够导致的)。

\n

那一刻我意识到，所谓“编译期豁免”只是在延迟爆炸时间，而不是解除危机。

\n

在两条路都走到尽头之后，只剩下一个选择：彻底重构 merge，让逃逸逻辑回归运行时，让编译阶段恢复简单纯粹。

\n

为什么要重写 merge？​

\n

复盘 1.x 旧版 merge，我发现我当时的设计基于两个假设：一是 tailwind-merge 的输入输出始终可控，二是编译器可以精准标记所有“需要放行”的调用。这两个假设已经被现实击碎。

\n

早期的 @weapp-tailwindcss/merge 主要目标是“把 tailwind-merge 的结果变成小程序合法类名”。我采取的策略是：

\n\n

这种模式在 Tailwind CSS v3 勉强能用，但一到 v4 就崩溃了：

\n
    \n
  1. 编译期豁免并不等于安全
    \ntwMerge('text-[#ececec]', 'text-(--my-custom-color)') 最终仍然输出原始字符串。稍微复杂一点的条件拼接、链式调用、动态导入，编译器根本判断不出来该不该跳过。
    2. \n
  2. 函数名黑名单无法覆盖新的 API
    \n新版本开始导出 create()、variants（tv）等工厂，调用形式千奇百怪，编译阶段根本匹配不到。
    3. \n
  3. 任意值语法越来越灵活
    \nTailwind v4 的任意值可以是 text-[theme(my.scale.foo)] 这种无法静态推断类型的写法。靠黑名单永远落后，反而让用户更困惑。
    4. \n
\n

新版 merge 的核心思路​

\n

决定“把锅背回运行时”以后，我做的第一件事就是把入口全部进行统一：twMerge / twJoin / createTailwindMerge / extendTailwindMerge / cva / variants……统统绑进同一套 transformer 里。

\n

思路很简单：先找出它们共有的“进场”和“退场”动作，再把逃逸拆成前后两个钩子， escape 和 unescape。

\n
const transformers = resolveTransformers(options)

const aggregators = {
  escape: transformers.escape,
  unescape: transformers.unescape,
}
\n

在实现里我刻意把 escape 和 unescape 拆成两个“齿轮”。不管是用户直接手点 twMerge，还是 variants 工厂兜一圈回来，都会先进统一的预处理，再丢给 tailwind-merge。

\n

这等于在运行时补了一层“语义编译器”。

\n

双向处理链​

\n

所以现在每次 merge 现在都得过一遍 unescape -> tailwind-merge -> escape 这样的流程：

\n
 const normalized = transformers.unescape(clsx(...inputs))
 return transformers.escape(fn(normalized))
\n

但是这样还不够，为了实现 escape 和 unescape 我还必须从源头上出发，更改 @weapp-core/escape 的转译规则，才能让每一个字符串映射变得独一无二

\n

重写 @weapp-core/escape​

\n

老 escape 工具一直挂在 @weapp-core/escape 上，它走的是“多对一”映射，贴一段旧代码大家感受一下：

\n
export const MappingChars2String: MappingStringDictionary = {
  '[': '_',
  ']': '_',
  // for tailwindcss v4
  '(': 'y',
  ')': 'y',
  '{': 'z',
  '}': 'z',
  '+': 'a',
  ',': 'b',
  ':': 'c',
  '.': 'd',
  '=': 'e',
  ';': 'f',
  '>': 'g',
  '#': 'h',
  '!': 'i',
  '@': 'j',
  '^': 'k',
  '<': 'l',
  '*': 'm',
  '&': 'n',
  '?': 'o',
  '%': 'p',
  '\\'': 'q',
  '$': 'r',
  '/': 's',
  '~': 't',
  '|': 'u',
  '`': 'v',
  '\\\\': 'w',
  '\"': 'x',
}
\n

问题马上就来了：它完全做不到配对 unescape。[ 和 ] 被一起砸成 _，( / )、{ / } 也全堆在同一个值上，运行时根本还原不回去。举个让人头疼的例子：escape('[bg:red]') === '__bg_red_'。

\n

所以我直接把 @weapp-core/escape 推倒重练，写成一个可逆的“状态机”。每个非法字符都分到独一无二的逃逸片段，还带长度前缀，跑完 unescape(escape(input)) 就一定回到原样。为了防止它在极端输入上翻车，我拉了十几组 property-based 测试，emoji、空格、重复 escape 全安排上写了大量的单元测试，确保往返都符合预期。

\n

下面是当前版本的核心映射表，展示了我如何为每个非法字符分配唯一的 escape 片段，便于和旧版多对一的写法做对比：

\n
export const MappingChars2String = {
  '[': '_b',
  ']': '_B',
  '(': '_p',
  ')': '_P',
  '#': '_h',
  '!': '_e',
  '/': '_f',
  '\\\\': '_r',
  '.': '_d',
  ':': '_c',
  '%': '_v',
  ',': '_m',
  '\\'': '_a',
  '\"': '_q',
  '*': '_x',
  '&': '_n',
  '@': '_t',
  '{': '_k',
  '}': '_K',
  '+': '_u',
  ';': '_j',
  '<': '_l',
  '~': '_w',
  '=': '_z',
  '>': '_g',
  '?': '_Q',
  '^': '_y',
  '`': '_i',
  '|': '_o',
  '$': '_s',
} as const
\n

文章里我只放这份“简化表”，因为它才是运行时默认用的版本，开发者平时看到的也是它。更复杂的兼容映射我留在文档和测试里。

\n

运行时配置​

\n

新的 create() 可以随手关掉任意环节，这是和社区聊得最多的诉求。有团队想“开箱默认就好”，也有老项目背着一堆历史包袱，得慢慢迁移。所以我直接给了一排明确开关，想保守就保守，想激进就激进。

\n
const { twMerge: passthrough } = create({ escape: false, unescape: false })
\n

配合 SSR 或老数据兼容的时候，也不用再额外写工具函数：服务端直接把 escape 全关掉，只做 merge 校验；到小程序再开回完整逃逸步奏，迁移过程就能一步一步踩稳。

\n

另外还开放了 map 字段，用于统一用自己的字符映射。

\n

发布 4.7.x 版本​

\n

绕了这么多弯，所有成果最终都塞进了 weapp-tailwindcss@4.7.x 和 @weapp-tailwindcss/merge@2.x 中。算是 weapp-tailwindcss 运行时时代的第一声号角。

\n

欢迎大家把新版 @weapp-tailwindcss/merge 用到真实项目里，更欢迎在社区继续砸想法，我会把这些反馈当作下一轮迭代的燃料，让 Tailwind CSS 在小程序世界里始终“开箱即用”。

\n

有时候我也在想，为小程序这个逐渐感觉不怎么活跃的生态，花了这么多时间，感觉有点不值。但是转念一想，起码在我这个领域我已经通过不断的学习，真的掌握了很多东西。

\n

起码，对 Tailwind CSS 进行符合中国小程序技术特色的改造方面，我也算是第一人了吧。每每想到这，就感觉自己好像还稍微有这么一点点自豪呢，哈哈哈。

\n

如果你也在思考工具链，编译，AST 等等方面的问题，希望这篇文章能给你一点启发。

\n

源代码附录​

\n", "url": "https://next.tw.icebreaker.top/blog/2025/11/v4.7.0-merge-runtime", "title": "重新思考 weapp-tailwindcss 的未来", "summary": "从编译期豁免到**运行时**自管理，weapp-tailwindcss/merge 的重构思路与未来规划。", "date_modified": "2025-11-02T00:00:00.000Z", "author": { "name": "icebreaker", "url": "https://github.com/sonofmagic" }, "tags": [ "merge", "runtime", "tailwindcss" ] }, { "id": "https://next.tw.icebreaker.top/blog/2025/9/v4.3-release", "content_html": "

weapp-tailwindcss@4.3.0 默认开启 CSS 变量计算模式，并补充了更细粒度的 cssCalc、px2rpx 等配置，显著提升了多端 rpx 与 calc 的兼容性。本文带你了解这些变化的原理与使用方法。

\n

CSS变量计算模式​

\n

在 tailwindcss@4 下，默认启用 CSS 变量计算模式。tailwindcss@3 默认不启用。

\n

此模式下会去预编译所有的 css 变量和 calc 计算表达式。

\n

比如 tailwindcss@4 下原先生成的样式为:

\n
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: calc(var(--spacing) * 2);
}
\n

在CSS变量计算模式启动，进行预编译之后，现在的结果为:

\n
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
  height: calc(var(--spacing) * 2);
}
\n

这个模式可以解决很多手机机型 calc rpx 单位的兼容问题

\n
\n

可通过给插件，传入 cssCalc 配置项 false 来手动关闭这个功能

\n
\n

假如这时候你需要去除 CSS 变量的声明，你可以传入

\n
{
  cssCalc: ['--spacing']
}
// 或者更精确的
{
  cssCalc: {
    includeCustomProperties: ['--spacing']
  }
}
\n
\n

你也可以传入正则表达式

\n
\n

这样生成的结果就是:

\n
page,
:root {
  --spacing: 8rpx;
}
.h-2 {
  height: 16rpx;
}
\n

通过这种方式可以解决手机机型 calc rpx 单位的兼容问题

\n

详见: https://tw.icebreaker.top/docs/api/interfaces/UserDefinedOptions#csscalc

\n

新增配置项​

\n

px2rpx​

\n

添加 px2rpx 配置项， 用于控制是否将 px 单位转换为 rpx 单位， 默认为 false

\n

传入 true 则会将所有的 px 单位, 1:1 转换为 rpx 单位

\n

假如需要更多的转化方式，可以传入一个 object, 配置项见 https://www.npmjs.com/package/postcss-pxtransform

\n

logLevel​

\n

添加 logLevel 配置项，用于控制日志输出级别， 默认为 info

", "url": "https://next.tw.icebreaker.top/blog/2025/9/v4.3-release", "title": "4.3.0 🚀", "summary": "weapp-tailwindcss@4.3.0 默认开启 CSS 变量计算模式，并补充了更细粒度的 cssCalc、px2rpx 等配置，显著提升了多端 rpx 与 calc 的兼容性。本文带你了解这些变化的原理与使用方法。", "date_modified": "2025-09-13T00:00:00.000Z", "author": { "name": "icebreaker", "url": "https://github.com/sonofmagic" }, "tags": [] }, { "id": "https://next.tw.icebreaker.top/blog/2025/8/v4.2-release", "content_html": "

weapp-tailwindcss@4.2.x 现已适配 uni-app x 的多端构建能力，让 Tailwind CSS 原子类能够无缝跨端使用。本文梳理了从项目初始化到插件配置的完整流程，帮助你快速完成集成与发布。

\n

前言​

\n

uni-app x 是 DCloud 团队开发的跨平台编译方案，可将同一份代码编译到 Web、小程序、Android、iOS、鸿蒙等多端。

\n

最近，我很荣幸在 weapp-tailwindcss@4.2.x 版本中，适配了 uni-app x 的多端构建，使 Tailwind CSS 的原子化样式能够无缝应用于多端项目。

\n

所以就有了这篇文章，给大家介绍(秀)一下怎么在 uni-app x 项目中，集成 weapp-tailwindcss 这个样式解决方案。

\n

快速集成​

\n

0. 创建项目​

\n

使用最新版本 Hbuilderx 创建一个 uni-app x 项目，然后在项目根目录执行

\n
npm init -y
\n

初始化一个 package.json 文件 (当然你也可以手动创建)

\n

1. 安装并引入 tailwindcss@3​

\n
# 安装 tailwindcss@3 版本的依赖
npm i -D tailwindcss@3 postcss autoprefixer
# 初始化一个 tailwind.config.js 文件
npx tailwindcss init
\n

然后，在你的根目录中的 App.uvue 中引入 tailwindcss 使它在应用全局生效

\n
App.uvue
<style>
@tailwind base;
@tailwind components;
@tailwind utilities;
</style>
\n

2. 安装 weapp-tailwindcss​

\n

在项目目录下，执行:

\n
npm i -D weapp-tailwindcss
\n

然后把下列脚本，添加进你的 package.json 的 scripts 字段里:

\n
package.json
 \"scripts\": {
   \"postinstall\": \"weapp-tw patch\"
 }
\n

想知道原因的同学可以查看 这个链接

\n

3. uni-app x 中注册 weapp-tailwindcss​

\n

3.0. 创建辅助函数​

\n

在项目中创建 shared.js 文件，用于存放一些工具函数：

\n
shared.js
const path = require('node:path')
// 绝对路径处理
function r(...args) {
  return path.resolve(__dirname, ...args)
}

module.exports = {
  r,
}
\n

3.1. 配置 Vite​

\n

创建 vite.config.ts 文件，注册插件：

\n
\n

这里特别注意 uniAppX 是从 weapp-tailwindcss/presets 这个预设中导出的

\n
\n
vite.config.ts
import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';
import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite'
import { r } from './shared'
import { uniAppX } from 'weapp-tailwindcss/presets'
import tailwindcss from 'tailwindcss'

export default defineConfig({
    plugins: [
        uni(),
        UnifiedViteWeappTailwindcssPlugin(
            uniAppX({
                base: __dirname,
                rem2rpx: true,
            }),
        ),
    ],
    css: {
        postcss: {
            plugins: [
                tailwindcss({
                    config: r('./tailwind.config.js'),
                }),
            ]
        }
    }
});
\n

3.2. 更改 tailwindcss 配置​

\n

你需要在 tailwind.config.js 的 content 配置中，使用绝对路径去包括所有的提取文件

\n
tailwind.config.js
const { r } = require('./shared')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    r('./pages/**/*.{uts,uvue}'),
    r('./components/**/*.{uts,uvue}') 
  ],
  corePlugins: {
    preflight: false,
  },
}

\n
\n

如需从更多目录提取样式 token，可按需扩展 content。

\n
\n
\n

在完成这些步骤之后， uni-app x 就集成 tailwindcss 原子化样式解决方案。

\n

如何运行​

\n

目前 uni-app x 并没有提供任何 cli 的方式去使用它，所以目前我们使用 Hbuilderx 去进行开发和构建的。

\n

这里可以使用 Hbuilderx 的运行，来运行到各个平台。

\n

优先使用安卓进行开发​

\n

一般来说，CSS 平台的兼容程度，是 Web > 小程序 > App(安卓/IOS/鸿蒙)

\n

所以，假如你有跨多端的需求，建议你一开始使用 安卓模拟器 来进行开发和调试，这是综合考虑下来 成本最低 的方案。

\n

🧐为什么?​

\n

因为 uni-app x 开发原生 app 是有一些限制的，

\n
    \n
  1. \n

    比如文字必须包括在 <text> 标签中，文字的样式(比如 text-2xl text-center text-red-400) 也必须设置在这个元素上，设置在 <view> 上是没有效果的。而 Web 和 小程序 都是兼容的。

    \n
    2. \n
  2. \n

    还有很多 css 的样式，目前 uni-app x 暂时是不兼容的，强行使用 Hbuilderx 的控制台会爆出警告，要求你进行更改。

    \n
    3. \n
\n

这就相当于，你写的代码，能够满足了 安卓 这一端，那就大概率能满足 小程序 端，甚至 Web 端了(当然实战中还需要很多条件编译处理)

\n

🧐为什么不是 IOS 或者鸿蒙?​

\n

IOS 模拟器，需要你有 Mac 才能运行，IOS 调试需要你有苹果手机，考虑到大部分开发应该都是用的 Windows 机器，所以选择 Android 模拟器开发，相对成本低一些，你都有的话当我没说

\n

至于鸿蒙，uni-app x 官方文档上都写着:

\n
\n

鸿蒙整体处于发展初期，能用，有坑，大部分坑有规避方案。但开发者应建议其领导、客户、质量部门降低期望，不能严格比照Android和iOS的验收标准要求鸿蒙。

\n
\n

不如安卓/IOS 稳定的话，自然优先选择安卓平台

\n

常见问题​

\n

Vscode uvue/uts 代码染色​

\n

安装 DCloud 自己推出的 uni-app x语言服务, 插件市场一搜 uni-app x 就搜到了

\n\n

Tailwindcss 智能提示​

\n

目前 Tailwindcss 智能提示最好的还是 vscode，但是 vscode Tailwindcss 肯定是不认识 uvue/uts 文件的，

\n

要让插件认识，只需要在你的项目中添加 .vscode/settings.json 文件

\n
{
    \"tailwindCSS.includeLanguages\": {
        \"uvue\": \"html\",
        \"uts\": \"javascript\"
    }
}
\n

当然，你直接全局修改你的 vscode Tailwindcss 插件配置肯定也是可以的。

\n

尾言​

\n

uni-app x 是一个 庞大的工程, DCloud 团队能做出这样的技术解决方案，令人倾佩。

\n

假如你遇到什么问题，可以在 weapp-tailwindcss 的 issue/disscussions 中提出。

\n

配置好的模板​

\n

https://github.com/icebreaker-template/uni-app-x-hbuilderx

\n

使用方式见这个项目中的 README.md

\n

参考文档​

\n

uni-app x 官方文档

\n

weapp-tailwindcss 官网

\n

weapp-tailwindcss 的 uni-app x 专题

", "url": "https://next.tw.icebreaker.top/blog/2025/8/v4.2-release", "title": "4.2.0 🚀", "summary": "weapp-tailwindcss@4.2.x 现已适配 uni-app x 的多端构建能力，让 Tailwind CSS 原子类能够无缝跨端使用。本文梳理了从项目初始化到插件配置的完整流程，帮助你快速完成集成与发布。", "date_modified": "2025-08-01T00:00:00.000Z", "author": { "name": "icebreaker", "url": "https://github.com/sonofmagic" }, "tags": [] }, { "id": "https://next.tw.icebreaker.top/blog/2025/3/v4-release", "content_html": "

weapp-tailwindcss v4.0 正式发布，核心亮点是兼容 tailwindcss@4 并引入 tailwind-merge 运行时整合能力。文章总结了升级背后的思路，并提供 uni-app 示例帮助你快速落地。

\n

\"4.0

\n

总结​

\n

经历了一番自虐式开发后，weapp-tailwindcss v4.0 终于发布了！

\n

在清理了一些自己当初写的屎山代码后，我终于实现了心心念念的两个大功能：

\n
    \n
  1. 支持 tailwindcss@4.x 版本
    2. \n
  2. 支持 tailwind-merge
    3. \n
\n
\n

因为 tailwindcss@4 直接变成了一个样式预处理器，定位上类似 Sass / Less，所以相关的改动还是挺大的。目前 weapp-tailwindcss@4 版本也同时兼容 tailwindcss 4+3+2(jit) 三个版本了。

\n
\n

想快速上手集成？欢迎访问 weapp-tailwindcss 官网！\n如果你想进一步了解细节，下面有个示例，看看就懂了。

\n
\n

uni-app 快速集成示例​

\n

这里我们以 uni-app（Vue3 + Vite） 为例。

\n

1. 安装依赖​

\n
npm install -D tailwindcss @tailwindcss/vite weapp-tailwindcss
\n

然后，把下面这段脚本加入 package.json 的 scripts 字段里：

\n
package.json
{
  \"scripts\": {
    \"postinstall\": \"weapp-tw patch\"
  }
}
\n
\n

这个补丁是为了让 tailwindcss@4 认识 rpx 单位，否则它会以为 rpx 是个颜色单位，导致 text-[40rpx] 这样的样式翻车。

\n
\n
\n

2. 配置 vite.config.ts​

\n
vite.config.ts
import uni from '@dcloudio/vite-plugin-uni'
import { defineConfig } from 'vite'
import { UnifiedViteWeappTailwindcssPlugin } from 'weapp-tailwindcss/vite'

export default defineConfig(async () => {
  // 这里必须这样引用，因为 uni 只提供 cjs 版本，而 @tailwindcss/vite 只提供 esm 版本
  const { default: tailwindcss } = await import('@tailwindcss/vite')
  return {
    plugins: [
      uni(),
      tailwindcss(),
      UnifiedViteWeappTailwindcssPlugin({ rem2rpx: true })
    ],
  }
})
\n
\n

3. 添加样式​

\n

在项目目录下创建 main.css，然后添加以下内容：

\n
main.css
@import 'weapp-tailwindcss/index.css';
\n
\n

注意：对于实际运行时入口，现在更推荐直接写 @import 'weapp-tailwindcss/index.css'，而不是继续依赖 rewriteCssImports 去改写 @import 'tailwindcss'。

\n
\n

接着在 main.js 里引用这个文件作为全局样式，然后直接运行：

\n
npm run dev:mp-weixin
\n

在微信开发者工具中导入这个项目，在项目中使用 tailwindcss 原子类，即可看到效果。

\n
\n

遇到的问题以及解决方案​

\n

1. tailwindcss@4 的样式兼容性问题​

\n

tailwindcss@4 生成的样式广泛使用了 @layer、color-mix、oklch 等新特性，现代浏览器兼容性都不咋地，更别说小程序了。

\n

所以无论是 H5 还是小程序，都需要 postcss-preset-env 来降级这些样式的生成结果。降级的程度取决于你的 browserslist 配置。

\n
\n

2. tailwind-merge 样式合并问题​

\n

tailwind-merge 是一个 tailwindcss 运行时样式合并工具，它能自动合并重复的样式。不过，小程序端用 tailwind-merge 有点挑战，因为：

\n\n

这导致 tailwind-merge 处理已转义的 class 时，误以为它们是普通 class，而不是 tailwindcss 的原子类。

\n

解决方案：编译时感应 + 运行时合并转义​

\n

我研究了一下 tailwind-merge 的源码，尝试写一个 plugin 来解决这个问题，结果发现路走不通，因为：

\n\n

于是，我换了个思路，采用编译时感应、忽略转义，运行时合并转义的方式 解决了这个问题，这就是 @weapp-tailwindcss/merge 诞生的原因。

\n

编译时感应的原理​

\n

我利用 babel 的 scope（作用域） 和 binding（绑定） 增强了识别能力

\n

scope 简而言之就是 js 基础里的大括号, binding 就是一个变量真正的绑定

\n

比如：

\n
const b = 'after:xx'
const a = `${b} text-[#123456]`
cn(a, 'xx', 'yy')
\n

这段代码的作用域是全局，然后 cn 中 a 的绑定是一个 VariableDeclaration 它的 init 中，又引用了 b ，它的绑定也是一个 VariableDeclaration 初始化是一个 StringLiteral

\n

于是，在编译时，我们可以从 cn 递归向上找到 a 和 b，识别出完整的样式链。

\n

当然，另一种方式是 自上而下查找，通过 import 语句分析模块依赖关系，甚至可以利用打包工具的模块分析图进行静态分析。

\n

当然这块的实现被用在了 @weapp-tailwindcss/merge 中，详见 tailwind-merge 快速开始。

\n
\n

开发心得​

\n

在开发的时候，一定要把可能影响结果的方式，拆成多多阶段运行，比如在修改 js ast 的时候，不应该一边 traverse ，一边再用 MagicString 去修改，而是应该把需要修改的地方，先全部收集出来，然后在一个阶段统一去修改。

\n

另外鉴别一个 ast 工具的成熟度，也应该考虑一下，作用域和绑定的关系，能否被解析出来。比如我们都知道 js 里面大概有 5 种行为会产生作用域:

\n\n

而绑定本身也是通过 scope 和它的 parent 依次向上去找的。

\n

最后一点碎碎念​

\n

转眼我也到了而立之年，在这个行情下，毕业（失业）随时可能发生，当然也不敢毕业，毕竟上有老下有小，还有各种贷款。

\n

技术学得越多，越觉得是个无底洞。而且掌握的东西多了，好像也没什么收益。更何况前端技术和那种 AI 技术相比，就像是过家家一样的。

\n

开源呢？搞了半天也没啥产出，想成为开源明星，但自己技术水平也没到那个级别。

\n

最近，我开始深入学习 云原生，因为我意识到，国内这种国情下 \"技术是工具，业务才是目的\"。

\n

这导致我们技术人员的地位是非常低的，这点只要还在国内混就无法改变。

\n

所以我们自己也不要对自己或者团队写的东西，搞得有多好多完美的似的。够用就行，多尝试，先快速搞他个 100 个应用，然后挑没死的去进行进一步的开发。

\n

举个例子，现在让我从 0 到 1 搭建一个完整的业务系统，我可以全程自主搞定：

\n\n

但问题是——开发成本和时间成本太高了！

\n

这种情况，我要自己去设计数据库，写 openapi.yml ，然后实现接口，还要自己写前端，和自己对接。写的差不多了还要测试，又是一堆 bug。

\n

而且还可能遇到技术难点，之前我在 Node.js 中实现 PostgreSQL 的 GraphQL 方案，就折腾了好久。这种情况，为什么不直接上 pg_graphql 这种成熟的中间件呢？

\n

所以，从商业角度来看：

\n
    \n
  1. 写尽可能少的代码，尽量利用成熟方案快速搭建业务。
    2. \n
  2. 赚钱才是第一要务，哪里有问题，先堆机器解决，实在搞不定了，再招专业人才处理。
    3. \n
  3. 多利用AI来降本增效，AI 成本比人低，所以招个高级，不如招个初级的，会用 AI 的，学习能力好的程序员，毕竟前端静态页面，AI 生成可快了
    4. \n
\n

所以，从一个程序员的视角出发:

\n

这是最好的时代，也是最坏的时代。

\n
\n

参考链接​

\n\n
\n

补充：classic uni-app vue2 / webpack 路线已经不再推荐，新项目请优先选择 uni-app vue3 vite。

\n
", "url": "https://next.tw.icebreaker.top/blog/2025/3/v4-release", "title": "4.0.0 🚀", "summary": "weapp-tailwindcss v4.0 正式发布，核心亮点是兼容 tailwindcss@4 并引入 tailwind-merge 运行时整合能力。文章总结了升级背后的思路，并提供 uni-app 示例帮助你快速落地。", "date_modified": "2025-03-01T00:00:00.000Z", "author": { "name": "icebreaker", "url": "https://github.com/sonofmagic" }, "tags": [] } ] }