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

前言

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

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

实践指南

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

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

<template><viewclass="content"><comp></comp></view></template><scriptsetup>import comp from"./comp.vue";</script><stylescoped>.content {display: flex;flex-direction: column;align-items: center;justify-content: center;  }.content.comp-text {color: green;  }</style>

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

.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 选择器允许我们在父组件中定义样式，并让这些样式作用于子组件中的元素。例如我们有这样的组件代码

<template><view><textclass="comp-text">comp 组件</text></view></template><style>.comp-text {color: red;  }</style>

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

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

编译产物如下：

- .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，也不是浏览器原生隔离能力。它本质上是编译器做了两件事：

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

例如源码中写：

<template>  <div class="content">    <span class="title">hello</span>  </div></template><style scoped>.content .title {  color: red;}</style>

Web 端大致会变成：

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

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

scoped 的源码入口

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

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

其中：

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

compileStyle 的流程可以简化成：

functioncompileStyle(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 注入到合适的位置。

简化后的处理过程：

functionprocessRule(rule, scopeId) {const selectorAst = parseSelector(rule.selector);  selectorAst.each((selector) => {    rewriteSelector(selector, scopeId);  });  rule.selector = selectorAst.toString();}

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

functionrewriteSelector(selector, scopeId) {const target = findLastNormalSelectorNode(selector);if (target) {    injectScopeIdAfter(target, scopeId);  }}

例如：

.title {color: red;}

会变成：

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

再比如：

.content.title {color: red;}

会变成：

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

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

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

button:hover {color: red;}

会变成类似：

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

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

模板节点如何带上 scopeId

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

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

const __sfc__ = {  setup() {}};__sfc__.__scopeId = "data-v-1cf27b2a";exportdefault __sfc__;

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

functionsetScopeId(el, id) {  el.setAttribute(id, "");}

所以浏览器里能看到：

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

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

父组件 scoped 样式：

.comp-text {color: green;}

会被编译成：

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

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

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

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

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

deep 的核心思路

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

例如：

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

会被编译成：

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

可以看到：

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

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

deep 的源码处理思路

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

简化源码逻辑：

functionrewriteSelector(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 内部选择器不注入当前组件 scopeIdbreak;    }if (isNormalSelectorNode(node)) {      injectTarget = node;    }  }if (injectTarget) {    injectScopeIdAfter(injectTarget, scopeId);  } else {    prependScopeId(selector, scopeId);  }}

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

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

最终得到：

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

如果直接写：

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

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

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

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

uni-app scoped 处理思路

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

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

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

小程序模板节点追加 class

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

关键逻辑：

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

addScopeId() 实际调用：

addStaticClass(node, scopeId)

所以模板中会生成类似：

<viewclass="foo data-v-5584ec96" />

小程序 CSS 替换 selector

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

关键调用：

cssCode = transformScopedCss(cssCode)

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

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

即把：

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

改成：

.foo.data-v-5584ec96 {}

写在最后

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