迁移遗留项目至Webpack后Bootstrap 5 JS API调用失败求助

架构老林

2026-7-9

问题分析与解决

问题原因

Bootstrap 5 jQuery兼容逻辑：Bootstrap 5不会自动将JS插件挂载到jQuery原型链，仅当检测到全局环境中的window.jQuery时，才会启用jQuery兼容模式，将modal这类方法绑定到$对象。
Popper依赖不匹配：当前配置使用旧版popper.js，但Bootstrap 5依赖的是@popperjs/core，依赖错误会导致Bootstrap JS加载异常。
Webpack模块隔离：Webpack默认的模块作用域是隔离的，即便通过ProvidePlugin注入了$和jQuery，若未显式暴露到window，Bootstrap无法检测到全局jQuery实例，也就不会挂载对应插件方法。

解决方法

步骤1：替换Popper依赖

卸载旧版依赖，安装Bootstrap 5要求的Popper包：

npm uninstall popper.js
npm install @popperjs/core --save

步骤2：修改Webpack配置

更新ProvidePlugin，替换Popper路径并将jQuery暴露到全局window：

plugins: [
    new webpack.ProvidePlugin({
        $: require.resolve('jquery'),
        jQuery: require.resolve('jquery'),
        'window.jQuery': require.resolve('jquery'), // 新增：将jQuery挂载到window
        Popper: ['@popperjs/core', 'default'], // 替换为正确的Popper包
    }),
],

步骤3：调整Bootstrap导入方式

方式1：继续使用jQuery调用Bootstrap方法

确保Bootstrap在全局jQuery存在后再导入：

import './styles.scss'
require('bootstrap-icons/font/bootstrap-icons.css');

// 手动挂载jQuery到window（若Webpack配置的window.jQuery未生效）
window.jQuery = window.$ = require('jquery');
// 导入Bootstrap，此时会自动绑定jQuery插件
import 'bootstrap';

$('#staticBackdrop').modal()

方式2：使用Bootstrap原生API（无需jQuery）

如果不需要依赖jQuery，可直接调用Bootstrap原生API：

import './styles.scss'
require('bootstrap-icons/font/bootstrap-icons.css');
import { Modal } from 'bootstrap';

const modalElement = document.getElementById('staticBackdrop');
const modal = new Modal(modalElement);
modal.show();