weapp-tailwindcss 是一套面向全端的 Tailwind CSS 工具链，把 Tailwind CSS 的原子化开发体验带到 Web/H5、小程序、App WebView、React Native 和 Lynx。它解决的问题是：用同一套 Tailwind 输入，按目标端生成正确的产物，而不是为每个平台维护一套互不相干的 class 规则。当前主线维护 Tailwind CSS v4。
一、项目官方信息
| 项目 | 信息 |
|---|---|
| GitHub 仓库 | https://github.com/weapp-tailwindcss/weapp-tailwindcss |
| 官方网站/文档 | https://tw.weapp.dev |
| 开源协议 | MIT |
| 主要语言 | TypeScript（约 71.2%） |
| Star 数 | 约 1.9k |
| 主线版本 | Tailwind CSS v4 |
核心包负责 Tailwind CSS v4 的 CSS 生成、类名转译、平台兼容和构建器生命周期集成；平台包与运行时包把能力延伸到不同渲染器与应用框架。
二、官方图片
weapp-tailwindcss 官方 Logo：
三、环境要求
- Node.js
^22.18.0 || >=24.11.0。 - Tailwind CSS
>=4.0.0。 - 使用 HBuilderX 的 uni-app / uni-app x 项目需要 HBuilderX
>=5.11。 - 包管理器推荐 pnpm。
四、完整接入步骤
1. 安装 Tailwind CSS 与核心包
pnpm add -D tailwindcss weapp-tailwindcss
2. 创建 CSS-first 入口
新建 src/app.css（或项目现有 CSS 入口）：
@import "tailwindcss";
@source "./**/*.{html,js,ts,jsx,tsx,vue}";
@source not "../node_modules";
@source not "../dist";
入口文件必须被项目实际引入；cssEntries 只用于让生成器稳定识别 Tailwind 入口，不会替代 bundler 的模块图。
3. 注册构建器插件（以 Vite 为例）
纯 Web 项目使用 CSS-only 入口：
import { defineConfig } from 'vite'
import { WeappTailwindcssWeb } from 'weapp-tailwindcss/vite/web'
export default defineConfig({
plugins: [
WeappTailwindcssWeb(),
],
})
vite/web 只处理 Tailwind CSS 生成、CSS transform、CSS HMR 和 Web CSS 收尾，不注册 JS/template 转译、框架扩展、分包或小程序 finalizer。需要同时支持小程序、框架扩展或多入口时，使用 weapp-tailwindcss/vite 主入口，并显式指定 generator.target 或 platform。
4. 小程序构建
微信、支付宝、抖音、QQ 等小程序的 CSS 生成，使用对应构建器入口，或通过 CLI：
pnpm add -D @weapp-tailwindcss/cli weapp-tailwindcss tailwindcss
pnpm exec weapp-tw -i src/app.css -o dist/app.wxss --target weapp
--target weapp 是 CSS-only 转换，不会扫描或改写 WXML/JS。
五、使用方法
支持的目标端
| 目标端 | 推荐入口 | 适用场景 |
|---|---|---|
| Web / H5 | weapp-tailwindcss/vite/web 或 vite/webpack/rspack/gulp/Node API |
浏览器 CSS、H5、普通 Web 构建 |
| 小程序 | 构建器入口或 @weapp-tailwindcss/cli --target weapp |
微信/支付宝/抖音/QQ 小程序 CSS |
| App WebView | 框架集成 | uni-app、Taro 等 App WebView 构建 |
| uni-app x | weapp-tailwindcss/vite |
Android/iOS/HarmonyOS 原生构建 |
| React Native / Expo | @weapp-tailwindcss/react-native |
Metro/Babel/RN style manifest |
| ReactLynx / Rspeedy | @weapp-tailwindcss/lynx |
Lynx CSS 与 Rspeedy 构建 |
Canonical 模板
仓库内提供可独立安装验证的最小模板：
- uni-app + Vue 3：
templates/uni-app-tailwindcss-v4 - Taro + Vite + React：
templates/taro-vite-tailwindcss-v4 - weapp-vite 原生小程序：
templates/weapp-vite-tailwindcss-v4
这些模板只使用 weapp-tailwindcss 生成 Tailwind CSS，不要再叠加 @tailwindcss/postcss 或 @tailwindcss/vite。
选择正确的包
| 需求 | 包 |
|---|---|
| Tailwind CSS 生成、类名转译、构建器接入 | weapp-tailwindcss |
| 独立 CSS CLI、watch、canonicalize | @weapp-tailwindcss/cli |
| PostCSS AST、选择器兼容、CSS 平台转换 | @weapp-tailwindcss/postcss |
| React Native/Expo 编译 | @weapp-tailwindcss/react-native |
| ReactLynx/Rspeedy 集成 | @weapp-tailwindcss/lynx |
| twMerge/tv/cva 等运行时 class 工具 | @weapp-tailwindcss/runtime、@weapp-tailwindcss/merge 等 |
重要边界
- Tailwind CSS v4 的生成由
weapp-tailwindcss接管，小程序构建中不要同时注册tailwindcss、@tailwindcss/postcss或@tailwindcss/vite作为第二套生成器。 - JS/WXML 类名只转换 Tailwind generator 已确认生成的精确候选集合，不对普通业务字符串做启发式替换。
- React Native、Lynx、小程序的 CSS 能力不等同于浏览器，不支持的属性以目标端测试结果为准。
六、常见问题 FAQ
1. 为什么同时配了 weapp-tailwindcss 和 @tailwindcss/vite 后样式错乱？
Tailwind CSS v4 的生成已由 weapp-tailwindcss 接管，不要再注册第二套生成器。移除 @tailwindcss/postcss 或 @tailwindcss/vite，只保留 weapp-tailwindcss 的插件。
2. Node 版本有要求吗？
需要 Node.js ^22.18.0 || >=24.11.0，低版本会安装失败或运行异常。
3. 想单独生成小程序 wxss 怎么办？
用 CLI：pnpm exec weapp-tw -i src/app.css -o dist/app.wxss --target weapp，这是纯 CSS 转换，不涉及 WXML/JS 改写。
4. uni-app 项目接哪个入口？
uni-app + Vite 用 weapp-tailwindcss/vite；uni-app x 用同一 vite 入口；HBuilderX 需 >=5.11。完整配置见框架接入指南。
5. 模板里为什么不能再装 @tailwindcss/vite？ 官方 canonical 模板已经用 weapp-tailwindcss 接管生成，再装会造成双生成器冲突，样式可能重复或丢失。
6. 文档在哪里？
官网 https://tw.weapp.dev ，含快速开始、v4 指南、框架接入、CLI、API 参考等；示例在仓库 demo/ 与 examples/ 目录。