Bootstrap框架源码编译环境搭建

Bootstrap框架源码编译环境搭建需要先看清适用场景和关键步骤，避免只记结论却忽略实际限制。

直接 npm install bootstrap 不提供源码编译环境，因官方 npm 包仅含编译后文件及 source map，不含 SCSS/JS 源码、构建脚本；需 git clone 仓库并 npm install 才能运行 npm run dist 等命令。

为什么直接 npm install bootstrap 不等于源码编译环境

因为官方发布的 bootstrap npm 包里只有编译好的 CSS/JS 文件和源映射，scss、js 源码、构建脚本（package.json 中的 build、dist 等 script）默认不包含在内。想改变量、删组件、调试 Sass 编译流程，必须克隆完整仓库。

用 git clone + npm install 搭建可编译源码环境

Bootstrap 官方仓库主分支（main）是开发态，含全部构建依赖；v5.3 这类版本标签才是发布快照。别用 npm install [email protected] 后试图去 node_modules/bootstrap 里找 package.json —— 它没有 scripts 字段，也跑不了 npm run dist。

1. 执行 git clone https://github.com/twbs/bootstrap.git，进目录后 npm install
2. 确保已安装 node ≥ 18（package.json 的 engines.node 要求），否则 npm install 会警告或失败
3. npm run dist 生成 dist/ 下的完整产物；npm run css 只编译样式，更快，适合只调 Sass 变量时用
4. 若报错 Cannot find module 'sass'，说明 node-sass 已弃用，Bootstrap 5.3+ 强制用 sass（Dart Sass），需确认 node_modules/sass 存在且为 v1.60+

修改 _variables.scss 后不生效？检查三个关键点

改了 scss/_variables.scss 里的 $primary 却发现 dist/css/bootstrap.css 没变，大概率卡在这三处：

1. 没运行 npm run css 或 npm run dist，仅保存文件不会自动编译
2. 改的是 scss/_variables.scss，但项目里 @import 的是 scss/bootstrap.scss —— 它内部已通过 @import "functions"; @import "variables"; 加载，没问题；但如果自己新建入口文件漏掉了 @import "variables"，那修改就白做了
3. 浏览器缓存了旧 CSS：用 npm run serve 启的服务默认不带 cache busting，强制刷新（Cmd+Shift+R）或关掉 DevTools 的 “Disable cache”

Windows 下编译失败常见于 Python 和 Git Bash 环境

Bootstrap 构建脚本（如 script/build-css.js）调用 git 命令获取版本号，且部分 Node.js 子进程 spawn 依赖 POSIX 环境。在 Windows 上容易遇到：

1. Error: spawn git ENOENT：系统 PATH 里没加 Git 的 bin 目录（如 C:Program FilesGitbin）
2. ReferenceError: process is not defined：用 Webpack/Vite 直接打包 Bootstrap JS 源码时，未正确 polyfill process.env —— 这不是编译环境问题，而是你把它当模块引入时的运行时问题，别混在一起排查
3. 推荐用 Git Bash 运行 npm run dist，避免 PowerShell 或 CMD 因路径分隔符（ vs /）或 shell 内置命令差异导致脚本中断

Bootstrap 源码编译本身不复杂，难的是区分“我在改源码”和“我在用成品”。一旦开始动 scss/ 或 js/src/，就必须走完整 clone → install → build 流程，任何想绕过这步的尝试，最后都会卡在某个找不到的 require 或空的 dist/ 目录里。