uni-app 小程序样式隔离实践指南和原理分析

前言

在 web 开发中，组件样式的之间的影响一直是一个重要的话题。为了避免不同的样式冲突，vue 框架引入了 scoped 样式的概念。scoped 样式可以让组件的样式只作用于当前组件，避免了样式的全局污染。同时，也提供了 deep 选择器来允许样式穿透到子组件中。

然而在小程序开发中，有一套专门的样式隔离机制，开发者可以通过不同的配置来实现不同程度的样式隔离。本文将介绍小程序样式隔离实践指南和 vue scoped 的实现原理，帮助开发者更好地理解和使用小程序的样式隔离机制。

实践指南

借助 scoped 属性，可以让组件的样式只作用于当前组件，避免了样式的全局污染。使用 scoped 样式时，编译器会为每个组件生成一个独特的属性选择器，并将其添加到组件的根元素上。这样，只有带有该属性选择器的元素才能应用该组件的样式，从而实现了样式的隔离。

假如我们有这样一个页面：

html 复制代码

<template>
  <view class="content">
    <comp></comp>
  </view>
</template>

<script setup>
  import comp from "./comp.vue";
</script>

<style scoped>
  .content {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
  }

  .content .comp-text {
    color: green;
  }
</style>

编译到微信小程序后，生成的样式会类似于：

css 复制代码

.content.data-v-1cf27b2a {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}
.content .comp-text.data-v-1cf27b2a {
  color: green;
}

可以看到，编译器为每个样式规则添加了一个独特的属性选择器（如 data-v-1cf27b2a），并将其添加到组件的根元素上。这样，只有带有该属性选择器的元素才能应用该组件的样式，从而实现了样式的隔离。

有时候我们需要让样式穿透到子组件中，这时可以使用 deep 选择器。deep 选择器允许我们在父组件中定义样式，并让这些样式作用于子组件中的元素。例如我们有这样的组件代码

html 复制代码

<template>
  <view>
    <text class="comp-text">comp 组件</text>
  </view>
</template>

<style>
  .comp-text {
    color: red;
  }
</style>

此时页面面上的文本颜色将会是红色的。如果我们想在父组件中覆盖子组件的样式，可以使用 deep 选择器：

diff 复制代码

