WXSS与CSS的区别：小程序样式开发从入门到实战迁移

刚开始写微信小程序的时候，我最大的困惑不是逻辑层和渲染层怎么通信，也不是路由怎么管理，而是：为什么样式不能直接用CSS？WXSS到底是个什么东西？估计不少人跟我一样，第一眼看到 WXSS 感觉它长得像CSS，但又总觉得哪里不对劲。等你真把一段写好的CSS粘进小程序项目里，各种样式不生效、真机和模拟器表现不一致的问题就全冒出来了。

这篇文章就把 WXSS 和 CSS 的区别讲透彻。我会从设计思路、语法能力、编译机制、实际踩坑几个维度展开，最后给一个完整的迁移示例，帮你在写小程序样式时少走弯路。适合两类读者：一是刚开始接触微信小程序、对样式体系还不熟悉的前端新手；二是从Web前端转小程序开发、经常被WXSS各种限制搞到崩溃的从业者。

1. 为什么小程序不直接沿用CSS——先搞清楚WXSS到底是个什么

1.1 微信小程序的运行环境决定了它的样式表必须“压缩包化”

很多人以为 WXSS 是微信故意搞出来折磨开发者的，其实不是。想要理解 WXSS 的设计动机，得先搞清楚小程序在手机上是怎么跑的。

小程序的渲染层不是普通浏览器页面，而是一个多端不一致的 WebView 集合。iOS 用的是 WKWebView，Android 阵营更复杂，有 XWeb、Chromium 内核，还有各种厂商深度定制过的浏览器内核，开发者工具里又是一个 Chromium 环境。你写的同一段 CSS，在开发者工具里渲染没问题，到了某些 Android 真机上可能就完全不是那么回事。

CSS 本身发展太快，属性太多，不同内核每年的支持度都有差异。如果小程序直接把 CSS 全量开放给开发者，那么同样的代码在不同机型上就会出现“薛定谔的样式”——有的端圆角生效，有的端渐变失效，有的端动画卡成 PPT。为了保证“一套代码，多端表现基本一致”，微信必须做一件事：把样式能力收敛到一个经过验证的共同子集里。

这就是 WXSS 存在的最根本原因。它不是要取代 CSS，而是从 CSS 里挑出适合小程序场景、在各端 WebView 里都能稳定运行的特性，再补上几个小程序特有的能力，整合成一套定制样式语言。所以你会发现，WXSS 官方文档开篇就写着“WXSS 具有 CSS 大部分特性”，这句话的潜台词是：剩下的那些“少部分特性”，要么不稳定，要么在小程序环境里没有意义。

1.2 WXSS 不是新语言，而是“CSS 的超集兼子集”

我习惯用“装修套餐”来类比这个关系。CSS 像是毛坯房，你有无限自由，想砌墙就砌墙，想砸墙就砸墙；WXSS 则是开发商提供的统一精装标准，套餐里包含的东西你随便用，套餐外的高级操作可能不允许，但套餐本身也送了几样外面买不到的定制家具——比如专为屏幕适配设计的 rpx 单位，比如全局样式和页面样式的层级体系。

从能力上看，WXSS 是 CSS 的“子集”：不支持通配符选择器、大量伪类选择器、一些复杂属性；同时又是 CSS 的“超集”：新增了 rpx 响应式像素单位、app.wxss 全局样式、页面级作用域隔离等原生 CSS 没有的概念。

这种“既是子集又是超集”的特性，导致从 Web 转过来的开发者特别容易踩坑。因为大多数人不会先去读一遍 WXSS 官方文档，而是默认“WXSS 就是 CSS”，然后直接把老代码搬过来。等到样式乱了，才回头研究差异。我见过不少项目，页面里躺着一堆从不生效的 :hover 和 * 选择器，看着挺吓人，实际上代码根本没跑起来。

1.3 官方设计目标是“写起来像 CSS，跑起来不像”

