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

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

## 设计目标

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

## 关键设计决策

### 1. 用内联样式替代不兼容的 Tailwind 类
- `bg-white/20` → `style="background-color: rgba(255, 255, 255, 0.2);"`
- `text-white/80` → `text-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 不兼容的转义选择器`。