生成模式使用方式（推荐）
生成模式推荐把 weapp-tailwindcss 作为项目里唯一负责 Tailwind CSS 样式生成的入口。你可以按项目需要安装 tailwindcss@3 或 tailwindcss@4，weapp-tailwindcss 会读取当前安装的 Tailwind 主版本，并按对应策略代理整个项目的样式生成。
核心变化是：实际项目中不需要再注册 @tailwindcss/vite、@tailwindcss/postcss 或其他 Tailwind 官方构建插件；构建插件或 PostCSS 插件开启 generator 后，最终产物会直接面向小程序，而不是先生成浏览器 CSS 再做大量兜底兼容。
如果你正在接入 Tailwind CSS 或准备升级到 v5，优先从生成模式开始。它会直接生成小程序目标 CSS，并用 classSet 精确约束 JS / 模板转译范围。
安装
生成模式只需要安装 tailwindcss 和 weapp-tailwindcss，不需要安装 Tailwind 官方构建插件，也不需要再配置 postinstall 脚本。
选择 Tailwind CSS v4：
- npm
- Yarn
- pnpm
- Bun
npm install -D tailwindcss@4 weapp-tailwindcss
yarn add --dev tailwindcss@4 weapp-tailwindcss
pnpm add -D tailwindcss@4 weapp-tailwindcss
bun add --dev tailwindcss@4 weapp-tailwindcss
选择 Tailwind CSS v3：
- npm
- Yarn
- pnpm
- Bun
npm install -D tailwindcss@3 weapp-tailwindcss
yarn add --dev tailwindcss@3 weapp-tailwindcss
pnpm add -D tailwindcss@3 weapp-tailwindcss
bun add --dev tailwindcss@3 weapp-tailwindcss
安装哪个主版本，生成模式就默认按哪个主版本的策略生成样式。Tailwind CSS v4 项目使用 CSS-first 入口和 @source；Tailwind CSS v3 项目继续使用 tailwind.config.js 的 content 和 theme。
按框架选择入口
| 场景 | 文档 | 推荐入口 | 注册位置 | CSS 入口 |
|---|---|---|---|---|
| uni-app Vue Vite | uni-app 生成模式 | WeappTailwindcss | vite.config.ts | src/main.css |
| uni-app Vue2 Webpack | uni-app 生成模式 | WeappTailwindcss | vue.config.js 的 configureWebpack | src/app.css |
| Taro Vite | Taro 生成模式 | WeappTailwindcss | config/index.ts 的 compiler.vitePlugins | src/app.css |
| Taro Webpack | Taro 生成模式 | WeappTailwindcss | config/index.ts 的 mini.webpackChain | src/app.css |
| weapp-vite | weapp-vite 生成模式 | WeappTailwindcss | vite.config.ts | app.css 或项目全局样式 |
| Mpx | Mpx 生成模式 | PostCSS 默认导出 + Webpack WeappTailwindcss | mpx.config.js | src/app.css |
生成模式下不要再把 @tailwindcss/vite 或 @tailwindcss/postcss 注册到实际项目里，否则会形成两套 Tailwind 生成链路。Vite、Webpack、Webpack4 与 Gulp 入口推荐导入大写 WeappTailwindcss；小写 weappTailwindcss 也可用，适合偏函数式命名的项目。PostCSS 入口继续使用默认导出。
CSS 入口
Tailwind CSS v4 项目的 CSS 入口建议使用 CSS-first 写法：
@import "tailwindcss";
@source "./src/**/*.{vue,js,ts,wxml,tsx,jsx}";
@source not "./dist";
Tailwind CSS v3 项目可以继续把扫描范围写在 tailwind.config.js：
export default {
content: ['./src/**/*.{vue,js,ts,wxml,tsx,jsx}'],
theme: {
extend: {},
},
}
默认小程序产物不需要写完整对象，直接开启即可：
generator: true
如果希望显式写出目标，也可以只传 target：
generator: {
target: 'weapp',
}
这两种写法都会使用默认的 mode: 'auto' 和 target: 'weapp'。小程序选择器兼容配置也有默认值，cssChildCombinatorReplaceValue 默认就是 ['view', 'text']，只有项目需要改成自定义组件标签时才需要传 styleOptions。
CI 严格校验时可以额外传 mode: 'force'。这样生成失败会直接让构建失败，避免静默回退到旧 CSS 后处理链路。
功能覆盖清单
| 能力 | uni-app Vite | uni-app Webpack | Taro Vite | Taro Webpack | weapp-vite | Mpx |
|---|---|---|---|---|---|---|
标准 @import "tailwindcss" | 是 | 是 | 是 | 是 | 是 | 是 |
Tailwind CSS v4 @source | 是 | 是 | 是 | 是 | 是 | 是 |
@theme / @config | 是 | 是 | 是 | 是 | 是 | 是 |
generator: true 默认启用 | Vite 插件 | Webpack 插件 | Vite 插件 | Webpack 插件 | Vite 插件 | PostCSS 插件 |
target = "weapp" 小程序产物 | 是 | 是 | 是 | 是 | 是 | 是 |
target = "web" 多端调试 | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 |
rem2rpx / rpx 任意值 | 是 | 是 | 是 | 是 | 是 | 是 |
| hover / active / dark / important / arbitrary value | 是 | 是 | 是 | 是 | 是 | 是 |
| JS / 模板动态类精确转译 | 是 | 是 | 是 | 是 | 是 | 是 |
@weapp-tailwindcss/merge 运行时合并 | 是 | 可用 | 可用 | 可用 | 可用 | 可用 |
| CSS dependency / HMR 依赖追踪 | 是 | 是 | 是 | 是 | 是 | 是 |
Web 目标调试
同一入口也可以设置 generator: { mode: 'force', target: 'web' } 生成浏览器 CSS，用于多端调试或对比 Tailwind 原始产物。target: 'web' 不做小程序选择器转义，也不会移除浏览器需要的 hover media；小程序生产构建应使用 target: 'weapp'。
验证矩阵
建议在合并 v5 示例时至少跑：
pnpm --filter weapp-tailwindcss test
pnpm --filter @weapp-tailwindcss-demo/mpx-tailwindcss-v5 build
pnpm build:apps
pnpm build:demo
其中 Taro 与 uni-app 的聚合构建可能被 guard 跳过；需要严格验证时，在交互式终端显式设置 TARO_BUILD_STRICT=1 或 UNI_BUILD_STRICT=1。
部署后验证
如果文档站使用预览域名或 Cloudflare Git 部署，建议在部署完成后直接检查新路由和旧入口是否符合预期：
curl -I https://next.tw.icebreaker.top/docs/quick-start/v4/v5-generator-examples
curl -I https://next.tw.icebreaker.top/docs/quick-start/v4/generator/uni-app
curl -I https://next.tw.icebreaker.top/docs/quick-start/v4/generator/taro
这些路由应返回 200；如果线上还没有出现新页面，优先检查 Cloudflare 的构建分支、构建命令、部署命令和输出目录是否与仓库配置一致。
