使用::-webkit-scrollbar时CSS变量显示未定义且构建后失效问题

问题原因 #

• CRA生产构建的CSS压缩优化会误判:root中的变量未被使用，进而将其移除（滚动条伪元素属于浏览器私有伪元素，构建工具无法识别它对变量的引用）。
• 浏览器DevTools显示变量“未定义”，是因为滚动条伪元素不在常规DOM流中，工具无法正确关联:root变量与伪元素的引用关系。

解决方案 #

1. 强制保留CSS变量（避免构建时被移除） #

在CSS代码末尾添加一个无实际视觉效果的引用，让构建工具识别到变量已被使用：

/* 用于告知构建工具变量已被引用，防止被tree-shaking移除 */
body::after {
  content: var(--scrollBarWidth) var(--scrollBarHeight) var(--scrollBarWidthWide) var(--scrollBarHeightWide) var(--scrollBarThumbColor) var(--scrollBarTrackColor) var(--scrollBarBorderRadius) var(--scrollBarThumbColorHover) var(--scrollBarWidthFirefox);
  display: none;
}

2. 直接使用静态值（应急方案） #

如果不想调整构建配置，可以把CSS变量直接替换为对应静态值，彻底规避变量被移除的问题：

body::-webkit-scrollbar {
  height: 5px;
  width: 5px;
}
/* 其他滚动条样式规则同理替换变量 */

3. 调整CRA的CSS优化配置（需eject或使用craco） #

如果已经eject项目，或者使用craco等工具扩展CRA配置，可以修改CSS loader规则，禁用对CSS变量的tree-shaking：

• 使用craco时，在craco.config.js中添加如下配置：

module.exports = {
  style: {
    css: {
      loaderOptions: {
        css: {
          discardUnused: false, // 禁用未使用CSS的移除逻辑
        },
      },
    },
  },
};

4. 验证变量是否生效 #

部署后可以通过控制台命令验证变量是否存在：

getComputedStyle(document.documentElement).getPropertyValue('--scrollBarWidth')

执行后如果返回预期的5px，说明变量已正常加载。

内容的提问来源于stack exchange，提问作者Hemanth Vijaywargi