scss入口文件是模块解析起点，必须显式指定@use路径；缺失或路径错误会导致编译报错或静默失效，\_index.scss为强制契约，仅限@use子模块和@forward暴露api。
SCSS 入口文件不是“可选配置”，而是模块解析的起点
没有明确入口，构建工具就无法判断该从哪开始解析依赖链，@use 会直接报错或静默 fallback 到错误路径。SCSS 不像 JS 有 package.json#exports 的自动映射机制，它完全依赖你手写的 @use 'path/to/index' 路径来定位第一层模块。
常见错误现象：
-
Error: Can't find stylesheet to import—— 实际是入口路径写错，但错误信息不提示具体缺哪个文件 - Vite 或 Webpack 报
Failed to resolve import，而你确认文件存在 —— 很可能是因为没在目标目录下放_index.scss - 用户
@use 'my-lib/components'却只拿到空对象 ——components/_index.scss里漏了@forward 'button'或写成了@use 'button'
_index.scss 是强制契约，不是命名习惯
每个功能目录（如 components/、utilities/、themes/）必须配一个 _index.scss，且它只能做两件事：@use 子模块 + @forward 暴露 API。任何样式规则、@include 或变量赋值都禁止出现在这里。
实操建议：
-
@forward 'button' as btn-*;—— 给所有导出成员加前缀，避免和用户项目变量名冲突 - 禁用
@use 'button' as *;—— 它会把button下所有私有变量也暴露出去，破坏封装 - 不要在
_index.scss里写$color-primary: #1890ff;—— 这类值应统一收口到_variables.scss并带!default
入口路径差异直接影响 tree-shaking 和打包结果
@use 'my-lib/components/button' 和 @use 'my-lib/components' 看似只是路径长短区别，但构建时行为完全不同：前者只解析 button 目录下的 SCSS 文件，后者会遍历整个 components/ 并加载所有 @forward 的模块 —— 即使你只用了按钮，也可能把 dialog、tooltip 的样式全打进包里。
性能影响关键点：
- SCSS 的 tree-shaking 依赖静态分析
@forward链路，一旦某个_index.scss里漏了@forward或用了@use ... as *，整条链就失效 - Webpack 的
sass-loader在api: 'modern'模式下才真正支持@use的作用域隔离；旧配置会退化为全局解析 - Vite 默认启用 Dart Sass，但若项目里混入了
node_modules中含@import的第三方 SCSS 包，整个模块图都会被污染
用户侧引入路径错位，样式就彻底不会生效
用户写 @use 'my-lib'，但你的 package.json#exports 没配 "sass": "./src/index.scss"，或者配了却指向一个不存在的文件，结果就是构建时无报错、运行时无样式 —— 因为 SCSS 编译器根本没加载任何东西。
容易被忽略的细节：
-
exports字段中"sass"条件必须显式声明，不能依赖"main"或"types"fallback - 如果同时提供 CSS 变量主题和 SCSS 主题，
_index.scss里不能直接@use 'theme/dark'，而应通过@use 'theme' with ($mode: 'dark')参数注入，否则 dark 主题会被无条件编译进去 - 发布前必须验证
npm pack后的 tarball 是否包含所有_index.scss和被@forward的文件 —— 常见疏漏是.npmignore误删了_*.scss
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