需要明确一个认知：WXSS 文件本身不会直接在浏览器里运行，它会经过小程序框架的编译和转译，变成各端 WebView 能识别的内容，同时配合运行时把 rpx 这类自定义单位换算成真实像素。这个“编译 + 运行时”的架构，决定了 WXSS 不可能做到和 CSS 实时同步。CSS 新增了一个属性，浏览器支持了就能用；但 WXSS 要先用，得等框架升级、开发者工具更新、基础库覆盖，链路长得多。

所以，看 WXSS 文档时，别拿 CSS 的标准去要求它“跟上时代”。它的目标从来不是“实现全部 CSS 特性”，而是“用最稳妥的方式解决小程序里的样式问题”。

2. WXSS 和 CSS 的语法能力差异：一张表看清楚

2.1 最大的差异是单位：rpx 到底怎么换算

WXSS 和 CSS 最直观的差异，就是多了一个尺寸单位 rpx（responsive pixel，响应式像素）。这个单位是 WXSS 的基石，也是新手最容易理解错的东西。

rpx 的换算规则：不管什么屏幕，一律按 750rpx 等于屏幕宽度来算。也就是说，设计稿宽度如果是 750px，那么设计稿上的 20px 间距，在 WXSS 里直接写 20rpx，不需要任何换算。

为什么是 750？这个数字背后有一段历史逻辑。早期的主流设计稿宽度是 750px，对应 iPhone 6 的逻辑分辨率 375px 和物理分辨率 750px（2 倍屏）。也就是说，iPhone 6 上 1rpx 正好等于 1 物理像素，等于 0.5 逻辑像素。而 750 这个数字足够大，设计稿给到 1px 的细节，在 WXSS 里至少能对应 1rpx，不会出现精度丢失。

实际的换算公式是：

• 屏幕逻辑宽度（px）× rpx数值 ÷ 750 = 实际像素值

举例来说，在 iPhone 6（逻辑宽度 375px）上，750rpx = 375px，1rpx = 0.5px；在 iPhone 14 Pro Max（逻辑宽度约 430px）上，750rpx = 430px，1rpx ≈ 0.573px。同样一个 width: 750rpx 的元素，在小屏手机上占满全屏，在大屏手机上也占满全屏，比例永远是对的。

这个机制省掉了响应式布局里最麻烦的媒体查询，但也带来一个陷阱：rpx 是等比缩放，不是恒定像素。比如你给一个输入框的 font-size 设置成 28rpx，在 iPhone 6 上是 14px，在 iPhone 14 Pro Max 上大约是 16px。文字在小屏上显示没问题，但大屏上字号会跟着变大。字体大小适度缩放问题不大，可如果你想让字号在所有设备上保持物理一致，rpx 就不合适了，建议用 px。

我给自己定的单位规则比较朴素：

2.2 选择器：能用的就那几种

WXSS 官方文档里明确列出的支持选择器非常有限，我用 Markdown 表格整理出来：

这个表看着不起眼，实际影响非常大。比如你把一段使用 * 重置样式的 reset.css 直接搬进小程序，全部失效。你把 :nth-child 用在列表斑马纹上，也全无效果。这些在 CSS 里习以为常的东西，在 WXSS 里都得换思路实现。

2.3 伪元素、媒体查询和部分 CSS 函数的边界

WXSS 对于伪元素的支持比较特殊，只保留了 ::after 和 ::before，其他伪元素没有。这两个伪元素在小程序里非常常用，比如给卡片加个左侧装饰条、给按钮加个角标，都可以用 ::after 实现。需要注意 content 属性的用法。我在真机上测试过，content: "文字" 是没问题的，但 content: attr(data-text) 这类取值写法在部分机型上不可靠，建议老老实实在 WXML 里写真实文本节点，而不是依赖伪元素的 attr() 取值。

媒体查询 @media 在 WXSS 里是支持的，这个很多文章没提到。但它能用的维度有限，主要是屏幕宽度区间：

css复制@media screen and (min-width: 375px) {
  .container {
    padding: 20rpx;
  }
}

不过有了 rpx 之后，大部分适配场景已经不需要媒体查询了。我实际项目里，媒体查询主要用于大屏平板场景的特殊布局调整，普通手机场景基本不写。

