Next.js项目引入Bootstrap 5 JS模块出现document未定义报错的原因排查
报错核心根因
ReferenceError: document is not defined 的触发本质是 Next.js 服务端渲染阶段的环境边界和 Bootstrap JS 的运行依赖不匹配:
- Next.js 运行流程包含服务端渲染环节,该环节代码执行在 Node.js 环境,不存在浏览器专属的
window、document等 DOM 全局对象。 - 你在
_app.js文件顶层导入 Bootstrap 的 JS 模块时,导入逻辑会在服务端渲染阶段被同步执行;而 Bootstrap 的 JS 模块从加载伊始就会直接访问document完成 DOM 适配初始化,Node.js 环境没有该变量,自然直接抛出未定义错误。 - 你尝试的几种不同导入路径的写法,本质上都没有解决服务端执行的问题——只要导入语句写在
_app.js的顶层作用域,不管路径怎么写,都会在服务端渲染时被加载执行,最终触发一样的报错。 - 你导入自定义 SCSS 没有报错,是因为 SCSS 会被编译为纯静态 CSS 资源,整个编译、加载流程完全不涉及 DOM 操作,不会触发环境依赖冲突。
正确的实现方式
要完全规避这类报错,不能在文件顶层同步导入 Bootstrap 的 JS 逻辑,必须让这段代码只在浏览器客户端环境执行:
- 移除文件顶层所有 Bootstrap JS 的导入语句,改用
useEffect钩子动态加载:useEffect的回调逻辑仅会在浏览器客户端 hydration 阶段执行,服务端渲染时完全不会运行这段代码,从根源上避免 Node.js 环境下访问 DOM 对象的问题。
示例代码:// src/pages/_app.js import "../custom.scss" import { useEffect } from "react" function RootApp({ Component, pageProps }) { // 仅在客户端环境执行模块导入 useEffect(() => { import("bootstrap/dist/js/bootstrap.bundle.min.js") }, []) return <Component {...pageProps} /> } export default RootApp - 导入路径直接使用包名相对路径即可,不需要手动拼接
node_modules的绝对路径,webpack 会自动完成模块解析。 - 如果后续需要调用 Bootstrap 组件的 JS 方法(如模态框、折叠面板的实例方法),等客户端加载完成后再动态引入对应的组件类即可,不要在文件顶层同步导入。
内容的提问来源于stack exchange,提问作者Hypno
相关产品推荐
相关产品推荐

