Agent Skills › sonofmagic/weapp-tailwindcss › weapp-tailwindcss-troubleshoot

weapp-tailwindcss-troubleshoot

GitHub

用于诊断 weapp-tailwindcss 与 CLI 的样式未生成、转译失败、多端兼容及 HMR 等问题。通过结构化步骤定位根因并提供修复方案，排除配置猜测。

skills/weapp-tailwindcss-troubleshoot/SKILL.md sonofmagic/weapp-tailwindcss

Trigger Scenarios

Tailwind CSS 在微信小程序中未生效 CLI 构建输出异常或失败 HMR 热更新失效多端样式兼容性调试

Install

npx skills add sonofmagic/weapp-tailwindcss --skill weapp-tailwindcss-troubleshoot -g -y

More Options

Use without installing

npx skills use sonofmagic/weapp-tailwindcss@weapp-tailwindcss-troubleshoot

指定 Agent (Claude Code)

npx skills add sonofmagic/weapp-tailwindcss --skill weapp-tailwindcss-troubleshoot -a claude-code -g -y

安装 repo 全部 skill

npx skills add sonofmagic/weapp-tailwindcss --all -g -y

预览 repo 内 skill

npx skills add sonofmagic/weapp-tailwindcss --list

SKILL.md

Frontmatter

{
    "name": "weapp-tailwindcss-troubleshoot",
    "description": "诊断 weapp-tailwindcss 与 `weapp-tw` CLI 的样式未生成、JS\/模板 class 未转译、classNameSet、@source\/cssEntries、source candidates、rpx、伪类\/custom variant、组件隔离、Rspack、压缩、watch\/HMR、H5\/Web\/App\/uni-app x 多端产物问题。Use for debugging, troubleshooting, CLI output failures, classes not working, broken hot reload, wrong output, or runtime compatibility；不用于新项目配置、自研 API 设计或 Lynx 专属接入。"
}

weapp-tailwindcss troubleshoot

从生成、转译、产物到运行时逐层定位根因，避免用配置猜测掩盖症状。

诊断顺序

收集最小复现：框架、bundler、目标端、版本、命令、原始 class、期望与实际产物。
读取 references/symptom-matrix.md，先归类症状，再执行对应最短路径。
检查 Tailwind 入口是否为纯 CSS、是否实际进入构建图、cssEntries 是否为绝对路径、@source 是否覆盖源码。
检查是否存在第二个 Tailwind 生成器，或 H5/Web 被错误 disabled。
分别验证 CSS 候选、模板/JS safe class、最终平台样式文件和真实页面；不要只看固定的 app.wxss 文件名。
watch/HMR 问题要在同一进程连续新增 class，区分首次构建成功与增量图失效。
CLI 问题先确认 web/weapp target、stdin/stdout、source map 与 watch 模式，不期待它改写模板或脚本。
只有根因确认后才修改配置，并补一条可重复的回归验证。

安全边界

JS 转译只接受 Tailwind 验证过的 classNameSet；未命中时修复扫描或刷新时序，不启用启发式全字符串转译。
space-* 先处理结构和组件虚拟节点，再最小扩展 cssOptions.cssChildCombinatorReplaceValue。
App WebView 兼容必须记录 Android Chromium、iOS WebKit 或 Harmony/HBuilderX 环境，并以真实运行截图或日志为证据。
不为排障临时加入 @tailwindcss/vite 或 @tailwindcss/postcss。
ReactLynx/Rspeedy 构建与 CSS encoder 问题转到 $weapp-tailwindcss-lynx。