scss文件名大小写不匹配导致模块找不到，因macos/linux文件系统区分大小写，@use'colors'与'colors'被视为不同路径；需全小写、不带_和.scss后缀，且变量名也严格区分大小写。
SCSS 文件名大小写不匹配导致 @use/@import 找不到文件
构建失败不是 Sass 语法错误，而是文件系统找不到模块——尤其在 macOS 和 Linux 下，文件系统区分大小写，@use 'Colors' 和 @use 'colors' 是两个不同路径。Windows 默认不区分，所以本地能过、CI/CD 或部署时直接报 File not found。
常见错误现象：Error: Can't find stylesheet to import. 或 Cannot resolve module，但文件明明存在；VS Code 能跳转，构建却失败。
- 检查所有
@use和@import语句中的路径：必须全小写，且不含_和.scss - 确认磁盘上实际文件名：比如
_variables.scss→ 引入写成@use 'variables'，不能写@use 'Variables'或@use '_variables.scss' - Git 有时会忽略大小写变更：用
git status看不到重命名，但文件系统已变；执行git rm --cached variables.scss && git add variables.scss强制刷新索引 - Vite/Webpack 默认不校验大小写，但底层 Node.js
fs.stat会按真实文件系统行为返回，别依赖编辑器提示
变量/函数名大小写混用触发 Sass 编译报错
Sass 是大小写敏感的：$ColorPrimary 和 $colorPrimary 是两个变量；一旦拼错，Undefined variable 报错直接中断编译，CSS 文件不会生成。
容易被忽略的点：AI 生成代码或复制粘贴时，常把设计稿里的 BrandBlue 直接当变量名用，但 SCSS 中习惯用 kebab-case（$brand-blue）或 camelCase（$brandBlue），混用就崩。
- 统一命名规范：项目里只用一种风格，推荐
$brand-blue（kebab-case），因为 CSS 自定义属性也用它，方便复用 - 不要用 PascalCase：
$BrandBlue易和 JS 类名混淆，且 Sass 官方文档示例全为小写 - 检查
@mixin和@function名称：它们同样大小写敏感，@include ButtonStyle≠@include buttonStyle - VS Code 插件（如 Sass Indent）可能自动首字母大写，关掉「Auto Capitalize」类设置
HTML/CSS 中 PX 单位大小写被 Prettier 强制转小写引发兼容问题
这不是 Sass 编译错误，但常被误认为“Sass 构建失败”：Prettier 格式化后把 100PX 变成 100px，而某些旧版 WebView 或定制渲染引擎只认大写 PX，导致样式失效。
注意：Sass 编译器本身不处理单位大小写，这是 CSS 输出后被 Prettier 或 PostCSS 处理的结果。
- 禁用 Prettier 的单位转换：在
.prettierrc中加"css-unit-case": "lower"（默认值）改不了，得用插件prettier-plugin-css-order或直接关掉相关规则 - 更稳妥的做法：用
/* prettier-ignore */包裹特殊声明，例如：/* prettier-ignore */<br>.box { width: 100PX; } - 避免在 Sass 中硬编码单位：改用
#{100}PX字符串插值，绕过 Prettier 对纯 CSS 块的扫描 - 上线前用
grep -r "PX" dist/快速验证是否残留，比肉眼检查快得多
构建工具对大小写的隐式处理差异
Webpack 和 Vite 在解析 @use 路径时行为不同：Vite 会先尝试小写路径，再 fallback 到原写法；Webpack（尤其搭配 sass-loader@12）则严格按字面匹配。同一份代码，在 Vite 开发环境正常，Webpack 构建就挂。
根本原因不是 Sass，而是构建工具封装层对 Node.js fs 模块调用方式不同。
- Webpack 用户：确保
sass-loader≥ v13，并在sassOptions中显式设implementation: require('sass')，避免回退到旧版解析逻辑 - Vite 用户：检查
css.preprocessOptions.scss是否启用了additionalData，它可能提前注入了大小写不一致的变量 - 统一 CI 环境：在 GitHub Actions 或 GitLab CI 中用 Ubuntu 镜像（而非 Windows），提前暴露大小写问题
- 最保险的实践：所有文件名、变量名、mixin 名全部小写 + 连字符，彻底规避歧义
真正卡住构建的，往往不是语法本身，而是大小写这个“看不见的字符”。它不报红，不提示，只在跨平台或换构建工具时突然爆发。每次 rename 文件或变量，记得同步检查所有引用处——连 @use 后面那个单引号里的字符串，都得盯一眼。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