CSS 函数方面，calc() 在 WXSS 里是支持的，这个很常用。我经常写类似 padding-bottom: calc(env(safe-area-inset-bottom) + 20rpx) 的样式，实测兼容性不错。CSS 变量（自定义属性 --primary 这种）在新版基础库上也能用，但要注意兼容边界，老版本基础库上可能无效，后面我会专门讲。

2.4 样式导入：@import 的路径踩坑

WXSS 支持 @import 导入外部样式文件，语法长这样：

css复制@import "common.wxss";
@import "../../styles/button.wxss";

看着和 CSS 差不多，但有几个差异需要注意。第一，路径必须写相对路径，不能写 node_modules 包路径，也不能写远程 URL。第二，文件后缀不能省略，CSS 里写 @import "common" 可能能找到文件，WXSS 里必须带 .wxss。第三，不支持嵌套的 import 循环检测，自己在导入公共文件时要注意别搞成 A 导 B、B 导 A 的闭环，编译会报错。

我习惯把公共样式抽成 common.wxss，然后在每个页面的 WXSS 第一行 @import 进来，而不是把公共样式全部堆在 app.wxss 里。原因是 app.wxss 一旦大了，所有页面都会加载，首屏时间受影响；按页导入可以按需加载。当然，像设计变量、重置样式这种全局必须的，还是放 app.wxss 更合适。

3. 从 CSS 迁到 WXSS 必踩的几个行为断裂点

3.1 通配符重置样式直接失效

Web 前端几乎都有一套 reset 或 normalize 样式，里面大概率有个 * { margin: 0; padding: 0; box-sizing: border-box; }。这段代码在 WXSS 里完全无效，因为通配符选择器不被支持。

第一次遇到这个问题时，我以为是选择器写错了，后来查文档才知道 WXSS 根本没有 * 选择器。不过说句公道话，小程序的环境没有浏览器那么多默认样式，view、text 这些组件本身没有默认的 margin 和 padding，所以重置的需求比 Web 小得多。你不需要担心 ul 的列表样式、h1 的加粗、a 的下划线，因为这些标签在小程序里根本不存在。

如果确实需要全局重置，可以用标签选择器逐个写：

