TailwindCSS Taro Plugin

超越 weapp-tailwindcss 的 TailwindCSS Taro 插件 - 零配置，开箱即用

🎯 核心优势

✨ 零配置体验

• 无需配置 "postinstall": "weapp-tw patch" 脚本
• 自动检测构建目录和文件
• 构建时自动执行所有兼容性处理
• 开箱即用，真正的零配置体验

🚀 超越 weapp-tailwindcss

• ✅ 更智能 - 自动检测和优化
• ✅ 更强大 - 更全面的兼容性处理
• ✅ 更高效 - 性能优化和缓存机制
• ✅ 更友好 - 详细的日志和错误处理
• ✅ 更完整 - 集成了 CLI 工具

🔧 完整功能

• 🎨 TailwindCSS v3/v4 支持 - 自动检测版本
• 📱 微信小程序兼容 - 100% 合法的 WXSS
• ⚡ Vite/Webpack 支持 - 双构建工具支持
• 🔄 热重载支持 - 开发体验优化
• 📊 性能分析 - 详细的构建报告
• 🛠️ CLI 工具 - 独立的命令行工具

🚀 快速开始

1. 安装

1npm install tailwindcss-taro
2# 或
3pnpm add tailwindcss-taro

2. 配置（零配置）

1// config/index.ts
2import { defineConfig } from '@tarojs/cli'
3import { createVitePlugin } from 'tailwindcss-taro'
4
5export default defineConfig({
6  compiler: {
7    type: 'vite',
8    vitePlugins: [
9      require('tailwindcss'),
10      require('autoprefixer'),
11      createVitePlugin() // 零配置，自动启用所有功能
12    ]
13  }
14})

3. 使用

1// 直接使用 TailwindCSS 类名
2function App() {
3  return (
4    <View className="flex items-center justify-center min-h-screen bg-gray-100">
5      <Text className="text-2xl font-bold text-blue-600">
6        Hello TailwindCSS Taro!
7      </Text>
8    </View>
9  )
10}

4. 构建

1npm run build:weapp
2# 插件自动执行：
3# ✅ 处理 TailwindCSS 样式
4# ✅ 自动 patch 构建产物
5# ✅ 修复类名和选择器
6# ✅ 添加运行时支持

✨ 零配置特性

🔧 自动 Patch 功能

插件内置自动 patch 功能，在构建完成后自动执行：

• ✅ 自动检测构建目录 - 支持 dist、build、output、miniprogram、weapp 等
• ✅ 自动处理 WXSS 文件 - 确保 CSS 100% 合法
• ✅ 自动修复类名 - 处理类名被去除的问题
• ✅ 自动修复选择器 - 处理选择器兼容性问题
• ✅ 自动添加运行时支持 - 提供调试和动态类名支持

📋 与 weapp-tw 的对比

功能	weapp-tw	tailwindcss-taro
需要 postinstall 脚本	✅ 必需	❌ 无需
自动检测构建目录	❌ 手动指定	✅ 自动检测
构建时自动执行	❌ 需要额外配置	✅ 自动执行
零配置使用	❌ 需要配置	✅ 完全零配置
智能错误处理	❌ 基础处理	✅ 智能处理
详细日志输出	❌ 基础日志	✅ 详细日志

🔧 高级配置

自定义配置（可选）

1createVitePlugin({
2  verbose: true, // 详细日志
3  enableAutoPatch: true, // 启用自动 patch（默认开启）
4  enableRuntime: true, // 启用运行时支持（默认开启）
5  enableClassPatch: true, // 启用类名修复（默认开启）
6  enableSelectorPatch: true, // 启用选择器修复（默认开启）
7  enablePerformanceOptimization: true, // 性能优化
8  enableBundleAnalysis: true, // 包分析
9  safelist: ['bg-red-500', 'text-blue-600'], // 安全列表
10  cssSelectorReplacement: {
11    root: 'page',
12    universal: 'view,text'
13  }
14})

Webpack 支持

1// config/index.ts
2import { defineConfig } from '@tarojs/cli'
3import { createWebpackPlugin } from 'tailwindcss-taro'
4
5export default defineConfig({
6  compiler: {
7    type: 'webpack',
8    webpackChain(chain) {
9      chain.plugin('tailwindcss-taro')
10        .use(createWebpackPlugin({
11          verbose: true
12        }))
13    }
14  }
15})

🛠️ CLI 工具

安装 CLI

1npm install -g tailwindcss-taro

使用 CLI

1# 自动 patch 构建产物
2tailwindcss-taro patch
3
4# 指定平台和目录
5tailwindcss-taro patch -p weapp -d ./dist
6
7# 启用所有功能
8tailwindcss-taro patch --runtime --class-patch --selector-patch -v
9
10# 分析构建产物
11tailwindcss-taro analyze -d ./dist

📊 性能优势

1. 智能缓存

• 缓存处理结果，避免重复计算
• 增量处理，只处理变化的文件
• 内存优化，自动清理过期缓存

2. 并行处理

• 支持并行处理多个文件
• 异步 I/O 操作优化
• 多进程处理大型项目

3. 性能监控

• 详细的构建时间统计
• 文件大小变化分析
• 缓存命中率监控

🔍 调试和监控

详细日志

1# 启用详细日志
2createVitePlugin({
3  verbose: true
4})
5
6# 输出示例：
7# 🚀 tailwindcss-taro 插件已加载
8# 📱 平台: weapp
9# 🎯 TailwindCSS 版本: v3
10# 🔧 自动 patch: 已启用
11# 📁 发现构建目录: dist
12# 📦 处理文件: app.wxss
13# 🔧 修复类名: pages/index/index.js
14# 🎉 自动 patch 完成！

性能监控

1createVitePlugin({
2  performanceMonitoring: {
3    enabled: true,
4    threshold: 1000, // 1秒
5    format: 'text'
6  }
7})

调试模式

1createVitePlugin({
2  debug: {
3    enabled: true,
4    level: 'debug',
5    outputFile: 'tailwindcss-taro-debug.log'
6  }
7})

📚 文档

• 快速开始 - 零配置快速上手
• 高级配置 - 详细配置说明
• 样式示例 - 常用样式示例
• 性能优化 - 性能优化指南
• 故障排除 - 常见问题解决
• 最佳实践 - 开发最佳实践
• CLI 使用 - CLI 工具使用指南
• 零配置指南 - 零配置特性详解

🎯 使用场景

1. 新项目

1# 创建新项目
2taro init myApp
3cd myApp
4
5# 安装插件
6npm install tailwindcss-taro
7
8# 零配置使用
9# 在 config/index.ts 中添加 createVitePlugin()

2. 现有项目

1# 安装插件
2npm install tailwindcss-taro
3
4# 替换现有配置
5# 移除 weapp-tailwindcss 相关配置
6# 添加 createVitePlugin()

3. 迁移项目

1# 从 weapp-tailwindcss 迁移
2npm uninstall weapp-tailwindcss
3npm install tailwindcss-taro
4
5# 移除 package.json 中的 postinstall 脚本
6# 更新配置文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境

1# 克隆项目
2git clone https://github.com/your-username/tailwindcss-taro.git
3cd tailwindcss-taro
4
5# 安装依赖
6npm install
7
8# 开发模式
9npm run dev
10
11# 构建
12npm run build
13
14# 测试
15npm run test

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

感谢以下项目的启发：

• weapp-tailwindcss - 原始灵感来源
• TailwindCSS - 优秀的 CSS 框架
• Taro - 跨端开发框架

---

🎉 享受零配置的 TailwindCSS Taro 开发体验！