微信小程序自定义组件样式穿透失效：写了等于没写的 CSS

在一个小程序项目里，首页轮播图的指示点位置和颜色需要按设计稿调整。我在页面的 WXSS 里写好覆盖规则，保存、编译、真机预览——完全没有任何变化。反复检查选择器，语法没问题，开发者工具里元素也找得到，但样式就是不生效。没有报错，没有警告，CSS 安静地消失了。

现象

在页面 WXSS（pages/home/index.wxss）中写如下规则：

/* 预期：把轮播指示点移到右下角，激活点变白色 */
.banner-wrap .dots {
  left: auto;
  right: 32rpx;
}
.banner-wrap .dot.on {
  background-color: #fff;
}

.banner-wrap 是页面内的容器，.dots 和 .dot 是 <x-banner> 自定义组件内部的元素。

结果：样式零效果。类似情况还出现在瀑布流卡片组件上——想从页面层加 border-radius 和 box-shadow，同样完全无效。

根因

微信小程序的自定义组件默认启用 styleIsolation: "isolated" 模式。这是框架级的样式沙盒机制：

• 页面 WXSS 的选择器只能作用于页面自身的 DOM 节点，无法穿透到自定义组件的内部 shadow tree
• 自定义组件的 .json 文件若未显式配置 styleIsolation，就自动采用 isolated（隔离）
• 框架在运行时静默拦截跨边界的样式规则，不产生任何报错或 console 提示

这意味着一旦目标元素属于某个自定义组件，无论选择器写得多精确，从页面层发出的 CSS 在组件边界处就被截停了。

正解

根据场景选三条路之一：

方案 A：直接修改组件 WXSS（推荐，改动全局生效）

若样式调整对所有使用该组件的页面都适用，最干净的做法就是直接编辑组件自己的 .wxss：

/* components/banner/banner.wxss */
.banner-box .dots {
  left: auto;
  right: 24rpx;
  bottom: 20rpx;
}
.banner-box .dot {
  background-color: rgba(255, 255, 255, 0.4);
}
.banner-box .dot.on {
  background-color: #fff;
}

不需要动任何隔离配置，改一处处处生效。

方案 B：组件 JSON 设置 apply-shared（页面样式单向穿入）

在组件的 .json 中添加：

{
  "component": true,
  "styleIsolation": "apply-shared"
}

此后页面 WXSS 的规则可以穿透进来。注意：这对所有引用该组件的页面都开放了穿透权，可能造成其他页面的意外污染，慎用于共享组件。

方案 C：externalClasses 外部类（精确外科手术式）

在组件 .js 声明外部类，在 .wxml 把它挂到目标元素，页面用属性传入类名再写样式：

// components/banner/banner.js
Component({
  externalClasses: ['custom-dot-class'],
})

<!-- components/banner/banner.wxml -->
<view class="dot custom-dot-class"></view>

<!-- pages/home/index.wxml -->
<x-banner custom-dot-class="my-dot" />

/* pages/home/index.wxss */
.my-dot { background-color: rgba(255, 255, 255, 0.4); }

只影响指定的外部类挂载点，不打开整个隔离边界。

排查速查

遇到样式写了不生效时，在 DevTools 里选中目标元素，查看「计算样式」面板：

• 若你的页面规则完全不出现在计算样式里（不是被覆盖，而是根本不存在）→ 99% 是样式隔离拦截
• 检查该元素所属组件的 .json，确认 styleIsolation 字段值
• 缺省 = isolated = 页面层无法触达

一句话外卖

微信小程序自定义组件的样式边界是真实存在的运行时沙盒，不是 CSS 优先级问题——写之前先问一句「这个元素在不在自定义组件里？」