:global是CSS Modules中唯一可靠的“跳出”方式，用于声明全局类名以避免哈希化，确保伪类、第三方样式等正确匹配；必须包裹完整选择器片段，不可拆分或嵌套在@keyframes中。
为什么 :global 是唯一可靠的“跳出”方式
CSS Modules 默认把所有类名局部化，想用 :hover、::before 这类伪类影响外部元素，或让某个类名不被哈希化——必须显式声明“这是全局的”。没有 :global，其他写法（比如直接写 .btn:hover）会被当成局部类处理，编译后变成类似 .Button_button__abc123:hover，根本匹配不到 DOM 中原始的 .btn。
常见错误现象：.wrapper :global(.btn):hover { color: red; } 写成 .wrapper .btn:hover，结果 hover 不生效；或者误以为加个 !important 就能绕过模块化，其实只是覆盖了样式优先级，类名依然被重命名了，选择器压根没命中。
-
:global()必须包裹完整的选择器片段，不能只包类名的一部分（如:global(.btn):hover✅，.btn:global(:hover)❌） - 支持嵌套：例如
:global(.modal) :global(.close-button)表示两个都是全局类 - 不能在
@keyframes或@font-face里用:global，它们本身就不受模块作用域限制
如何安全地混合局部与全局样式
实际项目中常需要“主体用模块化，按钮/图标/重置样式复用全局类”。这时候不能全写 :global，否则失去 CSS Modules 的隔离价值。关键是分清边界：哪些是组件内私有样式，哪些是跨组件通用语义类（如 text-center、sr-only）。
使用场景举例：一个弹窗组件要复用项目统一的 btn-primary 样式，同时自己定义 modal-header 的内边距和阴影。
立即学习“前端免费学习笔记（深入）”；
- 推荐写法：
:global(.btn-primary) { /* 不写 */ }—— 空声明即可，让 class 名透出，样式仍由全局 CSS 文件提供 - 避免在同一个规则里混用局部和全局类选择器，比如
.my-modal :global(.btn-primary)是 OK 的，但.my-modal .btn-primary会试图匹配局部化的.btn-primary，大概率失败 - 如果全局类来自第三方库（如 Bootstrap），确保其 CSS 在 CSS Modules 编译前已注入，否则可能因加载顺序导致样式被覆盖
:local 和默认行为的区别在哪
CSS Modules 默认就是 :local 模式，所以 .button { color: blue; } 等价于 :local(.button) { color: blue; }。但显式写 :local 有意义的场景是：你想在同一个文件里局部化一部分，另一部分用 :global，又怕自己或别人误读默认行为。
参数差异很小，但容易踩坑的是嵌套写法：
-
:local(.a) .b→ 外层.a局部化，.b仍按默认规则（即也是局部化） -
:global(.a) .b→.a全局，.b局部，除非再写:global(.b) - 不存在
:local(.a .b)这种写法，括号内不能含空格；正确写法是:local(.a) :local(.b)或直接省略
构建工具里容易忽略的兼容性细节
不是所有 CSS Modules 实现都完全一致。Webpack 的 css-loader、Vite 的 @vitejs/plugin-react、Next.js 的内置支持，在 :global 解析上基本一致，但对嵌套语法或注释处理略有差异。
性能影响几乎为零——:global 只是编译时标记，不增加运行时开销；但兼容性问题可能让你本地正常、CI 构建失败。
- Webpack 5+ 要求
css-loader版本 ≥ 6，旧版本对:global(.a .b)类写法支持不完整 - Vite 用户注意：如果用了
postcss-nested，别把:global写在嵌套块里（如.parent { :global(.child) { } }），部分版本会解析错位 - 错误信息如
Invalid CSS after "...": expected "{", was ";"，往往是因为:global后多写了分号或换行位置不对
最复杂的点其实不在语法，而在于团队协作时没人意识到某个 :global 声明正在悄悄破坏样式隔离——它不像 JS 错误会报红，而是静默地让组件在不同页面表现不一致。
