@forward 是声明模块出口的接口机制，不加载执行也不生成 CSS，仅暴露底层模块的变量、mixin、function 和占位符选择器；它不能替代 @use，因自身不引入符号，聚合文件中不可写实际 CSS 规则。
直接说结论：@forward 不是用来“组织模块”的工具，而是用来“声明模块出口”的接口机制。它本身不加载、不执行、不生成 CSS，只负责把底层模块的变量、@mixin、@function 和占位符选择器，按你指定的方式暴露给上游使用者。想靠它“整理目录”或“自动合并样式”，一定会踩坑。
为什么 @forward 不能替代 @use 直接使用
@forward 是纯声明，不是加载行为。你在 _index.scss 里写 @forward "mixins"，不代表这个文件能用 fluid-type() —— 它自己没 @use 过 mixins，变量和函数根本不可见。
- 常见错误：在聚合文件里只写
@forward，然后试图写顶层 CSS 规则（比如.btn { ... }），结果编译报Undefined variable或Invalid CSS - 正确做法：聚合文件（如
_index.scss）只做转发；真正要写样式的地方，必须@use入口（如@use "ui"），再通过命名空间调用，例如ui.$spacing-sm - 性能影响：多个组件都
@use "ui"，Sass 内部只解析一次，但若每个组件都@use "mixins"+@use "vars"，就失去聚合意义，也容易漏掉统一配置（如主题色）
@forward 路径必须严格对齐文件系统
SCSS 不支持路径别名或包映射。@forward "core/vars" 就必须真实存在 core/_vars.scss 或 core/_vars/index.scss；写错一个点、少一个下划线、多一个 .scss 后缀，立刻报 Can't find stylesheet to import。
- 常见错误：想用
@forward "core"一次性导出整个文件夹 → 不行，SCSS 不支持目录级转发 - 正确结构：建
core/_index.scss，里面写@forward "vars"、@forward "mixins"；主入口再@forward "core/index" - VS Code 插件跳转失效？八成是路径拼错，不是插件问题；改完路径后建议重启构建进程，避免缓存干扰
用 hide、show、as 控制暴露粒度
默认 @forward "x" 会把 _x.scss 所有公开符号全透出，这在中大型项目里极危险——内部调试函数、未完成的断点变量、实验性 mixin 都可能被下游误用。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
立即学习“前端免费学习笔记（深入）”；
-
@forward "utils" hide debug-log, _internal-helper;→ 下游@use "ui"后完全看不到这两个名字 -
@forward "breakpoints" as bp-*;→ 下游只能写bp-max("md")，无法知道源文件路径，也避免和grid-max()冲突 -
@forward "buttons" show button-base, button-size;→ 只暴露设计为公共 API 的部分，其余全部隔离 -
hide和show互斥，不能同时用；as *表示不加前缀，但仅限当前@forward生效
聚合入口文件里不能写实际 CSS 规则
只要 @forward 的目标文件（如 _reset.scss）里有顶层 CSS（* { margin: 0 }），这些规则仍会输出——但不是由 @forward 注入，而是等下游 @use 它时才生效。如果聚合文件自己写了规则，会导致重复注入。
- 典型反模式：
_ui/index.scss里@forward "base/reset"+ 自己写.container { ... }→ 构建后* { margin: 0 }可能出现多次 - 正确分层：
_base/reset.scss放规则；_base/reset-api.scss只@forward "reset"（无 CSS）；聚合文件只转发reset-api - 循环依赖报错
Circular forward dependency？说明两个模块互相@forward，得拎出第三个中转模块（如_shared/index.scss）来解耦
最易被忽略的一点：所有 @forward 都是静态声明，编译期就确定了导出内容。它不支持运行时条件判断、动态路径拼接或基于环境变量的开关——如果你需要主题切换、品牌定制这类能力，必须配合 @use "theme" with ($mode: dark) 显式传参，而不是指望 @forward 自动识别上下文。
