Svelte 作用域样式深度解析：哈希类如何封装 CSS、控制特异性与作用域 Keyframes

本文围绕 Svelte 官方文档《Scoped styles》展开，讲清楚组件内 <style> 块的作用域隔离机制：作用域类（如 svelte-123xyz）是如何由组件样式哈希生成的、每个选择器为何会获得 0-1-0 的特异性提升、重复出现的作用域类为何要包进 :where()，以及 @keyframes 的组件级隔离。读完之后，你不仅能直接使用 Svelte 的 scoped CSS，还能定位到编译器源码中生成这一切的具体位置，并会用 cssHash 选项自定义作用域类的生成策略。

一、作用域样式的基本机制

Svelte 组件可以包含一个 <style> 元素，其中的 CSS 属于该组件所有。这份 CSS 默认是**作用域化（scoped）**的：它只作用于该组件内的元素，不会污染页面上组件之外的任何元素。

<style>
	p {
		/* this will only affect <p> elements in this component */
		color: burlywood;
	}
</style>

官方文档给出的实现原理是：编译器会向受影响的元素添加一个类，这个类名基于组件样式的哈希值生成，例如 svelte-123xyz。编译后的 CSS 选择器会带上这个类，而模板中被命中的元素也会带上同样的类，两者配合完成隔离。

二、作用域哈希的生成：从 hash() 到 svelte-<hash>

要理解"基于组件样式的哈希"到底哈希了什么，可以看编译器源码：

• 哈希算法在 hash 函数：对输入字符串执行 djb2 变体（hash = (hash << 5) - hash 再异或字符编码），最后以 36 进制输出短字符串。输入中会先剔除 \r。
• 哈希的调用时机在分析阶段：2-analyze/index.js 中，只有当组件存在 root.css 时才会计算哈希，并调用 options.cssHash({ css, filename, name, hash })，将结果存入 analysis.css.hash。
• 默认实现在 validate-options.js：

cssHash: fun(({ css, filename, hash }) => {
	return `svelte-${hash(filename === '(unknown)' ? css : filename ?? css)}`;
})

可以看到：默认策略下，有文件名时哈希的是文件名，而不是 CSS 内容——所以文档中"based on a hash of the component styles"的表述，在默认 cssHash 下实际是"基于文件名的哈希"，前缀固定为 svelte-。

• 自定义哈希：cssHash 是合法的编译选项（类型定义见 types/index.d.ts），可以接收 { css, filename, name, hash } 四个参数并返回任意类名。仓库中的 custom-css-hash 测试样例 展示了一种典型用法——把组件名和文件名前缀拼进类名，便于在 DevTools 中肉眼识别来源：

export default test({
	compileOptions: {
		filename: 'src/components/FooSwitcher.svelte',
		cssHash({ hash, css, name, filename }) {
			const minFilename = (filename ?? '')
				.split('/')
				.map((i) => i.charAt(0).toLowerCase())
				.join('');
			return `sv-${name}-${minFilename}-${hash(css)}`;
		}
	}
});

三、特异性：0-1-0 提升与 :where() 的克制

每个作用域选择器都会因为追加的作用域类（如 .svelte-123xyz）而获得 0-1-0 的特异性提升。这意味着：组件内的 p 选择器会优先于全局样式表中的 p 选择器——即使全局样式表更晚加载（类选择器的特异性天然高于元素选择器，与加载顺序无关）。

值得注意的是，某些情况下作用域类必须被加到选择器上多次（例如一个选择器中出现多个独立的部分），但从第二次起会被包进 :where(.svelte-xyz123)，以避免特异性被进一步抬高。

这一点在转换阶段源码中有直接对应。render_stylesheet 中为每个 ComplexSelector 维护了 specificity.bumped 状态：

// for the first occurrence, we use a classname selector, so that every
// encapsulated selector gets a +0-1-0 specificity bump. thereafter,
// we use a `:where()` selector, which does not affect specificity
let modifier = context.state.selector;
if (context.state.specificity.bumped) modifier = `:where(${modifier})`;
context.state.specificity.bumped = true;

• 首次出现：modifier 就是 .svelte-xxx 类选择器，贡献 0-1-0；
• 后续出现：包一层 :where()，:where() 本身特异性为零，因此不再叠加；
• 另外，bumped 状态在嵌套规则中还会向上查找父级规则（见 SelectorList 处理器）：只要祖先规则中已有局部选择器做过提升，当前选择器首次出现时也会直接用 :where() 形式，保证整条嵌套链只获得一次 0-1-0 提升。

四、作用域 Keyframes

如果组件定义了 @keyframes，其名称会用同样的哈希方式作用域化（加 svelte-xxx- 前缀）；组件内的 animation 规则也会被同步改写，保证引用到改名后的 keyframes：

<style>
	.bouncy {
		animation: bounce 10s;
	}

	/* these keyframes are only accessible inside this component */
	@keyframes bounce {
		/* ... */
	}
</style>

源码中这两步分别由两个 visitor 完成（均在 3-transform/css/index.js）：

1. Atrule visitor 处理 @keyframes：对 keyframes 节点名在 @keyframes 与名字之间插入 ${state.hash}- 前缀；若名字以 -global- 开头（如 @keyframes -global-bounce），则直接移除该前缀，声明为全局 keyframes，不做作用域化。
2. Declaration visitor 处理 animation / animation-name：逐字符扫描声明值，遇到组件内定义过的 keyframes 名（记录在 state.keyframes 中）就同样插入哈希前缀，使 animation: bounce 10s 变成 animation: svelte-xxx-bounce 10s。

测试样例 packages/svelte/tests/css/samples/keyframes-autoprefixed/ 与 keyframes-from-to/ 分别验证了 keyframes 前缀补全和 from/to 简写场景下的处理。

五、其他与 scope 相关的编译行为

阅读同一份转换代码，还有几个对实际开发有影响的细节：

• :global 的处理：remove_global_pseudo_class 会把 :global(x) 还原为普通选择器 x，把嵌套规则中的 :global.x 还原为 .x（必要时补 &，如 div { :global.x { … } } 变为 div { &.x { … } }），即 :global 只是编译期语法，不会进入产物。
• 未使用选择器的清理：作用域分析阶段会标记每个选择器是否被模板用到（selector.metadata.used）。未被任何元素命中的选择器在 minify 模式下会被直接删除；在保留空白的模式下会被包成 /* (unused) … */ 注释保留，方便开发时排查（见 Rule/SelectorList visitor）。
• css 选项控制输出形态：validate-options.js 中，css 只接受 'external'（默认，推荐）或 'injected'。分析阶段的 inject_styles 标志（2-analyze/index.js）决定了样式是作为外链文件输出，还是以内联 <style> 注入页面；作用域类与哈希机制在两种形态下都一致生效。

六、小结与验证入口

• 作用域隔离 = 元素上追加 svelte-<hash> 类 + 选择器追加同类修饰；默认哈希基于文件名（djb2 算法，36 进制），可通过 cssHash 编译选项完全自定义；
• 每条作用域规则只获得一次 0-1-0 特异性提升，重复位置用零特异性的 :where() 修饰，避免意外盖过全局样式；
• @keyframes 名称与 animation 声明被同步改名实现组件级隔离，-global- 前缀可显式声明全局。

若希望对照编译产物逐一验证以上行为，仓库的 CSS 测试套件是很好的入口：packages/svelte/tests/css/test.ts 配合 packages/svelte/tests/css/samples/ 下的样例（如 specificity-*、keyframes*、global-*、omit-scoping-attribute* 系列），每个目录内的 _config.js 与期望产物文件都标明了该场景下编译器的确切输出。