You need to enable JavaScript to run this app. Next.js项目引入Bootstrap 5 JS模块出现document未定义报错的原因排查
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.11 00:24:03