npm run css 报错主因是环境或路径问题：Node.js 版本需≥18，须在克隆的Bootstrap根目录执行npm install；@import失败需配置includePaths；变量覆盖须置于所有@import前；自定义工具类需显式引入utilities并运行npm run css。
直接运行 npm run css 报错，大概率不是你写错了变量，而是环境或路径没对上——Bootstrap 官方仓库的构建脚本对 Node.js 版本、node_modules 结构和工作目录非常敏感。
Node.js 版本不匹配导致 npm install 失败或 npm run css 报 engines.node 错误
Bootstrap 5.3+ 要求 Node.js ≥ 18，低于该版本会卡在 npm install 阶段，或运行 npm run css 时提示 The engine "node" is incompatible with this module。
- 运行
node -v确认版本；若低于v18.0.0，必须升级（推荐用nvm管理） - 不要在
node_modules/bootstrap目录下执行npm install—— 这里是只读的，且无完整package.json构建脚本 - 正确做法：先
git clone https://github.com/twbs/bootstrap.git，进克隆目录后再npm install
@import "bootstrap/scss/bootstrap.scss" 找不到文件
常见于 Webpack/Vite 项目中手动 @import 但未配置 includePaths 或路径解析失败，报错类似 File to import not found。
- Webpack +
sass-loader：必须在loaderOptions.sass中加includePaths: ["node_modules"]，否则@import "bootstrap/scss/bootstrap"无法解析 - Vite：不支持
~别名（Bootstrap 5.3+ 启用了package.json#exports），优先用includePaths，或确保css.preprocessorOptions.sass.additionalData中的路径能被 Vite 正确解析（如@import "./src/styles/variables.scss"） - 命令行用
sassCLI：必须显式传--load-path=node_modules，否则同样报找不到
改了 $primary 但编译后仍是默认蓝
根本原因：变量声明顺序错，或构建工具没把你的覆盖文件注入 SCSS 上下文。本地 dev 看起来正常，build 后失效，基本可锁定为注入问题。
立即学习“前端免费学习笔记（深入）”；
- 变量必须写在所有 Bootstrap
@import之前，且不能放在bootstrap/scss/variables.scss里（下次yarn upgrade就丢） - Vite 项目：确认
vite.config.js中css.preprocessorOptions.sass.additionalData已启用，并指向你自己的variables.scss（仅含变量声明，不含@import） - Webpack 项目：检查
vue.config.js或webpack.config.js中sass-loader的additionalData是否用了 Webpack 可解析的路径（如@/styles/variables.scss），而非相对路径 - 别漏装
sass：Vite/Webpack 若没检测到sass包，会静默跳过 SCSS 编译，直接当普通 CSS 处理
自定义 $utilities 后没生成对应类
写了 "text-brand": ( property: color, values: (brand: #2563eb) )，但最终 CSS 里搜不到 .text-brand —— 不是语法错，是编译链断了。
- 必须确保
@import "bootstrap/scss/utilities"（或至少utilities/api）被显式引入，否则@include theme-colors()或 utility 循环不会执行 - 新增主题色（如
custom-blue）要生效，光往$theme-colors里加不够，还得调@include theme-colors() - 没运行
npm run css或npm run dist：保存.scss文件不会自动触发编译，这是最常被忽略的一环 - 浏览器缓存干扰：编译后记得硬刷新（
Ctrl+Shift+R），或检查 DevTools 的 Network 面板，确认加载的是新生成的 CSS 文件，而非旧缓存
真正卡住人的地方往往不在 Sass 语法本身，而在构建链路是否完整接通——从 Node 版本、includePaths 配置、additionalData 注入，到最终有没有手动触发编译命令，每一步都可能静默失败。
