@debug 输出仅限终端 stderr，需用 CLI 运行、禁用静默模式并确保 Dart Sass 版本；支持所有 Sass 类型但对未定义变量敏感，须用 variable-exists() 防错；调试应加模块前缀、避免深层嵌套直输、慎用 @warn/@error。
@debug 输出不到终端？先确认编译器和运行方式
@debug 的输出只出现在终端（stderr），不会进浏览器控制台，也不是 CSS 的一部分。如果你用 VS Code Live Server、CodePen 或直接双击打开 .css 文件，永远看不到它——因为编译早已完成。常见误操作包括：启动 npm run dev 但没盯住终端滚动日志；用了不支持 @debug 的旧版 Node Sass（已停更）；或者改了被 @use 引入但未实际参与编译的文件。
实操建议：
立即学习“前端免费学习笔记（深入）”；
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 命令行直接跑：
sass --trace src/main.scss dist/main.css，确保看到@debug行立即输出 - Webpack 项目需在
sass-loader配置里显式启用：sassOptions: { verbose: true } - Vite 用户检查是否启用了
css.devSourcemap并确认没有加--quiet参数 - VS Code 插件（如 Live Sass Compiler）默认不支持
@debug，必须切回 CLI
@debug 能打印什么，怎么避免报错中断编译
@debug 支持所有 Sass 原生类型：数字、颜色、字符串、列表、映射、布尔值、null，甚至函数调用结果（如 lightness($color)）。但它对未定义变量或 null 值极其敏感：写 @debug $undefined-var 会直接报错并终止编译，不是静默跳过。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 调试前先用
variable-exists()判定变量是否存在：@if variable-exists(theme-color) { @debug "theme-color:", $theme-color; } - 插值必须用引号包裹：
@debug "mode is #{$mode}";✅，@debug "mode is" $mode;❌（语法错误） - 别直接
@debug $config-map，深层嵌套 map 输出不可读；改用@debug "breakpoints:", map-get($config-map, breakpoints); - 函数内调试优先打中间值：
@debug "calculated width:", $width;，而不是只打最终返回值
在 @if / @each / @mixin 里怎么用 @debug 定位逻辑分支
条件判断和循环是最容易出错的地方，比如断点计算偏差、主题色派生失败、列表遍历漏项。@debug 的价值在于让每个分支“开口说话”，而不是靠猜哪条路径被执行。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 每个
@if分支开头加@debug，带明确前缀便于区分：@debug "[header] using dark mode"; -
@each循环中不要只打索引，要打键值对：@each $name, $size in $font-sizes { @debug "font #{$name}: #{$size}"; } - 在
@mixin入口处立刻@debug所有参数：@mixin button($variant: primary) { @debug "button mixin called with:", $variant; ... } - 避免在
@at-root或嵌套过深块里写@debug后又删掉——它可能影响作用域解析，导致后续变量引用失效
@debug 和 @warn / @error 混用时的关键区别
三者都输出到终端，但行为完全不同：@debug 是纯开发者日志，不影响流程；@warn 是黄色警告，编译继续，适合提示废弃参数；@error 是红色中断，强制失败，用于校验硬性约束（如必填参数缺失）。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 别用
@warn替代@debug查中间值——CI/CD 日志过滤常屏蔽警告，且 IDE 不高亮@warn输出 -
@error别乱用在公共@function里，下游项目一调就崩；应限定在输入合法性校验层，如@if not map-has-key($map, $key) { @error "Key #{$key} not found in map"; } - Dart Sass 默认把
@debug输出到 stderr，@warn输出到 stdout，管道处理时注意重定向目标（例如sass src/ | grep debug捕获不到） - 上线前无需手动删
@debug——Webpack/Vite 等构建工具在 production 模式下默认剥离，不影响最终 CSS
@use + @forward 场景下，不同模块的调试信息会混在一起，没加前缀几乎无法分辨来源。调试复杂主题系统时，第一件事不是看值对不对，而是先统一加 [module-name] 前缀。 
