Vite 项目中优雅集成与打包 Bootstrap 5（CSS + JavaScript 完整指南）

引言

Vite 作为新一代前端构建工具，以其极快的冷启动和热更新速度深受开发者喜爱。而 Bootstrap 作为最流行的 CSS 框架之一，仍然是很多中后台、管理系统、快速原型项目的首选。

然而，将 Bootstrap 正确集成到 Vite 项目中并非简单地复制 CDN 链接或 npm install 就完事。错误的集成方式会导致：

JS 交互组件（如下拉菜单、模态框）失效
CSS 体积过大，未 tree-shaking
SCSS 变量自定义不生效
生产环境打包后出现警告或路径问题

本文将展示2026 年仍然推荐的、最稳定的集成方式，并覆盖自定义主题、生产优化等进阶内容。

1. 初始化 Vite 项目（以 Vanilla 为例）

# 创建项目（可选择 vanilla、vue、react 等模板）
npm create vite@latest my-bootstrap-app -- --template vanilla

cd my-bootstrap-app

npm install

2. 安装 Bootstrap 及其依赖

# Bootstrap 5 主包 + Popper（用于下拉、popover 等定位）
npm install bootstrap @popperjs/core

如果你需要自定义主题（强烈推荐），额外安装 Sass：

npm install -D sass

3. 项目结构建议（推荐）

my-bootstrap-app/
├── src/
│   ├── js/
│   │   └── main.js          # 入口 JS，引入 Bootstrap JS
│   ├── scss/
│   │   ├── _variables.scss  # 自定义变量（可选）
│   │   └── styles.scss      # 主样式文件，引入 Bootstrap
│   ├── index.html
│   └── main.js             # vite 默认入口（可删除或合并）
└── vite.config.js

4. 引入 Bootstrap 的 CSS（推荐 SCSS 方式）

src/scss/styles.scss

// 1. 先定义自定义变量（可选，但强烈建议）
@import "variables";

// 2. 引入 Bootstrap（只加载需要的部分也可）
@import "bootstrap/scss/bootstrap";

// 或者更精细控制（按需加载，体积更小）
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
// ... 根据需要选择引入的组件
@import "bootstrap/scss/root";
@import "bootstrap/scss/reboot";
// 继续引入其他模块...
@import "bootstrap/scss/utilities";
@import "bootstrap/scss/type";
@import "bootstrap/scss/images";
// ...
@import "bootstrap/scss/grid";
@import "bootstrap/scss/buttons";
// 最后引入所有组件或用 @import "bootstrap/scss/bootstrap";

自定义变量示例 src/scss/_variables.scss

$primary: #0d6efd;           // 保持原色或修改
$enable-shadows: true;
$border-radius: 0.4rem;
$font-family-base: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;

// 自定义主题色
$custom-theme: (
  "primary": #5a67d8,
  "secondary": #e2e8f0,
);

$theme-colors: map-merge($theme-colors, $custom-theme);

5. 在 vite.config.js 中配置 SCSS 支持（通常无需额外配置）

Vite 原生支持 Sass，无需额外插件。但如果你遇到路径或警告问题，可做如下微调：

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/scss/variables" as *;`, // 可选：全局变量
        silenceDeprecations: ["legacy-js-api"], // 2025+ 常用，消除旧 API 警告
      }
    }
  },
  resolve: {
    alias: {
      '@': '/src'   // 方便路径引用
    }
  }
})

6. 引入 Bootstrap 的 JavaScript

src/js/main.js（或直接放在 src/main.js）

// 方式一：引入全部 JS（推荐大多数场景）
import 'bootstrap'

// 方式二：按需引入（体积更小，需要的组件自己 import）
import {
  Tooltip,
  Toast,
  Modal,
  Dropdown
} from 'bootstrap'

// 示例：初始化所有 tooltip
document.querySelectorAll('[data-bs-toggle="tooltip"]')
  .forEach(el => new Tooltip(el))

7. 修改 index.html 引入样式和脚本

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Vite + Bootstrap</title>
  
  <!-- Vite 会自动处理 -->
  <link rel="stylesheet" href="/src/scss/styles.scss">
</head>
<body>
  <div class="container my-5">
    <h1 class="text-primary">Hello Vite + Bootstrap 5!</h1>
    
    <button type="button" class="btn btn-primary" data-bs-toggle="tooltip" data-bs-title="Tooltip on top">
      Hover me
    </button>
  </div>

  <script type="module" src="/src/js/main.js"></script>
</body>
</html>

8. 启动 & 打包验证

# 开发
npm run dev

# 生产打包
npm run build

# 预览打包结果
npm run preview

9. 常见问题 & 解决方案（2026 视角）

问题	原因	解决方式
下拉菜单/模态框不工作	未引入 Popper 或 JS 未加载	`npm i @popperjs/core` 并 `import 'bootstrap'`
SCSS 变量不生效	变量文件未被先导入	把变量文件放在 `@import "bootstrap/scss/bootstrap";` 之前
打包后体积过大	引入全部 Bootstrap	使用按需加载或 `vite-plugin-purgecss`
Deprecation 警告	Bootstrap/Sass 新旧 API	`silenceDeprecations: ["legacy-js-api"]`
路径别名 @ 不生效	未配置 alias	在 `vite.config.js` 中添加 alias