css复制view, text, image, button, input, textarea {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

但这样写粒度太粗，容易影响第三方组件库的内部样式。我现在更推荐的做法是：不写全局重置，只在项目基础组件里对必要元素做重置。

3.2 伪类选择器全部失灵，按钮态要换个思路

CSS 里想让按钮按下时变色，写个 .btn:hover 就好了。但在小程序里，硬写 :hover 在开发者工具模拟器上可能有点效果，到真机上基本是废的。因为小程序组件没有浏览器的“悬浮”概念，手指触摸不是悬浮，是触摸。

小程序的正确方案是 hover-class 属性。给按钮组件加上 hover-class="btn-hover"，手指按下时自动切换类名，松开时移除：

html复制<button class="btn" hover-class="btn-hover">确认支付</button>

css复制.btn {
  background-color: #07c160;
  color: #fff;
}
.btn-hover {
  background-color: #06ad56;
  transform: scale(0.98);
}

同样的道理，任何类似 :active、:focus、:visited 的伪类在小程序里都不适用，需要靠状态类名或 WXML 的数据驱动来切换样式。

3.3 样式隔离带来的“覆盖”和“继承”乱象

小程序里存在三层样式：app.wxss 全局样式、页面 WXSS、组件 WXSS。它们的生效规则跟 CSS 的层叠不完全一样，因为它还叠加了一层“隔离”。

页面之间的样式天然隔离，页面里写的类名不会跑到另一个页面去。组件样式默认完全隔离，意味着你在组件 wxss 里定义的类名只对组件内部生效，外部页面无法通过类名覆盖组件内部样式。这个机制和 Vue 的 scoped 有点类似，但更严格。

实际开发中，这个特性经常让人头疼。你用了一个第三方组件库（比如 Vant Weapp），想在页面里改一下它内部按钮的颜色，直接在页面 wxss 里写 .van-button { background: red; } 是没用的。第三方组件的解决方案一般是通过外部样式类，比如 Vant 提供 custom-class 属性：

html复制<van-button custom-class="my-btn" type="primary">按钮</van-button>

css复制.my-btn {
  background-color: #ff6600;
  border-radius: 10rpx;
}

组件库会把 custom-class 挂到组件根节点上，并且允许外部类覆盖。如果是自己开发的组件，想要让外部能覆盖样式，可以在组件 options 里配置：

js复制Component({
  options: {
    styleIsolation: 'apply-shared' // 或 'shared'
  }
})

apply-shared 表示页面 wxss 样式可以影响组件，但组件 wxss 不影响页面；shared 则是双向影响。这里要谨慎，一旦开了共享，之前辛苦维护的样式隔离就破坏了，很容易出现“页面样式莫名污染组件”的情况。

3.4 动态值和动画：CSS 变量、calc 的兼容边界

小程序 CSS 变量（自定义属性）是能用的，官方在新版本基础库中支持。具体写法：

css复制page {
  --primary-color: #07c160;
  --spacing-md: 20rpx;
}
.btn {
  background-color: var(--primary-color);
  padding: var(--spacing-md);
}

CSS 变量在实现主题切换时非常有用。但要注意，CSS 变量的支持依赖基础库版本，如果项目最低基础库版本太低，老机型上变量会失效。我在实际项目中做得比较保守：基础变量放 page 上，关键 UI 组件里用变量兜底，并提供默认值：

css复制.button-primary {
  background-color: var(--primary-color, #07c160); /* 第二个参数是兜底值 */
}

这样即使变量失效，也有默认颜色顶着，不会出现整个页面“裸奔”的情况。

动画方面，@keyframes 在 WXSS 里是支持的，animation、transition 这些属性也都能用。做简单的位移动画、透明度动画、旋转动画完全没问题。但有几个注意点：尽量只做 transform 和 opacity 相关的动画，性能最好；不要依赖 position: absolute + top/left 做路径动画，掉帧严重；animation 的贝塞尔曲线参数跟 CSS 一致，可以直接套用。

3.5 兼容性差异：iOS 和 Android 的 WebView 不是同一个

这一点必须单独强调。CSS 里有几个属性在 iOS 和 Android 上的表现差异巨大，我在小程序开发中深有体会。

第一个是 safe-area-inset-bottom 安全区。iOS 的底部小黑条区域需要专门适配，正确姿势是：

css复制.page {
  padding-bottom: constant(safe-area-inset-bottom); /* iOS 11.0-11.2 */
  padding-bottom: env(safe-area-inset-bottom); /* iOS 11.2+ */
}

但前提是页面配置里要设置 "viewport-fit": "cover"，否则 env() 拿不到值。Android 上大部分机型没有安全区概念，env() 返回 0，影响不大。不过现在有些 Android 厂商也做了挖孔屏，底部手势条区域也需要适配，写法上要统一。

第二个是 position: fixed 和键盘弹起的配合。小程序里 fixed 定位元素在键盘弹起时经常出现位置错乱，iOS 和 Android 表现还不一样。经验是：涉及输入框的底部固定按钮，不建议纯 CSS fixed，最好用 adjust-position 或监听键盘高度动态设置位置。

第三个是渐变和阴影。linear-gradient、box-shadow 在 iOS 上表现细腻，在低端 Android 机型上可能出现锯齿或直接被忽略。做重要视觉时不要过度依赖阴影层次，宁可多加点边框对比。

4. WXSS 是怎么被编译和加载的：开发者工具里的“黑盒”没那么玄

4.1 WXSS 文件本身不会直接在 WebView 里跑

我刚开始写小程序时，特别好奇一件事：我写的 WXSS 代码到底去了哪里？真机上有没有一个文件保存着它？答案是：WXSS 会被小程序框架编译成各端 WebView 能识别的内容，运行时再注入到渲染层。

这个编译过程是自动的。开发者工具会把你写的 .wxss 文件、app.wxss 和 WXML 里的内联 style 一起打包成编译产物。到了真机上，渲染层拿到的是经过处理后的样式表。这也是为什么你在开发者工具的 WXML 面板里选中元素，看到的 Computed 样式值是 px 而不是 rpx——rpx 在运行时已经被换算成当前机型的具体像素了。

理解这一点的实际价值在于排错。比如你在开发者工具里看到一个元素宽度是 375px，不要惊讶，那就是 750rpx 在 375px 宽度屏幕上的换算结果。换一台 430px 宽度的真机，它就会变成 430px。所以你要验证的是“换算前”的 rpx 值是否正确，而不是纠结综合样式里的具体像素。

4.2 样式注入顺序：全局、页面、组件、内联 style 的优先级

WXSS 的样式优先级是有明确顺序的。在不涉及选择器具体度（specificity）的前提下，大致服从这个规则：

内联 style > 组件/页面 wxss > app.wxss > 框架默认样式

但这里面有个细节：页面 wxss 和组件 wxss 之间因为样式隔离，通常不存在直接竞争。真正的竞争经常发生在“页面 wxss 里写的样式”和“app.wxss 里写的同优先级样式”之间，这时页面 wxss 会覆盖 app.wxss。这也是为什么很多人把公共样式放 app.wxss，然后在页面里单独调整。

还有一个容易忽略的点：微信开发者工具对样式优先级的模拟有时过于宽松。模拟器里生效的覆盖，真机上可能不生效。比如组件库内部样式优先级是 !important，你在外部写普通样式根本压不住。遇到这种情况，不要盲目在页面样式里加 !important，应该先查组件库有没有提供外部样式类或者 CSS 变量覆盖入口。

4.3 开发者工具的“宽容”是真机的大坑

开发者工具基于 Chromium，Chromium 对 CSS 的兼容性比真机 WebView 高得多。一个典型场景：你在开发者工具里用了 gap 属性来实现 flex 子元素的间距，模拟器显示完美。一上真机，部分低版本 Android 机型的 WebView 不支持 gap，间距全部消失。

这种问题很难排查，因为开发者工具不会报错。我的经验是，凡是使用比较新的 CSS 特性，都先查一下基础库和 WebView 的兼容范围，然后用更保守的方案替代。比如 flex 子元素间距，我之前遇到过 gap 不兼容的情况，改用 margin 或者父容器负边距实现，彻底避开兼容问题。

再比如 aspect-ratio、backdrop-filter、position: sticky 这些新特性，在开发者工具里都能跑，真机上就要打问号。我在项目里的原则是：新特性只用于“视觉增强”而非“功能依赖”，即使失效也不影响核心体验。

5. 项目沉淀：WXSS 适配与样式架构规范

5.1 单位选择策略：宽度间距用 rpx，字号边框用 px

经过几个项目的打磨，我总结了一套自己的单位使用规范，分享出来供参考。

宽度、间距、高度、圆角，一律用 rpx。这些属性需要跟随屏幕宽度等比缩放，rpx 是最优解。

字号建议用 px。原因前面提过，用户阅读习惯是固定物理尺寸，字号跟着屏幕等比缩放会显得大屏上文字过大、小屏上文字过小。用 px 可以保证字号在所有机型上物理一致。但要注意，小程序的 px 是逻辑像素，不是物理像素，在不同 DPR 的设备上，最终渲染出的物理像素会不同，这点和 Web 一致。

1px 边框不要用 rpx。如果写成 1rpx，在 2 倍屏上是 0.5px，在 3 倍屏上是约 0.33px，细线本身没问题，但在部分机型上会渲染出半像素导致发虚。更稳妥的方案是用伪元素 + transform: scale(0.5) 来模拟 1px 物理像素边框：

css复制.divider {
  position: relative;
}
.divider::after {
  content: "";
  position: absolute;
  left: 0;
  right: 0;
  bottom: 0;
  height: 1px;
  background-color: #ebedf0;
  transform: scaleY(0.5);
  transform-origin: 0 0;
}

不过这个方案也不是绝对完美。在小程序里，我实测发现 ::after 不能定位到所有容器的边界，个别场景还是需要直接用 border-bottom: 1px solid #ebedf0，视觉上稍微粗一点但省事。到底用哪种，取决于你对像素级的追求。

5.2 布局：flex 是主力，grid 要谨慎

小程序里的布局，flex 绝对是主力，display: flex、flex-direction、justify-content、align-items、flex-wrap 这些基础属性兼容性都很稳定。做动态列表、流式布局、底部 Tab，flex 都能胜任。

flex 的一个常见需求是“子元素宽度自适应”，比如等分布局：

css复制.card-list {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-between;
}
.card {
  width: 48%;
}

这里比较稳的写法是给子元素设置百分比宽度，或者用 flex: 1 让子元素自动瓜分剩余空间。要注意 flex: 1 会让子元素宽度均等，但如果子元素里有文本内容过长，可能需要配合 min-width: 0 或 overflow: hidden 防止撑破布局。

关于 gap 属性，在小程序 flex 布局里的兼容性存在风险，我之前在真机上踩过坑。不建议直接依赖 gap 控制间距，而是在子元素上用 margin 来实现。如果非要用，先确认你的基础库版本和主要用户机型的 WebView 支持情况。

grid 布局在小程序里的兼容性更差一些，尤其是一些老机型的 WebView 对 grid 的支持不完整。普通页面布局不建议用 grid，简单的两列、三列用 flex 百分比就够了。复杂的网格布局如果必须用，建议先做真机兼容性测试。

5.3 原子化 CSS 在小程序里的变通写法

现在 Web 端原子化 CSS 很火，Tailwind CSS、UnoCSS 这些方案在 React/Vue 项目里用得很爽。小程序里能不能用？能，但要打折扣。

主要问题是小程序不支持动态类名。Tailwind 这类工具生成的类名，如果是在构建时静态提取，是可以用的。比如你在 HTML 里写死 class="flex items-center"，这些类名会被扫描并生成到产物里。但如果你用模板字符串动态拼接类名，比如 class="item-${index}"，编译时扫描不到，类名就不会被生成，样式就丢了。

小程序 WXML 也支持动态类名，但受限于构建工具的静态扫描，很多高级用法无法实现。我给团队的建议是：如果要用原子化 CSS，不要让设计师或者后端接口控制类名，前端所有类名必须硬编码在 WXML 里，保证可被构建工具扫描到。

另外一个思路是使用小程序多端框架自带的样式方案。比如 Taro 支持在 React 语法里写 CSS Modules，UniApp 支持 scoped 样式，这些方案都经过框架层处理，比直接在原生小程序里折腾原子化 CSS 要省心。但不管用什么方案，核心都是：类名要静态、可预测、可扫描。

5.4 安全区、顶部导航栏和 iPhone 底部兼容

小程序的顶部导航栏适配，是很多从业者都会遇到的问题。胶囊按钮（右上角那三个点）的位置不是固定的，不同机型上它的高度、距顶距离、距右距离都不同。CSS 做不到精确获取胶囊位置，需要配合 JavaScript：

js复制const menuButton = wx.getMenuButtonBoundingClientRect()
const systemInfo = wx.getWindowInfo()
// 导航栏高度 = 胶囊按钮顶部位置 - 状态栏高度
const navBarHeight = (menuButton.top - systemInfo.statusBarHeight) * 2 + menuButton.height

拿到这些数据后，通常的做法是通过行内 style 或者 CSS 变量注入到页面：

js复制this.setData({
  navBarHeight: navBarHeight,
  statusBarHeight: systemInfo.statusBarHeight
})

html复制<view class="nav-bar" style="padding-top: {{statusBarHeight}}px; height: {{navBarHeight}}px;"></view>

这里有个细节：导航栏高度不建议千篇一律写死成 44px。不同机型的胶囊位置有差异，动态计算才是保险的做法。

底部安全区适配，常见写法：

css复制.safe-bottom {
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
  padding-bottom: calc(env(safe-area-inset-bottom) + 20rpx); /* 额外增加留白 */
}

如果页面里的固定底部按钮，还要考虑键盘弹起的问题，这个前面已经提过，建议不要纯 CSS 处理。

5.5 公共样式文件和设计变量的管理技巧

小程序项目的公共样式管理，我推荐按模块拆分，而不是一个大文件。目录结构长这样：

code复制styles/
  ├── variables.wxss      // 设计变量：颜色、间距、字体大小
  ├── reset.wxss          // 基础重置
  ├── mixins.wxss         // 常用混合样式：文本溢出、清除浮动
  ├── button.wxss         // 按钮样式
  └── card.wxss           // 卡片样式

variables.wxss 里的设计变量，我强烈建议用 CSS 变量来承载，同时配合注释说明：

css复制page {
  /* 品牌色 */
  --color-primary: #07c160;
  --color-primary-light: #06ad56;
  --color-danger: #fa5151;
  --color-warning: #ff976a;

  /* 文本色 */
  --color-text-main: #333333;
  --color-text-secondary: #666666;
  --color-text-placeholder: #999999;

  /* 间距 */
  --spacing-xs: 8rpx;
  --spacing-sm: 16rpx;
  --spacing-md: 24rpx;
  --spacing-lg: 32rpx;
  --spacing-xl: 48rpx;
}

页面里使用变量时，一定要带默认值兜底：

css复制.foo {
  color: var(--color-primary, #07c160);
  margin-top: var(--spacing-md, 24rpx);
}

这样即使某个基础库版本不支持 CSS 变量，视觉上也不至于崩得太厉害。如果项目整体基础库版本较高，并且你愿意承担一点点兼容风险，变量方案可以大幅提高样式维护效率。

5.6 动效样式库的取舍：小型库可以，大型库要裁剪

网上有很多现成的 CSS 动效样式库，比如 Animate.css、Hover.css 这类。直接在小程序里用，效果可能不理想。原因很简单：这些库动辄几百个类，大量用到了 * 通配符、:nth-child、:hover 等小程序不支持的选择器。

我的做法是：从这些动画库里挑出自己需要的几个关键帧动画，复制到项目里，只保留用到的部分。常见的淡入淡出、滑入滑出、缩放、旋转，其实手写几分钟就能搞定，不需要为了一个动画引入整个库增加包体积。

如果团队对动效要求高，可以考虑用小程序官方提供的动画 API（wx.createAnimation）或者 CSS 动画结合方式。大量连续的位移动画用 CSS 动画性能更好，复杂交互动画用 JavaScript 驱动更灵活。

5.7 一些 CSS 特殊效果在小程序里的实现

搜索热词里有几个高频问题，比如“CSS 文字竖着排列”“CSS 波浪效果”“CSS 倒影”“CSS 字体渐变”，这些效果在小程序里能不能做？

文字竖着排列：CSS 里有 writing-mode: vertical-rl，但小程序部分 WebView 不支持，体验不稳定。更稳妥的方案是每个字单独一个 text 组件，通过 flex-direction: column 排列。

字体渐变：background-clip: text + -webkit-text-fill-color: transparent 在小程序里支持度还可以，但要看基础库版本。实现毛玻璃、金属字这类特殊效果时，建议加一层降级方案，比如纯色文字。

波浪效果：可以用 SVG 背景图 + CSS 动画，也可以直接用 Canvas。如果是页面里的动态波浪，Canvas 可能是更好的选择。CSS 手绘波浪在小程序里的兼容性一般，而且性能不稳定。

文字呼吸/涟漪光圈扩散：这类动画用 @keyframes 实现完全没问题，注意避开了兼容雷区即可。

6. 实战改造：把一段普通 CSS 代码迁移成 WXSS

6.1 原始场景：一个卡片列表的 CSS 写法

假设我从 Web 项目里拿了这么一段样式代码，想塞进小程序。先看看原始 CSS 长什么样：

css复制/* 原始 CSS */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

.card-list {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-between;
  padding: 20px;
}

.card-item {
  width: 48%;
  margin-bottom: 15px;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
  background: #fff;
  overflow: hidden;
}

.card-item:hover {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

.card-item:nth-child(2n) {
  margin-left: 4%;
}

.card-item .card-title {
  font-size: 16px;
  color: #333;
  padding: 12px 15px;
}

.card-item .card-tag {
  display: inline-block;
  padding: 4px 8px;
  border-radius: 4px;
  background: #f0f9eb;
  color: #67c23a;
  font-size: 12px;
}

这段 CSS 用了通配符、:hover、:nth-child、后代选择器，直接扔进 WXSS 里，通配符和伪类全部失效，间距和圆角还是固定 px，到了不同屏幕尺寸上适配全靠浏览器默认行为，乱套是必然的。

6.2 改造过程：一步步换成 WXSS

第一步，删掉通配符重置。小程序标签没有默认 margin/padding，不需要。

第二步，把 :hover 换成 hover-class。给卡片加 hover-class="card-item-hover"，再补一个类名样式：

css复制.card-item-hover {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  transform: scale(0.98);
}

第三步，解决 :nth-child(2n)。WXML 的循环里，可以用 index 计算类名，或者在 wx:for 中直接用 data-index 绑定，用 flex 布局替代 nth-child 的 margin hack。这里最省事的是用 flex 的 justify-content: space-between + 子元素百分比宽度，根本不需要 margin-left：

css复制.card-item {
  width: 48.5%;
  margin-bottom: 20rpx;
}

由于父容器已经 space-between，两个卡片自然分列两端，不需要额外处理第二列间距。

第四步，把 px 换成 rpx。设计稿如果是基于 750px 宽度，那么 20px 对应 20rpx，16px 字号要单独考虑，我用 px 保持物理一致。

第五步，阴影、圆角这些属性保留，但阴影尽量控制在一个适度范围，避免低端机渲染出问题。

6.3 改造后的 WXSS 完整代码

css复制/* 改造后的 WXSS */
.card-list {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-between;
  padding: 20rpx;
}

.card-item {
  width: 48.5%;
  margin-bottom: 20rpx;
  border-radius: 16rpx;
  box-shadow: 0 2rpx 8rpx rgba(0, 0, 0, 0.08);
  background: #ffffff;
  overflow: hidden;
  transition: transform 0.2s ease;
}

.card-item-hover {
  transform: scale(0.98);
  box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.15);
}

.card-title {
  padding: 20rpx 24rpx;
  font-size: 16px; /* 字号用 px 保持物理一致 */
  color: #333333;
}

.card-tag {
  display: inline-block;
  padding: 8rpx 12rpx;
  margin-left: 24rpx;
  border-radius: 8rpx;
  background: #f0f9eb;
  color: #67c23a;
  font-size: 12px;
}

改造后有几个直观变化：代码行数少了，因为去掉了 reset 和 nth-child 写法；适配能力提升了，间距和圆角用 rpx 后可随屏幕宽度自动缩放；交互反馈用 hover-class 实现，真机表现稳定。

6.4 改造过程中的真实测试记录

我在开发者工具和两台真机（iPhone 13、Android 小米 11）上分别跑了一遍。开发者工具模拟器上，阴影细腻、动效流畅；iPhone 13 上基本一致；小米 11 上阴影稍显生硬，但总体可接受。gap 属性我没有用，用的 flex space-between，所以三端间距表现完全一致。

如果当初直接把原始 CSS 扔进去，模拟器上大概率也能看，因为开发者工具支持 :hover 和 :nth-child。但一上真机，:hover 无响应，:nth-child 样式丢失，卡片间距错乱，这才是最坑的地方。所以，迁移样式的第一原则是：不要看模拟器“能不能显示”，要看真机“稳不稳定”。

写在最后的个人经验

做了几年小程序开发，我对 WXSS 的态度经历了一个转变：刚开始觉得它功能受限、各种不顺手，后来渐渐理解了这些限制背后的逻辑。WXSS 的问题不在于“比 CSS 少”，而在于“跟 CSS 不一样”。如果从一开始就把 WXSS 当成一门独立的样式语言来学，而不是带着“CSS 的简化版”的预设去看它，很多坑是可以提前避免的。

我现在写小程序样式，会先想清楚三件事：这个间距用 rpx 还是 px；这段交互要加 hover-class 还是纯 CSS 动画；这个选择器在小程序里是不是合法写法。想清楚再动手，比写完再调试效率高得多。

最后再分享一个小技巧：小程序开发者工具的“真机调试”功能一定要用起来，尤其是样式相关改动。模拟器再方便，也不能替代真机上的真实渲染。每次发版前，至少挑一台 iOS 和一台 Android 真机过一遍关键页面，比在模拟器里调整一百遍都有用。