TailwindCSS Taro Plugin

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

🎯 核心优势

✨ 零配置体验

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

🚀 超越 weapp-tailwindcss

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

🔧 完整功能

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

🚀 快速开始

1. 安装

npm install tailwindcss-taro
# 或
pnpm add tailwindcss-taro

2. 配置（零配置）

// config/index.ts
import { defineConfig } from '@tarojs/cli'
import { createVitePlugin } from 'tailwindcss-taro'

export default defineConfig({
  compiler: {
    type: 'vite',
    vitePlugins: [
      require('tailwindcss'),
      require('autoprefixer'),
      createVitePlugin() // 零配置，自动启用所有功能
    ]
  }
})

3. 使用

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

4. 构建

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

✨ 零配置特性

🔧 自动 Patch 功能

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

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

📋 与 weapp-tw 的对比

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

🔧 高级配置

自定义配置（可选）

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

Webpack 支持

// config/index.ts
import { defineConfig } from '@tarojs/cli'
import { createWebpackPlugin } from 'tailwindcss-taro'

export default defineConfig({
  compiler: {
    type: 'webpack',
    webpackChain(chain) {
      chain.plugin('tailwindcss-taro')
        .use(createWebpackPlugin({
          verbose: true
        }))
    }
  }
})

🛠️ CLI 工具

安装 CLI

npm install -g tailwindcss-taro

使用 CLI

# 自动 patch 构建产物
tailwindcss-taro patch

# 指定平台和目录
tailwindcss-taro patch -p weapp -d ./dist

# 启用所有功能
tailwindcss-taro patch --runtime --class-patch --selector-patch -v

# 分析构建产物
tailwindcss-taro analyze -d ./dist

📊 性能优势

1. 智能缓存

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

2. 并行处理

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

3. 性能监控

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

🔍 调试和监控

详细日志

# 启用详细日志
createVitePlugin({
  verbose: true
})

# 输出示例：
# 🚀 tailwindcss-taro 插件已加载
# 📱 平台: weapp
# 🎯 TailwindCSS 版本: v3
# 🔧 自动 patch: 已启用
# 📁 发现构建目录: dist
# 📦 处理文件: app.wxss
# 🔧 修复类名: pages/index/index.js
# 🎉 自动 patch 完成！

性能监控

createVitePlugin({
  performanceMonitoring: {
    enabled: true,
    threshold: 1000, // 1秒
    format: 'text'
  }
})

调试模式

createVitePlugin({
  debug: {
    enabled: true,
    level: 'debug',
    outputFile: 'tailwindcss-taro-debug.log'
  }
})

📚 文档

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

🎯 使用场景

1. 新项目

# 创建新项目
taro init myApp
cd myApp

# 安装插件
npm install tailwindcss-taro

# 零配置使用
# 在 config/index.ts 中添加 createVitePlugin()

2. 现有项目

# 安装插件
npm install tailwindcss-taro

# 替换现有配置
# 移除 weapp-tailwindcss 相关配置
# 添加 createVitePlugin()

3. 迁移项目

# 从 weapp-tailwindcss 迁移
npm uninstall weapp-tailwindcss
npm install tailwindcss-taro

# 移除 package.json 中的 postinstall 脚本
# 更新配置文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境

# 克隆项目
git clone https://github.com/your-username/tailwindcss-taro.git
cd tailwindcss-taro

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm run test

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

感谢以下项目的启发：

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

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