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

引言#

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

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

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

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

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

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

4
cd my-bootstrap-app
5

6
npm install

2. 安装 Bootstrap 及其依赖#

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

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

1
npm install -D sass

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

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

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

src/scss/styles.scss

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

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

7
// 或者更精细控制（按需加载，体积更小）
8
@import "bootstrap/scss/functions";
9
@import "bootstrap/scss/variables";
10
@import "bootstrap/scss/maps";
11
@import "bootstrap/scss/mixins";
12
// ... 根据需要选择引入的组件
13
@import "bootstrap/scss/root";
14
@import "bootstrap/scss/reboot";
15
// 继续引入其他模块...
16
@import "bootstrap/scss/utilities";
17
@import "bootstrap/scss/type";
18
@import "bootstrap/scss/images";
19
// ...
20
@import "bootstrap/scss/grid";
21
@import "bootstrap/scss/buttons";
22
// 最后引入所有组件或用 @import "bootstrap/scss/bootstrap";

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

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

6
// 自定义主题色
7
$custom-theme: (
8
  "primary": #5a67d8,
9
  "secondary": #e2e8f0,
10
);
11

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

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

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

1
import { defineConfig } from 'vite'
2

3
export default defineConfig({
4
  css: {
5
    preprocessorOptions: {
6
      scss: {
7
        additionalData: `@use "@/scss/variables" as *;`, // 可选：全局变量
8
        silenceDeprecations: ["legacy-js-api"], // 2025+ 常用，消除旧 API 警告
9
      }
10
    }
11
  },
12
  resolve: {
13
    alias: {
14
      '@': '/src'   // 方便路径引用
15
    }
16
  }
17
})

6. 引入 Bootstrap 的 JavaScript#

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

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

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

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

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

1
<!doctype html>
2
<html lang="zh-CN">
3
<head>
4
  <meta charset="utf-8">
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
  <title>Vite + Bootstrap</title>
7

8
  <!-- Vite 会自动处理 -->
9
  <link rel="stylesheet" href="/src/scss/styles.scss">
10
</head>
11
<body>
12
  <div class="container my-5">
13
    <h1 class="text-primary">Hello Vite + Bootstrap 5!</h1>
14

15
    <button type="button" class="btn btn-primary" data-bs-toggle="tooltip" data-bs-title="Tooltip on top">
16
      Hover me
17
    </button>
18
  </div>
19

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

8. 启动 & 打包验证#

1
# 开发
2
npm run dev
3

4
# 生产打包
5
npm run build
6

7
# 预览打包结果
8
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