uni-app小程序样式隔离：原理与实践指南

前言

在 Web 开发里，组件样式之间的互相影响，一直是个绕不开的话题。为了不让样式“打架”，Vue 搞出了 scoped 样式这个概念——让组件的样式只待在自己的地盘上，别去污染全局。同时，还弄了个 deep 选择器，专门用来让样式“穿透”到子组件内部。

不过在小程序的世界里，有一套自己的样式隔离机制，开发者可以通过不同的配置来控制隔离的程度。这篇文章就来聊聊小程序的样式隔离实践，顺便把 Vue scoped 的底裤也扒一扒，帮大家彻底搞懂这回事。

实践指南

先说说 scoped 怎么用。给 标签加上 scoped 属性，编译器就会自动给每个组件生成一个独特的属性选择器，比如 data-v-xxxxx，然后把这个 ID 加到组件的根元素上。这样一来，只有带着这个属性选择器的元素，才会应用这个组件的样式——隔离的效果就这么实现了。

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

<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>

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

.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 的 class（在小程序里，它变了个形式，但本质一样）。

但有时候，我们需要让父组件的样式“穿透”到子组件内部，这时候就得用 deep 选择器。来看个例子：子组件 comp.vue 里有个文本：

<template>
  <view>
    <text class="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;
}

注意看，scopeId 从子组件节点上移到了父组件的 .content 上，而 .comp-text 不再带 scopeId。这样一来，样式就能穿透到子组件内部了。

上面这些能生效，其实都依赖于小程序的 styleIsolation 默认值是 apply-shared。如果把它改成 isolated，那就算用了 deep 选择器，父组件的样式也摸不到子组件。

vue scoped 原理

scoped 的核心思路

Vue 的 scoped 既不是 Shadow DOM，也不是浏览器原生隔离——它全靠编译器干活。简单说就是两件事：

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

举个例子，源码里这么写：

Web 端编译后大致变成：

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

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

scoped 的源码入口

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

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

其中：

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

compileStyle 的流程可以简化成：

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

简化后的处理过程：

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

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

function rewriteSelector(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";export default __sfc__;

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

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

所以在浏览器里能看到：

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

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

父组件 scoped 样式：

.comp-text {
  color: green;
}

会被编译成：

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

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

<span class="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 不是运行时穿透，而是编译阶段改变了选择器改写方式。

deep 的源码处理思路

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

简化后的源码逻辑：

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) 来说：

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)

所以模板中会生成类似：

<view class="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 {}