SCSS在Windows和macOS下编译不一致的根本原因是路径分隔符、行尾符（CRLF/LF）及文件系统大小写敏感性三者叠加导致解析差异，尤其影响@import/@use路径解析、变量定义和AST生成。
SCSS 在 Windows 和 macOS 下编译出的 CSS 不一致，根本原因不是操作系统“本身”，而是构建工具链中路径分隔符、行尾符（CRLF vs LF）、文件系统大小写敏感性这三者叠加导致的解析差异——尤其当项目混用 @import、相对路径别名或第三方库时，sass 解析器对路径的 normalize 行为在不同系统上会产出不同 AST。
Windows/macOS 路径分隔符引发的 @import 失败
SCSS 的 @import 对路径敏感：@import "./components/button.scss" 在 macOS 上能正常解析，但在 Windows 下可能因反斜杠 被误读为转义字符而报 file to import not found；更隐蔽的是，某些构建工具（如旧版 Webpack）会把 path.join(__dirname, 'styles') 生成带 的字符串传给 sass-loader，而 Dart Sass 默认只识别正斜杠 /。
- 统一用正斜杠：所有
@import和@use中的路径都显式写成./components/button.scss，避免path.resolve()动态拼接 - 配置 sassOptions.alias（Vite/Webpack）时，值必须是正斜杠路径：
{ '~': './src/styles' }，不能写成{ '~': '.\src\styles' } - 检查 node_modules 中第三方 SCSS 包（如 bootstrap）是否含 Windows 风格路径引用——这类包需手动 patch 或换用官方推荐的
@use方式引入
行尾符（CRLF/LF）导致的变量解析错乱
Windows 默认保存文件为 CRLF（
），macOS/Linux 为 LF（
）。Dart Sass 在解析 $var: value; 时，若换行符被截断或误判，可能导致 invalid css after "" 或 undefined variable —— 特别是在多行注释、嵌套 map 定义或 mixin 参数列表末尾。
- 项目根目录加
.gitattributes强制统一行尾：* text=auto eol=lf - 编辑器（VS Code）启用 “Ensure Newline at End of File” + “Files: EOL = ”
- 避免在变量赋值后紧跟 Windows 风格空行：
$color: #fff; $size: 12px;→ 改为单个
大小写敏感性让 @use 别名失效
macOS 文件系统默认不区分大小写（APFS），Windows（NTFS）也不区分，但 Linux（ext4）严格区分。当你写 @use '@/styles/vars' as v;，而实际文件是 VARS.scss，Dart Sass 在 Linux CI 环境下会直接报 Can't find stylesheet，本地 macOS 却能“侥幸”通过。
立即学习“前端免费学习笔记（深入）”；
- 所有文件名和
@use路径全部小写+短横线：_variables.scss，引用写@use '@/styles/_variables' as vars; - 禁用 IDE 自动首字母大写的文件创建行为（WebStorm/VS Code 设置里关掉 “Auto-capitalize filenames”）
- CI 流水线（GitHub Actions）明确指定 runner 为
ubuntu-latest，早于 macOS-latest 暴露问题
node-sass 与 dart-sass 的除法语法分歧加剧系统差异
旧项目若仍用 node-sass，其 libsass 引擎允许 width: $col / 12; 这种除法；但 Dart Sass（当前默认）要求显式调用 math.div($col, 12)。Windows 开发者常因全局装了旧版 CLI 而本地编译成功，macOS CI 用新版则失败——表面是系统差异，实则是引擎版本错位。
- 删掉
node-sass，统一用sass（Dart Sass）：npm uninstall node-sass && npm install -D sass - 全局搜索项目中所有
/除法，替换为math.div()（注意先@use 'sass:math';） - 在
vite.config.js或webpack.config.js中显式声明implementation: require('sass')，防止 fallback 到残留的 node-sass
最易被忽略的点：你以为改了路径就能跨系统一致，但 Dart Sass 的 @use 解析顺序依赖文件系统遍历结果——而 NTFS/APFS/ext4 对同目录下文件的排序可能不同，导致 @use 的变量覆盖顺序不一致。解决方式只有一条：不要依赖隐式加载顺序，所有依赖显式 @use 并按需 with 覆盖。
