@debug 仅在编译成功后运行，用于验证计算逻辑，如 map-get 返回值、@each 遍历、@if 分支等；若编译出错（语法错误、未定义变量、map 参数非法），则根本不会执行。
@debug 不是用来“排查编译错误”的，它只在编译成功后运行，专为验证计算逻辑是否符合预期——比如 map-get() 返回值不对、@each 漏遍历、@if 分支没进对、百分比算成 0% 等。
为什么 @debug 没输出？先看终端红字报错
很多人加了 @debug $val 却没看到输出，第一反应是“指令失效”，实际几乎全是编译提前中断了：
-
$color: #ff0少分号 → 语法错误，@debug根本没机会执行 -
@debug $undefined-var→ 直接报Undefined variable "$undefined-var"，流程终止 -
@debug map-get($config, 'breakpoints')中$config是null→ Dart Sass 报Argument '$map' of 'map-get' must be a map
结论：红字没清完，@debug 就是哑的。别把它当探针，它连编译门槛都过不去。
@debug 打在哪才真正有用？
打在“值刚算出来、还没被赋给变量或塞进 CSS”的位置，而不是最后 @return 前。常见有效点：
- 在
@function内部每步运算后：@debug "scaled:", $scaled; - 在
@if分支开头，而非只在@else里补一句：@if $mode == dark { @debug "[dark] triggered"; } - 查
@each $key, $val in $map时，别只打$key：@debug "key: #{$key}, val: #{$val}";，否则容易把sm和480px当同一层 - 对
map必须用map-get()提取再 debug：@debug "md:", map-get($breakpoints, md);，直接@debug $breakpoints只会输出(sm: 480px, md: 768px)这种字符串，看不出结构
终端看不到输出？检查构建工具配置
@debug 默认写入 stderr，多数构建工具会静默丢弃它：
- CLI 直跑必须加
--trace：sass --trace src/main.scss dist/main.css，不加可能完全不显示 - Webpack 项目需在
sass-loader的sassOptions里显式开verbose: true，否则被吞掉 - VS Code 的 Live Sass Compiler 插件完全不支持
@debug——它不走 Dart Sass CLI，得切回命令行
上线前不删 @debug 会怎样？
它不会污染 CSS，也不会影响浏览器，但会污染 CI/CD 日志、干扰团队排查、暴露内部逻辑路径。更麻烦的是：CI 脚本若用了 sass --quiet 或重定向了 stdout，@debug 就彻底消失；而某些团队误以为它能拦截运行时问题，其实它只是编译期单次快照——值对不对，只取决于那一刻的输入和上下文，不带状态、不重试、不兜底。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
