2026-06-26-fix-wxss-escape-selectors-design.md 1.7 KB


comet_change: fix-wxss-escape-selectors role: technical-design

canonical_spec: openspec

WXSS 转义选择器修复设计文档

设计目标

消除 refine-weapp-ui-style 上线后发现的微信小程序 WXSS 编译错误:Tailwind 的透明度/分数类(如 bg-white/20text-white/80)会生成 .bg-white\\/20 等带 \\/ 转义的选择器,微信小程序 WXSS 解析器无法识别。

关键设计决策

1. 用内联样式替代不兼容的 Tailwind 类

  • bg-white/20style="background-color: rgba(255, 255, 255, 0.2);"
  • text-white/80text-white + style="opacity: 0.8;"
  • 保持视觉表现不变,同时避免 Tailwind 编译出转义选择器。

2. 增强 WXSS 检查脚本

  • 更新 scripts/check-wxss-escapes.js 的正则,从仅检测 \\: / \\. 扩展到同时检测 \\/,确保 fractional/opacity 类也能被拦截。
  • 检测失败时输出明确的类名示例并退出非零,阻止问题进入产物。

3. 不涉及架构改动

  • 仅替换类名和增强脚本,不引入新的样式系统、不修改业务逻辑、不调整组件接口。

受影响文件

  • src/components/home/SalesHome.vue
  • src/components/home/DispatchHome.vue
  • src/components/home/ConstructionHome.vue
  • src/components/my/ProfileView.vue
  • scripts/check-wxss-escapes.js

风险与缓解

风险 缓解
后续再次引入 bg-*/*text-*/* 检查脚本已覆盖 \\/,构建会失败
内联样式与 Tailwind 类混用导致维护困难 本次范围极小,仅用于必须规避 WXSS 的场景

测试策略

  • npm run type-check 无 TS 错误。
  • npm run build:mp-weixin 成功,且 [check-wxss] app.wxss 未发现 WXSS 不兼容的转义选择器