@debug 仅在编译成功后输出调试信息，无法排查语法错误、未定义变量等导致的编译失败；它适用于定位逻辑错误，需配合构建工具配置（如--trace或verbose: true）才能显示，且上线前应清理。
@debug 本身不会排查编译错误，它只在编译成功时输出调试信息；遇到语法错误、未定义变量或类型不匹配等真正报错时，@debug 根本不会执行——编译已在它之前中断了。
为什么 @debug 没输出，其实多半是编译失败了
很多人盯着终端等 @debug 输出，结果什么也没看到，第一反应是“指令没生效”，但真实情况往往是：Sass 在碰到 @debug 前就因其他错误退出了。比如：
-
$color: #ff0;后面少了个分号 → 语法错误，编译终止，@debug $color永远不会运行 -
@debug $undefined-var→ 直接触发语义错误，报Undefined variable "$undefined-var"，流程立刻停止 -
@debug map-get($config, 'breakpoints')中$config是null→ Dart Sass 1.30+ 会明确报错Argument '$map' of 'map-get' must be a map
实操建议：先解决终端里红色报错行，再加 @debug；不要把它当万能探针，它连编译门槛都过不去。
用 @debug 定位逻辑错误（不是语法错误）
当 CSS 输出不符合预期，但编译无报错——比如主题色没变、断点值错乱、@each 漏遍历——这才是 @debug 的主战场。关键是要打在“计算发生的位置”，而不是结果赋值后。
立即学习“前端免费学习笔记（深入）”；
- 在
@function内部每一步计算后加：@debug "after scale:", $scaled-value; - 在
@if分支开头打，而非只在最终@return前：@if $mode == dark { @debug "[theme] dark mode triggered"; ... } - 查
@each时别只打索引：@debug "key: #{$key}, value: #{$val}";，避免把sm和480px当成同一层 - 对 map 值务必用
map-get()提取再 debug：@debug "md breakpoint:", map-get($breakpoints, md);，而非@debug $breakpoints;
终端看不到 @debug 输出？检查这三件事
@debug 只写入 stderr，且默认被多数构建工具静默丢弃。不是你的代码有问题，是环境没配对。
- CLI 直跑必须带
--trace：sass --trace src/main.scss dist/main.css（不加可能完全不显示） - Webpack 项目需在
sass-loader的sassOptions里显式开verbose: true，否则@debug被吞掉 - VS Code 的 Live Sass Compiler 插件完全不支持
@debug——它走的是自己封装的编译器，和 Dart Sass CLI 行为不同，必须切回命令行
上线前不删 @debug 会怎样？
它不会污染 CSS，也不会影响浏览器运行，但会污染 CI/CD 日志、干扰团队排查、暴露内部逻辑路径。更麻烦的是：某些旧版构建配置（如部分 Gulp sass 插件）会把 @debug 当警告处理，导致 PR 检查失败。 不要依赖“反正不影响样式”就留着——它本质是开发期日志，和 console.log 一样该清理。Dart Sass 默认不输出 @debug，但别赌配置没被改过。
