| name | weapp-tailwindcss |
| description | 帮助用户在 uni-app、taro、uni-app x 与原生小程序项目中接入和排障 weapp-tailwindcss。Use when 用户提到 weapp-tailwindcss、小程序 Tailwind 不生效、rpx 任意值、JS 字符串 class、space-y/space-x、weapp-tw patch、@source、twMerge/cva/tv。 |
weapp-tailwindcss Skill
用于业务项目接入 weapp-tailwindcss，并让 AI 稳定完成“小程序 + 多端”配置、排障与 Tailwind 写法规范落地。
本 Skill 服务“项目使用者”场景，不是仓库内部二次开发指南。
适用任务
- 新项目快速启用
tailwindcss + weapp-tailwindcss
- 老项目迁移（
uni-app / taro / uni-app x / 原生小程序）
- 多端协同（小程序 +
H5 / App）配置
- 样式不生效、
rpx 任意值异常、JS 字符串 class 未转译等问题排查
- 需要“Tailwind class 应该怎么写”的团队规范与代码评审清单
任务分流
先判断用户当前任务类型，再进入对应流程：
- 集成新项目
- 迁移存量项目
- 排查已有问题
- 沉淀 Tailwind 写法规范
信息收集最小集
缺少关键信息时，先补齐后再输出方案：
- 当前框架：
uni-app / taro / uni-app x / 原生小程序 / 其他
- 构建工具：
vite / webpack5 / webpack4 / 其他
- 目标端：仅小程序，还是小程序 +
H5 / App
tailwindcss 主版本（v3 / v4）与包管理器（重点确认是否 pnpm@10+）- 运行环境：
node 版本（weapp-tailwindcss@5.2.0 起要求 >=22.12.0）；涉及 HBuilderX 时确认版本 >=5.11
- 当前诉求是“集成配置 / 问题排查 / 写法规范沉淀”中的哪一类
执行流程
1) 基线配置（所有任务通用）
- 先判断 Tailwind 主版本与扫描方式：
tailwindcss@4 用入口 CSS 的 @source- 扫描范围必须覆盖真实模板与脚本文件，并排除
dist / unpackage / node_modules
- 生成模式不再要求
postinstall，也不需要手动执行 weapp-tw patch
weapp-tw patch 仅作为旧脚本兼容提示保留；排障优先检查入口 CSS、@source、cssEntries 和构建插件是否生效
2) 按任务类型执行
3) 回归验证（所有任务都要给）
- 先跑开发态，再跑目标端构建
- 至少验证 3 类样式：基础工具类、任意值（含
rpx）、变体/伪类
- 若
JS/TS 中 class 不生效，优先检查 @source 是否覆盖该文件与扩展名
- 若
space-y-* / space-x-* 不生效，固定优先级：
- 先改结构（子节点落到
view/text 或外层补 view）
- 再评估
virtualHost
- 最后才扩展
cssChildCombinatorReplaceValue（保持最小标签集合）
输出格式要求
最终输出必须包含：
- 结论（适用框架、Tailwind 版本、目标端）
- 修改文件清单（按文件逐条列出）
- 可直接复制的配置片段
- 安装/运行命令（默认
pnpm）
- 验证步骤与预期结果
- 回滚方案（至少一条）
若用户要求“规范沉淀”，额外补充：
- 推荐写法（Do）
- 禁止写法（Don't）
- 最小回归检查清单（Code Review Checklist）
关键约束
- 不要再要求用户执行
weapp-tw patch；当前版本由构建运行时自动接管 Tailwind CSS 处理
- 不要把小程序转译插件无条件应用到纯
H5 场景
- 不要忽略
@source 范围配置；这会直接导致 class 不生成
- 不要建议“运行时自由拼接 class 字符串”作为常规方案；优先枚举化或
cva/tv
- 对
text-[22rpx]、bg-[22rpx] 等二义性任意值，提供 length: / color: 前缀作为兜底写法
- 涉及
twMerge / twJoin / cva / cn / tv 的封装或重命名时，提醒配置 ignoreCallExpressionIdentifiers
- 需要原样透传第三方类名时，优先使用
weappTwIgnore
- 对
space-y-* / space-x-*，默认按 view + view（含 text）处理，不要假设会自动覆盖全部标签
space-y-* / space-x-* 的标签扩展应最小化，只加入业务确实需要的标签，避免选择器污染- 不要提供与仓库原则冲突的建议：
JS 转译基于 classNameSet 精确命中，禁止启发式兜底转译
- 对版本不确定时，优先给出与官方文档一致的最小可用方案，再做增量优化
引用资料