-  .content .comp-text {
+  .content :deep(.comp-text) {
    color: green;
  }

编译产物如下：

diff 复制代码

- .content .comp-text.data-v-1cf27b2a {
+ .content.data-v-1cf27b2a .comp-text {
        color: green;
}

可以看到，编译器将 deep 选择器转换成了一个普通的选择器，并将其放在了组件的根元素之前。这样，父组件中的样式就可以覆盖子组件中的样式了。

上面这些能生效其实都是 styleIsolation 的默认值为 apply-shared 的结果，如果我们将 styleIsolation 设置为 isolated，则父组件中的样式将无法穿透到子组件中，即使使用了 deep 选择器。

vue scoped 原理

scoped 的核心思路

Vue 的 scoped 不是 Shadow DOM，也不是浏览器原生隔离能力。它本质上是编译器做了两件事：

给当前组件生成一个唯一的 scopeId，例如 data-v-1cf27b2a。
模板节点带上这个 scopeId，CSS 选择器也追加这个 scopeId。

例如源码中写：

vue 复制代码

<template>
  <div class="content">
    <span class="title">hello</span>
  </div>
</template>

<style scoped>
.content .title {
  color: red;
}
</style>

Web 端大致会变成：

html 复制代码

<div class="content" data-v-1cf27b2a>
  <span class="title" data-v-1cf27b2a>hello</span>
</div>

css 复制代码

.content .title[data-v-1cf27b2a] {
  color: red;
}

scoped 的源码入口

Vue 3 中和 scoped 样式最相关的是 @vue/compiler-sfc：

txt 复制代码

packages/compiler-sfc/src/compileStyle.ts
packages/compiler-sfc/src/style/pluginScoped.ts

其中：

compileStyle.ts：处理 <style> 块，判断是否存在 scoped，如果有就启用 scoped 选择器改写插件。
pluginScoped.ts：真正改写 CSS 选择器，例如 .title -> .title[data-v-xxx]，以及处理 :deep()。

compileStyle 的流程可以简化成：

ts 复制代码

function compileStyle(options) {
  const {
    source,
    id,
    scoped
  } = options;

  const shortId = id.replace(/^data-v-/, "");
  const longId = `data-v-${shortId}`;
  const plugins = [];

  if (scoped) {
    plugins.push(scopedPlugin(longId));
  }

  return postcss(plugins).process(source);
}

也就是说，scoped 样式的 CSS 改写不是运行时做的，而是在 SFC 编译阶段通过 PostCSS 插件完成的。

scoped 普通选择器如何改写

pluginScoped 会遍历每条 CSS rule，然后用 selector parser 把选择器解析成 AST，再把 scopeId 注入到合适的位置。

简化后的处理过程：

ts 复制代码

function processRule(rule, scopeId) {
  const selectorAst = parseSelector(rule.selector);

  selectorAst.each((selector) => {
    rewriteSelector(selector, scopeId);
  });

  rule.selector = selectorAst.toString();
}

普通选择器的核心逻辑可以理解成：

ts 复制代码

function rewriteSelector(selector, scopeId) {
  const target = findLastNormalSelectorNode(selector);

  if (target) {
    injectScopeIdAfter(target, scopeId);
  }
}

例如：

css 复制代码

.title {
  color: red;
}

会变成：

css 复制代码

.title[data-v-1cf27b2a] {
  color: red;
}

再比如：

css 复制代码

.content .title {
  color: red;
}

会变成：

css 复制代码

.content .title[data-v-1cf27b2a] {
  color: red;
}

这里有个关键点：Vue 不会简单地给选择器每一段都追加 scopeId，而是通常注入到当前 selector 最后一个合适的节点上。这样可以保证样式只命中当前组件节点，同时避免选择器过度膨胀。

伪类场景也会调整插入位置，例如：

css 复制代码

button:hover {
  color: red;
}

会变成类似：

css 复制代码

button[data-v-1cf27b2a]:hover {
  color: red;
}

scopeId 插在 button 后面、:hover 前面，这样既保留伪类语义，又完成作用域限制。

模板节点如何带上 scopeId

只改 CSS 还不够，模板渲染出来的节点也必须带同一个 scopeId。

SFC 编译时，组件对象会记录自己的 __scopeId，简化后类似：

js 复制代码

const __sfc__ = {
  setup() {}
};

__sfc__.__scopeId = "data-v-1cf27b2a";

export default __sfc__;

运行时渲染组件时，renderer 会在创建真实 DOM 节点时写入这个 scopeId。Web 端最终类似：

ts 复制代码

function setScopeId(el, id) {
  el.setAttribute(id, "");
}

所以浏览器里能看到：

html 复制代码

<div class="content" data-v-1cf27b2a></div>

为什么 scoped 不能直接影响子组件内部

父组件 scoped 样式：

css 复制代码

.comp-text {
  color: green;
}

会被编译成：

css 复制代码

.comp-text[data-v-parent] {
  color: green;
}

但子组件内部节点通常只有子组件自己的 scopeId：

html 复制代码

<span class="comp-text" data-v-child>comp 组件</span>

它没有 data-v-parent，因此父组件的 .comp-text[data-v-parent] 匹配不上。

这就是普通 scoped 的隔离效果：父组件样式不会随意污染子组件内部结构。

deep 的核心思路

:deep() 是 scoped 里的一个特殊选择器，作用是告诉编译器：deep 内部的选择器不要追加当前组件的 scopeId。

例如：

css 复制代码

.content :deep(.comp-text) {
  color: green;
}

会被编译成：

css 复制代码

.content[data-v-1cf27b2a] .comp-text {
  color: green;
}

可以看到：

.content 仍然带 [data-v-1cf27b2a]，样式入口仍限制在当前组件内。
.comp-text 不再带 [data-v-1cf27b2a]，因此可以命中子组件内部的 .comp-text。

所以 deep 不是运行时穿透，也不是绕过 CSS 规则，而是编译阶段改变了选择器改写方式。

deep 的源码处理思路

pluginScoped 在遍历 selector AST 时，如果遇到 :deep()，会把 :deep() 里面的选择器取出来替换原节点，并且不再给 deep 内部选择器追加当前组件的 scopeId。

简化源码逻辑：

ts 复制代码

function rewriteSelector(selector, scopeId) {
  let injectTarget = null;

  for (const node of selector.nodes) {
    if (isDeep(node)) {
      const innerSelector = node.nodes;

      // :deep(.comp-text) -> .comp-text
      replaceDeepWithInnerSelector(node, innerSelector);

      // deep 内部选择器不注入当前组件 scopeId
      break;
    }

    if (isNormalSelectorNode(node)) {
      injectTarget = node;
    }
  }

  if (injectTarget) {
    injectScopeIdAfter(injectTarget, scopeId);
  } else {
    prependScopeId(selector, scopeId);
  }
}

以 .content :deep(.comp-text) 为例：

txt 复制代码

1. 遍历到 .content，记录它是 scopeId 注入目标。
2. 遇到 :deep(.comp-text)。
3. 把 :deep(.comp-text) 替换成 .comp-text。
4. 给 .content 注入 [data-v-1cf27b2a]。
5. .comp-text 不注入 [data-v-1cf27b2a]。

最终得到：

css 复制代码

.content[data-v-1cf27b2a] .comp-text {
  color: green;
}

如果直接写：

css 复制代码

:deep(.comp-text) {
  color: green;
}

因为 deep 前面没有可注入的普通选择器，编译器会在前面补一个当前组件作用域限制：

css 复制代码

[data-v-1cf27b2a] .comp-text {
  color: green;
}

所以 :deep(.comp-text) 也不是完全全局污染，它仍然要求 .comp-text 位于当前组件作用域节点的后代中。

uni-app scoped 处理思路

uni-app 编译到小程序时，因为小程序 WXSS/WXML 对属性选择器和自定义属性的支持、转换策略不同，产物可能会变成类似：

css 复制代码

.content .title.data-v-1cf27b2a {
  color: red;
}

也就是把 Web 里的 [data-v-xxx] 思路转换成小程序更容易处理的 .data-v-xxx class 思路。但原理不变：节点上有唯一标识，样式选择器也带同一个唯一标识。

小程序模板节点追加 class

文件：packages/uni-mp-compiler/src/transforms/transformElement.ts

关键逻辑：

ts 复制代码

if (context.scopeId) {
  addScopeId(node, context.scopeId)
}

addScopeId() 实际调用：

ts 复制代码

addStaticClass(node, scopeId)

所以模板中会生成类似：

html 复制代码

<view class="foo data-v-5584ec96" />

小程序 CSS 替换 selector

文件：packages/uni-mp-vite/src/plugin/configResolved.ts

关键调用：

ts 复制代码

cssCode = transformScopedCss(cssCode)

实现文件：packages/uni-cli-shared/src/mp/style.ts

ts 复制代码

return cssCode.replace(/\[(data-v-[a-f0-9]{8})\]/gi, (_, scopedId) => {
  return '.' + scopedId
})

即把：

css 复制代码

.foo[data-v-5584ec96] {}

改成：

css 复制代码

.foo.data-v-5584ec96 {}

写在最后

感觉您耐心看完这篇文章，希望您能喜欢。这里是《前端毕业班》，前端开发者的自救互助小组。在 AI 与不确定性并存的时代，我们一起看清焦虑，聊技术、聊趋势，也聊前端还能走多远，走去哪。